API Management の高度なポリシーAPI Management advanced policies

このトピックでは、次の API Management ポリシーについて説明します。This topic provides a reference for the following API Management policies. ポリシーを追加および構成する方法については、「 Azure API Management のポリシー」をご覧ください。For information on adding and configuring policies, see Policies in API Management.

高度なポリシーAdvanced policies

制御フローControl flow

choose ポリシーは、プログラミング言語の if-then-else や switch 構造のように、ブール式の評価結果に基づいて、含まれているポリシー ステートメントを適用します。The choose policy applies enclosed policy statements based on the outcome of evaluation of Boolean expressions, similar to an if-then-else or a switch construct in a programming language.

ポリシー ステートメントPolicy statement

<choose>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <otherwise>
        <!— one or more policy statements to be applied if none of the above conditions are true  -->
</otherwise>
</choose>

制御フロー ポリシーには、1 つ以上の <when/> 要素が含まれている必要があります。The control flow policy must contain at least one <when/> element. <otherwise/> 要素は省略可能です。The <otherwise/> element is optional. <when/> 要素内の条件は、ポリシーに記述されている順序で評価されます。Conditions in <when/> elements are evaluated in order of their appearance within the policy. 条件属性が true と等しい最初の <when/> 要素に含まれているポリシー ステートメントが適用されます。Policy statement(s) enclosed within the first <when/> element with condition attribute equals true will be applied. <otherwise/> 要素 (存在する場合) に含まれているポリシーは、<when/> 要素の条件属性がすべて false の場合に適用されます。Policies enclosed within the <otherwise/> element, if present, will be applied if all of the <when/> element condition attributes are false.

Examples

Example

次の例は、set-variable ポリシーと 2 つの制御フロー ポリシーを示しています。The following example demonstrates a set-variable policy and two control flow policies.

変数の設定ポリシーは inbound セクションにあり、User-Agent 要求ヘッダーにテキスト iPad または iPhone が含まれる場合に true に設定される isMobile ブール型コンテキスト変数を作成します。The set variable policy is in the inbound section and creates an isMobile Boolean context variable that is set to true if the User-Agent request header contains the text iPad or iPhone.

最初の制御フロー ポリシーも inbound セクションにあり、isMobile コンテキスト変数の値に応じて 2 つのクエリ文字列パラメーターの設定ポリシーのうち 1 つを条件付きで適用します。The first control flow policy is also in the inbound section, and conditionally applies one of two Set query string parameter policies depending on the value of the isMobile context variable.

2 番目の制御フロー ポリシーは outbound セクションにあり、isMobiletrue に設定されている場合に XML から JSON への変換ポリシーを条件付きで適用します。The second control flow policy is in the outbound section and conditionally applies the Convert XML to JSON policy when isMobile is set to true.

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers["User-Agent"].Contains("iPad") || context.Request.Headers["User-Agent"].Contains("iPhone"))" />
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <set-query-parameter name="mobile" exists-action="override">
                    <value>true</value>
                </set-query-parameter>
            </when>
            <otherwise>
                <set-query-parameter name="mobile" exists-action="override">
                    <value>false</value>
                </set-query-parameter>
            </otherwise>
        </choose>
    </inbound>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <xml-to-json kind="direct" apply="always" consider-accept-header="false"/>
            </when>
        </choose>
    </outbound>
</policies>

Example

次の例に、バックエンド サービスから受信した応答で Starter 製品が使用されている場合にデータ要素を削除して、内容のフィルター処理を行う方法を示します。This example shows how to perform content filtering by removing data elements from the response received from the backend service when using the Starter product. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177:More API Management Features」(クラウド カバー エピソード 177: その他の API Management 機能の紹介) を 34:30 まで早送りしてご覧ください。For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 34:30. このデモで使用されている Dark Sky Forecast API の概要について確認する場合は、31:50 から再生してください。Start at 31:50 to see an overview of The Dark Sky Forecast API used for this demo.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the api product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

要素Elements

要素Element 説明Description 必須Required
choosechoose ルート要素。Root element. はいYes
whenwhen choose ポリシーの if または ifelse の部分に使用する条件。The condition to use for the if or ifelse parts of the choose policy. choose ポリシーに複数の when セクションがある場合、これらのセクションは順番に評価されます。If the choose policy has multiple when sections, they are evaluated sequentially. when 要素のいずれかの conditiontrue に評価されると、それ以降の when 条件は評価されません。Once the condition of a when element evaluates to true, no further when conditions are evaluated. はいYes
otherwiseotherwise when 条件のいずれも true に評価されない場合に使用されるポリシー スニペットが含まれます。Contains the policy snippet to be used if none of the when conditions evaluate to true. いいえNo

属性Attributes

AttributeAttribute 説明Description 必須Required
condition="ブール式 | ブール型定数"condition="Boolean expression | Boolean constant" 含んでいる when ポリシー ステートメントが評価されるときに評価されるブール式または定数。The Boolean expression or constant to evaluated when the containing when policy statement is evaluated. はいYes

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

要求を転送するForward request

forward-request ポリシーは、要求コンテキストに指定されたバックエンド サービスに要求を転送します。The forward-request policy forwards the incoming request to the backend service specified in the request context. バックエンド サービスの URL は API 設定で指定され、バックエンド サービスの設定ポリシーを使用して変更できます。The backend service URL is specified in the API settings and can be changed using the set backend service policy.

注意

このポリシーを削除すると、要求はバックエンド サービスに転送されず、inbound セクションのポリシーが正常に完了した時点で outbound セクションのポリシーが即座に評価されます。Removing this policy results in the request not being forwarded to the backend service and the policies in the outbound section are evaluated immediately upon the successful completion of the policies in the inbound section.

ポリシー ステートメントPolicy statement

<forward-request timeout="time in seconds" follow-redirects="true | false" buffer-request-body="true | false" />

Examples

Example

次の API レベル ポリシーは、バックエンド サービスに転送されたすべての API 要求が 60 秒でタイムアウトすることを示します。The following API level policy forwards all API requests to the backend service with a timeout interval of 60 seconds.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Example

この操作レベル ポリシーは、base 要素を使用して、親 API レベル スコープからバックエンド ポリシーを継承します。This operation level policy uses the base element to inherit the backend policy from the parent API level scope.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Example

この操作レベル ポリシーは、すべての要求を 120 秒のタイムアウト間隔でバックエンド サービスに明示的に転送し、親 API レベル バックエンド ポリシーを継承しません。This operation level policy explicitly forwards all requests to the backend service with a timeout of 120 and does not inherit the parent API level backend policy.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120"/>
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Example

この操作レベル ポリシーは、バックエンド サービスに要求を転送しません。This operation level policy does not forward requests to the backend service.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

要素Elements

要素Element 説明Description 必須Required
forward-requestforward-request ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
timeout="整数"timeout="integer" バックエンド サービスによって返される HTTP 応答ヘッダーを待機する秒単位の時間。この時間を過ぎると、タイムアウト エラーが発生します。The amount of time in seconds to wait for the HTTP response headers to be returned by the backend service before a timeout error is raised. 最小値は 0 秒です。Minimum value is 0 seconds. この時間を過ぎると基盤となるネットワーク インフラストラクチャによってアイドル接続がドロップされる可能性があるため、240 秒より大きい値は受け入れられません。Values greater than 240 seconds may not be honored as the underlying network infrastructure can drop idle connections after this time. いいえNo なしNone
follow-redirects="true | false"follow-redirects="true | false" バックエンド サービスからのリダイレクトについて、その後にゲートウェイが続くか、それとも呼び出し元に返されるかを指定します。Specifies whether redirects from the backend service are followed by the gateway or returned to the caller. いいえNo falsefalse
buffer-request-body="true | false"buffer-request-body="true | false" "true" に設定した場合、要求がバッファーされ、再試行で再利用されます。When set to "true" request is buffered and will be reused on retry. いいえNo falsefalse

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: backendPolicy sections: backend
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

コンカレンシーを制限するLimit concurrency

limit-concurrency ポリシーは、含まれているポリシーがいずれかの時点で指定された数を超える要求によって実行されないようにします。The limit-concurrency policy prevents enclosed policies from executing by more than the specified number of requests at any time. その数を超えた場合は、新しい要求は 429 Too Many Requests (要求が多すぎます) のステータス コードですぐに失敗します。Upon exceeding that number, new requests will fail immediately with 429 Too Many Requests status code.

ポリシー ステートメントPolicy statement

<limit-concurrency key="expression" max-count="number">
        <!— nested policy statements -->
</limit-concurrency>

Examples

Example

次の例は、コンテキスト変数の値に基づいてバックエンドに転送される要求の数を制限する方法を示しています。The following example demonstrates how to limit number of requests forwarded to a backend based on the value of a context variable.

<policies>
  <inbound>…</inbound>
  <backend>
    <limit-concurrency key="@((string)context.Variables["connectionId"])" max-count="3">
      <forward-request timeout="120"/>
    <limit-concurrency/>
  </backend>
  <outbound>…</outbound>
</policies>

要素Elements

要素Element 説明Description 必須Required
limit-concurrencylimit-concurrency ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
keykey 文字列。A string. 式を使用できます。Expression allowed. コンカレンシー スコープを指定します。Specifies the concurrency scope. 複数のポリシーで共有できます。Can be shared by multiple policies. はいYes 該当なしN/A
max-countmax-count 整数。An integer. ポリシーに入力できる要求の最大数を指定します。Specifies a maximum number of requests that are allowed to enter the policy. はいYes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

イベント ハブにログを記録するLog to Event Hub

log-to-eventhub ポリシーは、指定された形式のメッセージを Logger エンティティによって定義されたイベント ハブに送信します。The log-to-eventhub policy sends messages in the specified format to an Event Hub defined by a Logger entity. その名前が示すように、このポリシーは、オンラインまたはオフライン分析のために、選択された要求または応答コンテキスト情報を保存するために使用します。As its name implies, the policy is used for saving selected request or response context information for online or offline analysis.

注意

イベント ハブの構成とイベントのログ記録に関する詳細な手順については、Azure Event Hubs で API Management イベントを記録する方法に関するページを参照してください。For a step-by-step guide on configuring an event hub and logging events, see How to log API Management events with Azure Event Hubs.

ポリシー ステートメントPolicy statement

<log-to-eventhub logger-id="id of the logger entity" partition-id="index of the partition where messages are sent" partition-key="value used for partition assignment">
  Expression returning a string to be logged
</log-to-eventhub>

Example

イベント ハブに記録する値として、任意の文字列を使用できます。Any string can be used as the value to be logged in Event Hubs. この例では、すべての着信コールの日付と時刻、デプロイ サービス名、要求 ID、IP アドレス、および操作名が、contoso-logger ID で登録されたイベント ハブ ロガーに記録されます。In this example the date and time, deployment service name, request id, ip address, and operation name for all inbound calls are logged to the event hub Logger registered with the contoso-logger id.

<policies>
  <inbound>
    <log-to-eventhub logger-id ='contoso-logger'>
      @( string.Join(",", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) )
    </log-to-eventhub>
  </inbound>
  <outbound>
  </outbound>
</policies>

要素Elements

要素Element 説明Description 必須Required
log-to-eventhublog-to-eventhub ルート要素。Root element. この要素の値は、イベント ハブに記録する文字列です。The value of this element is the string to log to your event hub. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required
logger-idlogger-id API Management サービスに登録されているロガーの ID。The id of the Logger registered with your API Management service. はいYes
partition-idpartition-id メッセージが送信されるパーティションのインデックスを指定します。Specifies the index of the partition where messages are sent. 省略可能。Optional. partition-key を使用する場合はこの属性を使用できません。This attribute may not be used if partition-key is used.
partition-keypartition-key メッセージの送信時にパーティション割り当てに使用される値を指定します。Specifies the value used for partition assignment when messages are sent. 省略可能。Optional. partition-id を使用する場合はこの属性を使用できません。This attribute may not be used if partition-id is used.

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

モック応答Mock response

mock-response は名前が示すとおり、API と操作の模擬テストを実行するために使用します。The mock-response, as the name implies, is used to mock APIs and operations. 通常のパイプライン実行を中止し、モック応答を呼び出し元に返します。It aborts normal pipeline execution and returns a mocked response to the caller. ポリシーは常に、再現性が最も高い応答を返そうとします。The policy always tries to return responses of highest fidelity. 使用可能な場合は常に、応答コンテキストの例が優先されます。It prefers response content examples, whenever available. スキーマが提供され、例が提供されていない場合、ポリシーはスキーマからサンプルの応答を生成します。It generates sample responses from schemas, when schemas are provided and examples are not. 例もスキーマも見つからない場合、コンテキストなしの応答が返されます。If neither examples or schemas are found, responses with no content are returned.

ポリシー ステートメントPolicy statement

<mock-response status-code="code" content-type="media type"/>

Examples

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code. First found content type is used. If no example or schema is found, the content is empty. -->
<mock-response/>

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code and media type. If no example or schema found, the content is empty. -->
<mock-response status-code='200' content-type='application/json'/>

要素Elements

要素Element 説明Description 必須Required
mock-responsemock-response ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
status-codestatus-code 応答の状態コードを指定し、対応する例またはスキーマを選択するために使用します。Specifies response status code and is used to select corresponding example or schema. いいえNo 200200
content-typecontent-type Content-Type 応答のヘッダー値を指定し、対応する例またはスキーマを選択するために使用します。Specifies Content-Type response header value and is used to select corresponding example or schema. いいえNo なしNone

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、on-errorPolicy sections: inbound, outbound, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

再試行Retry

retry ポリシーは子ポリシーを 1 回実行し、再試行 conditionfalse になるか再試行 count に達するまで、実行を再試行します。The retry policy executes its child policies once and then retries their execution until the retry condition becomes false or retry count is exhausted.

ポリシー ステートメントPolicy statement


<retry
    condition="boolean expression or literal"
    count="number of retry attempts"
    interval="retry interval in seconds"
    max-interval="maximum retry interval in seconds"
    delta="retry interval delta in seconds"
    first-fast-retry="boolean expression or literal">
        <!-- One or more child policies. No restrictions -->
</retry>

Example

次の例では、要求の転送が、指数再試行アルゴリズムを使用して 10 回まで再試行されます。In the following example, request forwarding is retried up to ten times using an exponential retry algorithm. first-fast-retry が false に設定されているため、すべての再試行が指数再試行アルゴリズムの対象になります。Since first-fast-retry is set to false, all retry attempts are subject to the exponential retry algorithm.


<retry
    condition="@(context.Response.StatusCode == 500)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
        <forward-request buffer-request-body="true" />
</retry>

要素Elements

要素Element 説明Description 必須Required
retryretry ルート要素。Root element. 他のポリシーを子要素として含めることができます。May contain any other policies as its child elements. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
conditioncondition 再試行を停止する (false) か続行する (true) かを指定するブール型リテラルまたはA boolean literal or expression specifying if retries should be stopped (false) or continued (true). はいYes 該当なしN/A
countcount 最大再試行回数を指定する正の数。A positive number specifying the maximum number of retries to attempt. はいYes 該当なしN/A
intervalinterval 再試行の間の待機間隔を指定する正の数 (秒単位)。A positive number in seconds specifying the wait interval between the retry attempts. はいYes 該当なしN/A
max-intervalmax-interval 再試行の間の最大待機間隔を指定する正の数 (秒単位)。A positive number in seconds specifying the maximum wait interval between the retry attempts. 指数再試行アルゴリズムを実装するために使用されます。It is used to implement an exponential retry algorithm. いいえNo 該当なしN/A
deltadelta 待機間隔の増分値を指定する正の数 (秒単位)。A positive number in seconds specifying the wait interval increment. 線形再試行アルゴリズムと指数再試行アルゴリズムを実装するために使用されます。It is used to implement the linear and exponential retry algorithms. いいえNo 該当なしN/A
first-fast-retryfirst-fast-retry true に設定した場合、最初の再試行がすぐに実行されます。If set to true , the first retry attempt is performed immediately. いいえNo false

注意

interval のみを指定した場合、再試行は固定間隔で実行されます。When only the interval is specified, fixed interval retries are performed. intervaldelta のみを指定した場合、線形間隔の再試行アルゴリズムが使用されます。この場合の再試行間の待機時間は、次の式に従って計算されます: interval + (count - 1)*deltaWhen only the interval and delta are specified, a linear interval retry algorithm is used, where wait time between retries is calculated according the following formula - interval + (count - 1)*delta. intervalmax-interval、および delta を指定した場合、指数間隔の再試行アルゴリズムが適用されます。この場合の再試行間の待機時間は、次の式に従って interval の値から値 max-interval まで指数的に大きくなります: min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval)When the interval, max-interval and delta are specified, exponential interval retry algorithm is applied, where the wait time between the retries is growing exponentially from the value of interval to the value max-interval according to the following formula - min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval).

使用法Usage

このポリシーは、ポリシーの以下のセクションスコープで使用できます。This policy can be used in the following policy sections and scopes . 子ポリシーの使用に関する制限がこのポリシーに継承されることに注意してください。Note that child policy usage restrictions will be inherited by this policy.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

応答を返すReturn response

return-response ポリシーは、パイプラインの実行を中止し、既定またはカスタムの応答を呼び出し元に返します。The return-response policy aborts pipeline execution and returns either a default or custom response to the caller. 既定の応答は、本文のない 200 OK です。Default response is 200 OK with no body. コンテキスト変数またはポリシー ステートメントを使用して、カスタムの応答を指定できます。Custom response can be specified via a context variable or policy statements. その両方を指定した場合、コンテキスト変数に含まれる応答が、呼び出し元に返される前にポリシー ステートメントによって変更されます。When both are provided, the response contained within the context variable is modified by the policy statements before being returned to the caller.

ポリシー ステートメントPolicy statement

<return-response response-variable-name="existing context variable">
  <set-header/>
  <set-body/>
  <set-status/>
</return-response>

Example

<return-response>
   <set-status code="401" reason="Unauthorized"/>
   <set-header name="WWW-Authenticate" exists-action="override">
      <value>Bearer error="invalid_token"</value>
   </set-header>
</return-response>

要素Elements

要素Element 説明Description 必須Required
return-responsereturn-response ルート要素。Root element. はいYes
set-headerset-header set-header ポリシー ステートメント。A set-header policy statement. いいえNo
set-bodyset-body set-body ポリシー ステートメント。A set-body policy statement. いいえNo
set-statusset-status set-status ポリシー ステートメント。A set-status policy statement. いいえNo

属性Attributes

AttributeAttribute 説明Description 必須Required
response-variable-nameresponse-variable-name たとえば、アップストリームの send-request ポリシーから参照され、Response オブジェクトを含むコンテキスト変数の名前The name of the context variable referenced from, for example, an upstream send-request policy and containing a Response object 省略可能。Optional.

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

1 方向の要求を送信するSend one way request

send-one-way-request ポリシーは、指定された URL に指定された要求を送信します。応答は待機しません。The send-one-way-request policy sends the provided request to the specified URL without waiting for a response.

ポリシー ステートメントPolicy statement

<send-one-way-request mode="new | copy">
  <url>...</url>
  <method>...</method>
  <header name="" exists-action="override | skip | append | delete">...</header>
  <body>...</body>
  <authentication-certificate thumbprint="thumbprint" />
</send-one-way-request>

Example

このサンプル ポリシーでは、send-one-way-request ポリシーを使用して、HTTP 応答コードが 500 以上の場合に Slack チャット ルームにメッセージを送信します。This sample policy shows an example of using the send-one-way-request policy to send a message to a Slack chat room if the HTTP response code is greater than or equal to 500. このサンプルの詳細については、「Azure API Management サービスからの外部サービスの使用」を参照してください。For more information on this sample, see Using external services from the Azure API Management service.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

要素Elements

要素Element 説明Description 必須Required
send-one-way-requestsend-one-way-request ルート要素。Root element. はいYes
urlurl 要求の URL。The URL of the request. いいえ (mode=copy の場合)。はい (それ以外の場合)。No if mode=copy; otherwise yes.
methodmethod 要求の HTTP メソッド。The HTTP method for the request. いいえ (mode=copy の場合)。はい (それ以外の場合)。No if mode=copy; otherwise yes.
ヘッダーheader 要求ヘッダー。Request header. 複数の要求ヘッダーには複数のヘッダー要素を使用します。Use multiple header elements for multiple request headers. いいえNo
bodybody 要求本文。The request body. いいえNo
authentication-certificateauthentication-certificate クライアントの認証に使用する証明書Certificate to use for client authentication いいえNo

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
mode="文字列"mode="string" これが新しい要求であるか現在の要求のコピーであるかを判定します。Determines whether this is a new request or a copy of the current request. 送信モードでの mode=copy の場合、要求本文は初期化されません。In outbound mode, mode=copy does not initialize the request body. いいえNo 新規New
namename 設定するヘッダーの名前を指定します。Specifies the name of the header to be set. はいYes 該当なしN/A
exists-actionexists-action 対象のヘッダーが既に指定されている場合の操作を指定します。Specifies what action to take when the header is already specified. この属性の値は次のいずれかに設定する必要があります。This attribute must have one of the following values.

- override - 既存のヘッダーの値を置き換えます。- override - replaces the value of the existing header.
- skip - 既存のヘッダーの値を置き換えません。- skip - does not replace the existing header value.
- append - 既存のヘッダーの値に値を追加します。- append - appends the value to the existing header value.
- delete - 要求からヘッダーを削除します。- delete - removes the header from the request.

override に設定した場合、同じ名前の複数のエントリを記載すると、すべてのエントリに従ってヘッダーが設定されます (複数回記載されます)。結果に設定されるのは記載した値のみです。When set to override enlisting multiple entries with the same name results in the header being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
いいえNo overrideoverride

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

要求を送信するSend request

send-request ポリシーは、設定されたタイムアウト値以内の待機時間で、指定された要求を指定された URL に送信します。The send-request policy sends the provided request to the specified URL, waiting no longer than the set timeout value.

ポリシー ステートメントPolicy statement

<send-request mode="new|copy" response-variable-name="" timeout="60 sec" ignore-error
="false|true">
  <set-url>...</set-url>
  <set-method>...</set-method>
  <set-header name="" exists-action="override|skip|append|delete">...</set-header>
  <set-body>...</set-body>
  <authentication-certificate thumbprint="thumbprint" />
</send-request>

Example

この例は、承認サーバーを使用して参照トークンを検証する 1 つの方法を示しています。This example shows one way to verify a reference token with an authorization server. このサンプルの詳細については、「Azure API Management サービスからの外部サービスの使用」を参照してください。For more information on this sample, see Using external services from the Azure API Management service.

<inbound>
  <!-- Extract Token from Authorization header parameter -->
  <set-variable name="token" value="@(context.Request.Headers.GetValueOrDefault("Authorization","scheme param").Split(' ').Last())" />

  <!-- Send request to Token Server to validate token (see RFC 7662) -->
  <send-request mode="new" response-variable-name="tokenstate" timeout="20" ignore-error="true">
    <set-url>https://microsoft-apiappec990ad4c76641c6aea22f566efc5a4e.azurewebsites.net/introspection</set-url>
    <set-method>POST</set-method>
    <set-header name="Authorization" exists-action="override">
      <value>basic dXNlcm5hbWU6cGFzc3dvcmQ=</value>
    </set-header>
    <set-header name="Content-Type" exists-action="override">
      <value>application/x-www-form-urlencoded</value>
    </set-header>
    <set-body>@($"token={(string)context.Variables["token"]}")</set-body>
  </send-request>

  <choose>
        <!-- Check active property in response -->
        <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
            <!-- Return 401 Unauthorized with http-problem payload -->
            <return-response>
                <set-status code="401" reason="Unauthorized" />
                <set-header name="WWW-Authenticate" exists-action="override">
                    <value>Bearer error="invalid_token"</value>
                </set-header>
            </return-response>
        </when>
    </choose>
  <base />
</inbound>

要素Elements

要素Element 説明Description 必須Required
send-requestsend-request ルート要素。Root element. はいYes
urlurl 要求の URL。The URL of the request. いいえ (mode=copy の場合)。はい (それ以外の場合)。No if mode=copy; otherwise yes.
methodmethod 要求の HTTP メソッド。The HTTP method for the request. いいえ (mode=copy の場合)。はい (それ以外の場合)。No if mode=copy; otherwise yes.
ヘッダーheader 要求ヘッダー。Request header. 複数の要求ヘッダーには複数のヘッダー要素を使用します。Use multiple header elements for multiple request headers. いいえNo
bodybody 要求本文。The request body. いいえNo
authentication-certificateauthentication-certificate クライアントの認証に使用する証明書Certificate to use for client authentication いいえNo

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
mode="文字列"mode="string" これが新しい要求であるか現在の要求のコピーであるかを判定します。Determines whether this is a new request or a copy of the current request. 送信モードでの mode=copy の場合、要求本文は初期化されません。In outbound mode, mode=copy does not initialize the request body. いいえNo 新規New
response-variable-name="文字列"response-variable-name="string" 応答オブジェクトを受信するコンテキスト変数の名前。The name of context variable that will receive a response object. この変数が存在しない場合は、ポリシーの正常な実行時に作成され、context.Variable コレクション経由でアクセス可能になります。If the variable doesn't exist, it will be created upon successful execution of the policy and will become accessible via context.Variable collection. はいYes 該当なしN/A
timeout="整数"timeout="integer" URL の呼び出しが失敗するまでのタイムアウト間隔 (秒単位)。The timeout interval in seconds before the call to the URL fails. いいえNo 6060
ignore-errorignore-error true に設定され、要求の結果がエラーになった場合:If true and the request results in an error:

- response-variable-name が指定されている場合、null 値が格納されます。- If response-variable-name was specified it will contain a null value.
- response-variable-name が指定されていない場合、context.Request は更新されません。- If response-variable-name was not specified, context.Request will not be updated.
いいえNo falsefalse
namename 設定するヘッダーの名前を指定します。Specifies the name of the header to be set. はいYes 該当なしN/A
exists-actionexists-action 対象のヘッダーが既に指定されている場合の操作を指定します。Specifies what action to take when the header is already specified. この属性の値は次のいずれかに設定する必要があります。This attribute must have one of the following values.

- override - 既存のヘッダーの値を置き換えます。- override - replaces the value of the existing header.
- skip - 既存のヘッダーの値を置き換えません。- skip - does not replace the existing header value.
- append - 既存のヘッダーの値に値を追加します。- append - appends the value to the existing header value.
- delete - 要求からヘッダーを削除します。- delete - removes the header from the request.

override に設定した場合、同じ名前の複数のエントリを記載すると、すべてのエントリに従ってヘッダーが設定されます (複数回記載されます)。結果に設定されるのは記載した値のみです。When set to override enlisting multiple entries with the same name results in the header being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
いいえNo overrideoverride

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

HTTP プロキシの設定Set HTTP proxy

proxy ポリシーにより、HTTP プロキシ経由でバックエンドに転送されるように要求をルーティングできます。The proxy policy allows you to route requests forwarded to backends via an HTTP proxy. ゲートウェイとプロキシ間は、HTTP (HTTPS ではなく) のみがサポートされます。Only HTTP (not HTTPS) is supported between the gateway and the proxy. 基本認証と NTLM 認証のみ。Basic and NTLM authentication only.

ポリシー ステートメントPolicy statement

<proxy url="http://hostname-or-ip:port" username="username" password="password" />

Example

ポリシー ドキュメントに機密情報を保存しないようにするため、ユーザー名とパスワードの値としてのプロパティの使用に注意してください。Note the use of properties as values of the username and password to avoid storing sensitive information in the policy document.

<proxy url="http://192.168.1.1:8080" username={{username}} password={{password}} />

要素Elements

要素Element 説明Description 必須Required
proxyproxy ルート要素Root element はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
url="string"url="string" http://host:port の形式のプロキシ URL。Proxy URL in the form of http://host:port. はいYes 該当なしN/A
username="string"username="string" プロキシで認証に使用するユーザー名。Username to be used for authentication with the proxy. いいえNo 該当なしN/A
password="string"password="string" プロキシで認証に使用するパスワード。Password to be used for authentication with the proxy. いいえNo 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inboundPolicy sections: inbound

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

要求メソッドを設定するSet request method

set-method ポリシーでは、要求の HTTP 要求メソッドを変更できます。The set-method policy allows you to change the HTTP request method for a request.

ポリシー ステートメントPolicy statement

<set-method>METHOD</set-method>

Example

このサンプル ポリシーでは、set-method ポリシーを使用して、HTTP 応答コードが 500 以上の場合に Slack チャット ルームにメッセージを送信します。This sample policy that uses the set-method policy shows an example of sending a message to a Slack chat room if the HTTP response code is greater than or equal to 500. このサンプルの詳細については、「Azure API Management サービスからの外部サービスの使用」を参照してください。For more information on this sample, see Using external services from the Azure API Management service.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

要素Elements

要素Element 説明Description 必須Required
set-methodset-method ルート要素。Root element. 要素の値は、HTTP メソッドを指定します。The value of the element specifies the HTTP method. はいYes

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、on-errorPolicy sections: inbound, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

状態コードを設定するSet status code

set-status ポリシーは、HTTP 状態コードを指定された値に変更します。The set-status policy sets the HTTP status code to the specified value.

ポリシー ステートメントPolicy statement

<set-status code="" reason=""/>

Example

この例は、承認トークンが無効な場合に 401 応答を返す方法を示しています。This example shows how to return a 401 response if the authorization token is invalid. 詳細については、「Azure API Management サービスからの外部サービスの使用」を参照してください。For more information, see Using external services from the Azure API Management service

<choose>
  <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
    <return-response response-variable-name="existing response variable">
      <set-status code="401" reason="Unauthorized" />
      <set-header name="WWW-Authenticate" exists-action="override">
        <value>Bearer error="invalid_token"</value>
      </set-header>
    </return-response>
  </when>
</choose>

要素Elements

要素Element 説明Description 必須Required
set-statusset-status ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
code="整数"code="integer" 返される HTTP 状態コード。The HTTP status code to return. はいYes 該当なしN/A
reason="文字列"reason="string" 状態コードを返す理由の説明。A description of the reason for returning the status code. はいYes 該当なしN/A

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: outbound、backend、on-errorPolicy sections: outbound, backend, on-error
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

変数の設定Set variable

set-variable ポリシーは、コンテキスト変数を宣言し、または文字列リテラルによって指定された値をこの変数に割り当てます。The set-variable policy declares a context variable and assigns it a value specified via an expression or a string literal. リテラルが含まれている式は文字列に変換され、値の型は System.String になります。if the expression contains a literal it will be converted to a string and the type of the value will be System.String.

ポリシー ステートメントPolicy statement

<set-variable name="variable name" value="Expression | String literal" />

Example

次の例は、inbound セクションの変数の設定ポリシーを示しています。The following example demonstrates a set variable policy in the inbound section. この変数の設定ポリシーは、User-Agent 要求ヘッダーにテキスト iPad または iPhone が含まれる場合に true に設定される isMobile ブール型コンテキスト引数を作成します。This set variable policy creates an isMobile Boolean context variable that is set to true if the User-Agent request header contains the text iPad or iPhone.

<set-variable name="IsMobile" value="@(context.Request.Headers["User-Agent"].Contains("iPad") || context.Request.Headers["User-Agent"].Contains("iPhone"))" />

要素Elements

要素Element 説明Description 必須Required
set-variableset-variable ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required
namename 変数の名前。The name of the variable. はいYes
value 変数の値。The value of the variable. 式またはリテラル値を指定できます。This can be an expression or a literal value. はいYes

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

使用できる型Allowed types

set-variable ポリシーで使用する式は、次の基本的な型のいずれかを返す必要があります。Expressions used in the set-variable policy must return one of the following basic types.

  • System.BooleanSystem.Boolean
  • System.SByteSystem.SByte
  • System.ByteSystem.Byte
  • System.UInt16System.UInt16
  • System.UInt32System.UInt32
  • System.UInt64System.UInt64
  • System.Int16System.Int16
  • System.Int32System.Int32
  • System.Int64System.Int64
  • System.DecimalSystem.Decimal
  • System.SingleSystem.Single
  • System.DoubleSystem.Double
  • System.GuidSystem.Guid
  • System.StringSystem.String
  • System.CharSystem.Char
  • System.DateTimeSystem.DateTime
  • System.TimeSpanSystem.TimeSpan
  • System.Byte?System.Byte?
  • System.UInt16?System.UInt16?
  • System.UInt32?System.UInt32?
  • System.UInt64?System.UInt64?
  • System.Int16?System.Int16?
  • System.Int32?System.Int32?
  • System.Int64?System.Int64?
  • System.Decimal?System.Decimal?
  • System.Single?System.Single?
  • System.Double?System.Double?
  • System.Guid?System.Guid?
  • System.String?System.String?
  • System.Char?System.Char?
  • System.DateTime?System.DateTime?

トレースTrace

trace ポリシーは、API Inspector の出力に文字列を追加します。The trace policy adds a string into the API Inspector output. このポリシーは、トレースがトリガーされたときにのみ実行されます。つまり、Ocp-Apim-Trace 要求ヘッダーが存在し、true に設定されている場合、および Ocp-Apim-Subscription-Key 要求ヘッダーが存在し、管理者アカウントに関連付けられた有効なキーを保持している場合が該当します。The policy will execute only when tracing is triggered, i.e. Ocp-Apim-Trace request header is present and set to true and Ocp-Apim-Subscription-Key request header is present and holds a valid key associated with the admin account.

ポリシー ステートメントPolicy statement


<trace source="arbitrary string literal">
    <!-- string expression or literal -->
</trace>

要素Elements

要素Element 説明Description 必須Required
tracetrace ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
sourcesource メッセージのソースを指定する、トレース ビューアーにとって意味のある文字列リテラル。String literal meaningful to the trace viewer and specifying the source of the message. はいYes 該当なしN/A

使用法Usage

このポリシーは、ポリシーの以下のセクションスコープで使用できます。This policy can be used in the following policy sections and scopes .

  • ポリシー セクション: inbound、outbound、backend、on-errorPolicy sections: inbound, outbound, backend, on-error

  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

待機Wait

wait ポリシーは、直接の子ポリシーを並列で実行し、その直接の子ポリシーのすべてまたはいずれかが完了するまで完了を待機します。The wait policy executes its immediate child policies in parallel, and waits for either all or one of its immediate child policies to complete before it completes. 待機ポリシーには、要求を送信するキャッシュからの値の取得、および制御フローのポリシーを直接の子ポリシーとして含めることができます。The wait policy can have as its immediate child policies Send request, Get value from cache, and Control flow policies.

ポリシー ステートメントPolicy statement

<wait for="all|any">
  <!--Wait policy can contain send-request, cache-lookup-value,
        and choose policies as child elements -->
</wait>

Example

次の例では、wait ポリシーの直接の子ポリシーとして 2 つの choose ポリシーがあります。In the following example there are two choose policies as immediate child policies of the wait policy. これらの choose ポリシーはそれぞれ並列に実行されます。Each of these choose policies executes in parallel. choose ポリシーは、キャッシュされた値を取得しようとします。Each choose policy attempts to retrieve a cached value. キャッシュ ミスがある場合は、バックエンド サービスが呼び出されて値を提供します。If there is a cache miss, a backend service is called to provide the value. この例では、for 属性が all に設定されているため、すべての直接の子ポリシーが完了するまで、wait ポリシーは完了しません。In this example the wait policy does not complete until all of its immediate child policies complete, because the for attribute is set to all. この例のコンテキスト変数 (execute-branch-onevalue-oneexecute-branch-two、および value-two) は、このサンプル ポリシーのスコープ外で宣言されています。In this example the context variables (execute-branch-one, value-one, execute-branch-two, and value-two) are declared outside of the scope of this example policy.

<wait for="all">
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-one="])">
      <cache-lookup-value key="key-one" variable-name="value-one" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-one="))">
          <send-request mode="new" response-variable-name="value-one">
            <set-url>https://backend-one</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-two="])">
      <cache-lookup-value key="key-two" variable-name="value-two" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-two="))">
          <send-request mode="new" response-variable-name="value-two">
            <set-url>https://backend-two</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
</wait>

要素Elements

要素Element 説明Description 必須Required
waitwait ルート要素。Root element. send-request ポリシー、cache-lookup-value ポリシー、および choose ポリシーのみを子要素として含めることができます。May contain as child elements only send-request, cache-lookup-value, and choose policies. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required 既定値Default
forfor wait ポリシーがすべての直接の子ポリシーが完了するまで待機するか、1 つが完了するまで待機するかを決定します。Determines whether the wait policy waits for all immediate child policies to be completed or just one. 使用できる値は、以下のとおりです。Allowed values are:

- all - すべての直接の子ポリシーが完了するまで待機します。- all - wait for all immediate child policies to complete
- any - いずれかの直接の子ポリシーが完了するまで待機します。- any - wait for any immediate child policy to complete. 最初の直接の子ポリシーが完了すると、wait ポリシーが完了し、他の直接の子ポリシーの実行が終了します。Once the first immediate child policy has completed, the wait policy completes and execution of any other immediate child policies is terminated.
いいえNo すべてall

使用法Usage

このポリシーは、次のポリシー セクションスコープで使用できます。This policy can be used in the following policy sections and scopes.

  • ポリシー セクション: inbound、outbound、backendPolicy sections: inbound, outbound, backend
  • ポリシー スコープ: すべてのスコープPolicy scopes: all scopes

次の手順Next steps

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