API Management のポリシーにおけるエラー処理Error handling in API Management policies

Azure API Management では、パブリッシャーは ProxyError オブジェクトを指定することにより、要求の処理中に発生するエラーに対応することができます。By providing a ProxyError object, Azure API Management allows publishers to respond to error conditions, which may occur during processing of requests. ProxyError オブジェクトは context.LastError プロパティからアクセスでき、on-error ポリシー セクションのポリシーで使用できます。The ProxyError object is accessed through the context.LastError property and can be used by policies in the on-error policy section. この記事では、Azure API Management におけるエラー処理機能向けの参考資料を提供します。This article provides a reference for the error handling capabilities in Azure API Management.

API Management でのエラー処理Error handling in API Management

Azure API Management のポリシーは、次の例で示すとおり、inboundbackendoutbound、および on-error のセクションに分かれています。Policies in Azure API Management are divided into inbound, backend, outbound, and on-error sections as shown in the following example.

<policies>  
  <inbound>  
    <!-- statements to be applied to the request go here -->  
  </inbound>  
  <backend>  
    <!-- statements to be applied before the request is   
         forwarded to the backend service go here -->  
    </backend>  
    <outbound>  
      <!-- statements to be applied to the response go here -->  
    </outbound>  
    <on-error>  
        <!-- statements to be applied if there is an error   
             condition go here -->  
  </on-error>  
</policies>  

要求の処理中、要求のスコープ内にあるすべてのポリシーと共に組み込みの手順が実行されます。During the processing of a request, built-in steps are executed along with any policies, which are in scope for the request. エラーが発生すると、処理は直ちに on-error ポリシー セクションにジャンプします。If an error occurs, processing immediately jumps to the on-error policy section.
on-error ポリシー セクションは、任意のスコープで使用できます。The on-error policy section can be used at any scope. API パブリッシャーは、イベント ハブへのエラーの記録や、呼び出し元に戻るための新しい応答の作成などのカスタム動作を構成できます。API publishers can configure custom behavior such as logging the error to event hubs or creating a new response to return to the caller.

注意

on-error セクションは、既定ではポリシーに存在しません。The on-error section is not present in policies by default. on-error セクションをポリシーに追加するには、ポリシー エディターで目的のポリシーを参照し、このセクションを追加します。To add the on-error section to a policy, browse to the desired policy in the policy editor and add it. ポリシーを構成する方法の詳細については、「Azure API Management のポリシー」を参照してください。For more information about configuring policies, see Policies in API Management.

on-error セクションがない場合、エラーが発生すると、呼び出し元は 400 または 500 HTTP 応答メッセージを受信します。If there is no on-error section, callers will receive 400 or 500 HTTP response messages if an error condition occurs.

エラー状態で使用できるポリシーPolicies allowed in on-error

次のポリシーは、on-error ポリシー セクションで使用できます。The following policies can be used in the on-error policy section.

lastErrorLastError

エラーが発生し、コントロールが on-error ポリシー セクションにジャンプすると、エラーは context.LastError プロパティ内に格納されます。このプロパティには、on-error セクションにあるポリシーがアクセス可能です。When an error occurs and control jumps to the on-error policy section, the error is stored in context.LastError property, which can be accessed by policies in the on-error section. LastError のプロパティは次のとおりです。LastError has the following properties.

名前Name TypeType 説明Description 必須Required
Source stringstring エラーが発生した要素を指定します。Names the element where the error occurred. ポリシーまたは組み込みパイプライン ステップ名のいずれかになります。Could be either policy or a built-in pipeline step name. はいYes
Reason stringstring エラー処理に使用できる、マシンに適したエラー コード。Machine-friendly error code, which could be used in error handling. いいえNo
Message stringstring 人間が判読できるエラーの説明。Human-readable error description. はいYes
Scope stringstring エラーが発生したスコープの名前 ("global"、"product"、"api"、または "operation")Name of the scope where the error occurred and could be one of "global", "product", "api", or "operation" いいえNo
Section stringstring エラーが発生したセッション名。Section name where error occurred. 設定される可能性がある値: "inbound"、"backend"、"outbound"、"on-error"。Possible values: "inbound", "backend", "outbound", or "on-error". いいえNo
Path stringstring 入れ子になったポリシー (例: "choose[3]/when[2]") を指定します。Specifies nested policy, for example "choose[3]/when[2]". いいえNo
PolicyId stringstring エラーが発生したポリシーの id 属性の値 (顧客が指定した場合)Value of the id attribute, if specified by the customer, on the policy where error occurred いいえNo

ヒント

context.Response.StatusCode によって状態コードにアクセスできます。You can access the status code through context.Response.StatusCode.

注意

すべてのポリシーには、ポリシーのルート要素に追加できる、省略可能な id 属性があります。All policies have an optional id attribute that can be added to the root element of the policy. エラー条件が発生したときにこの属性がポリシーに存在する場合、context.LastError.PolicyId プロパティを使用して、この属性の値を取得できます。If this attribute is present in a policy when an error condition occurs, the value of the attribute can be retrieved using the context.LastError.PolicyId property.

組み込みの手順向けの定義済みエラーPredefined errors for built-in steps

次のエラーは、組み込みの処理手順の評価時に発生する可能性があるエラー条件用に定義されています。The following errors are predefined for error conditions that can occur during the evaluation of built-in processing steps.

SourceSource 条件Condition ReasonReason MessageMessage
configurationconfiguration API または操作に URI が一致しませんUri doesn't match to any API or Operation OperationNotFoundOperationNotFound 操作に受信要求を一致させることができません。Unable to match incoming request to an operation.
authorizationauthorization サブスクリプション キーが指定されていませんSubscription key not supplied SubscriptionKeyNotFoundSubscriptionKeyNotFound サブスクリプション キーがないため、アクセスが拒否されました。Access denied due to missing subscription key. この API に要求を行うときは、サブスクリプション キーを指定してください。Make sure to include subscription key when making requests to this API.
authorizationauthorization サブスクリプション キー値が無効ですSubscription key value is invalid SubscriptionKeyInvalidSubscriptionKeyInvalid サブスクリプション キーが無効なため、アクセスが拒否されました。Access denied due to invalid subscription key. アクティブなサブスクリプションへの有効なキーを指定してください。Make sure to provide a valid key for an active subscription.

ポリシーの定義済みのエラーPredefined errors for policies

次のエラーは、ポリシーの評価時に発生する可能性があるエラー条件用に定義されています。The following errors are predefined for error conditions that can occur during policy evaluation.

SourceSource 条件Condition ReasonReason MessageMessage
rate-limitrate-limit レート制限を超過Rate limit exceeded RateLimitExceededRateLimitExceeded レート制限を超過しています。Rate limit is exceeded
quotaquota クォータを超過したQuota exceeded QuotaExceededQuotaExceeded 呼び出しボリュームのクォータを超過しています。Out of call volume quota. クォータは xx:xx:xx 後に補充されます。Quota will be replenished in xx:xx:xx. または、帯域幅クォータがありません。-or- Out of bandwidth quota. クォータは xx:xx:xx 後に補充されます。Quota will be replenished in xx:xx:xx.
jsonpjsonp コールバック パラメーターの値が無効です (不正な文字が含まれています)Callback parameter value is invalid (contains wrong characters) CallbackParameterInvalidCallbackParameterInvalid コールバック パラメーター {callback-parameter-name} の値が、有効な JavaScript 識別子ではありません。Value of callback parameter {callback-parameter-name} is not a valid JavaScript identifier.
ip-filterip-filter 要求からの呼び出し元 IP の解析に失敗しましたFailed to parse caller IP from request FailedToParseCallerIPFailedToParseCallerIP 呼び出し元の IP アドレスを確立できませんでした。Failed to establish IP address for the caller. アクセスが拒否されました。Access denied.
ip-filterip-filter 呼び出し元 IP が許可リストにありませんCaller IP is not in allowed list CallerIpNotAllowedCallerIpNotAllowed 呼び出し元 IP アドレス {ip-address} は許可されていません。Caller IP address {ip-address} is not allowed. アクセスが拒否されました。Access denied.
ip-filterip-filter 呼び出し元 IP がブロック リストにありますCaller IP is in blocked list CallerIpBlockedCallerIpBlocked 呼び出し元 IP アドレスはブロックされています。Caller IP address is blocked. アクセスが拒否されました。Access denied.
check-headercheck-header 必須のヘッダーが表示されない、または値がありませんRequired header not presented or value is missing HeaderNotFoundHeaderNotFound 要求にヘッダー {header-name} がありません。Header {header-name} was not found in the request. アクセスが拒否されました。Access denied.
check-headercheck-header 必須のヘッダーが表示されない、または値がありませんRequired header not presented or value is missing HeaderValueNotAllowedHeaderValueNotAllowed ヘッダー {header-name} 値 {header-value} は許可されていません。Header {header-name} value of {header-value} is not allowed. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt JWT トークンが要求にありませんJwt token is missing in request TokenNotFoundTokenNotFound JWT が要求にありません。JWT not found in the request. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt 署名の検証に失敗しましたSignature validation failed TokenSignatureInvalidTokenSignatureInvalid <JWT ライブラリからのメッセージ>。<message from jwt library>. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt 無効な対象者Invalid audience TokenAudienceNotAllowedTokenAudienceNotAllowed <JWT ライブラリからのメッセージ>。<message from jwt library>. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt 無効な発行者Invalid issuer TokenIssuerNotAllowedTokenIssuerNotAllowed <JWT ライブラリからのメッセージ>。<message from jwt library>. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt トークンの有効期限が切れていますToken expired TokenExpiredTokenExpired <JWT ライブラリからのメッセージ>。<message from jwt library>. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt 署名キーを ID で解決できませんでしたSignature key was not resolved by ID TokenSignatureKeyNotFoundTokenSignatureKeyNotFound <JWT ライブラリからのメッセージ>。<message from jwt library>. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt 必要なクレームがトークンにありませんRequired claims are missing from token TokenClaimNotFoundTokenClaimNotFound 次のクレームが JWT トークンにありません: <c1>, <c2>, …JWT token is missing the following claims: <c1>, <c2>, … アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt クレームの値が一致しませんClaim values mismatch TokenClaimValueNotAllowedTokenClaimValueNotAllowed クレーム {claim-name} の値 {claim-value} は許可されていません。Claim {claim-name} value of {claim-value} is not allowed. アクセスが拒否されました。Access denied.
validate-jwtvalidate-jwt その他の検証の失敗Other validation failures JwtInvalidJwtInvalid <JWT ライブラリからのメッセージ><message from jwt library>

Example

API ポリシーを次のように設定します。Setting an API policy to:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

そして承認されていない要求を送信すると、結果として次のような応答があります。and sending an unauthorized request will result in the following response:

未承認エラーの応答

次の手順Next steps

ポリシーを使用する方法の詳細については、次のトピックを参照してください。For more information working with policies, see: