API Management の変換ポリシーAPI Management transformation 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.

変換ポリシーTransformation policies

JSON から XML への変換Convert JSON to XML

json-to-xml ポリシーは、要求本文または応答本文を JSON から XML に変換します。The json-to-xml policy converts a request or response body from JSON to XML.

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

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false" parse-date="true | false"/>

Example

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false"/>
    </outbound>
</policies>

要素Elements

名前Name 説明Description 必須Required
json-to-xmljson-to-xml ルート要素。Root element. はいYes

属性Attributes

名前Name 説明Description 必須Required 既定値Default
applyapply この属性の値は次のいずれかに設定する必要があります。The attribute must be set to one of the following values.

- always - 常に変換を適用します。- always - always apply conversion.
- content-type-json - 応答の Content-Type ヘッダーに JSON の存在が示されている場合のみ変換を行います。- content-type-json - convert only if response Content-Type header indicates presence of JSON.
はいYes 該当なしN/A
consider-accept-headerconsider-accept-header この属性の値は次のいずれかに設定する必要があります。The attribute must be set to one of the following values.

- true - 要求の Accept ヘッダーで JSON が要求されている場合に変換を適用します。- true - apply conversion if JSON is requested in request Accept header.
- false - 常に変換を適用します。- false -always apply conversion.
いいえNo truetrue
parse-dateparse-date false に設定すると、変換中、日付値がコピーされます。When set to false date values are simply copied during transformation いいえNo truetrue

使用法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

XML から JSON への変換Convert XML to JSON

xml-to-json ポリシーは、要求本文または応答方文を XML から JSON に変換します。The xml-to-json policy converts a request or response body from XML to JSON. このポリシーを使用すると、XML のみのバックエンド Web サービスに基づく API を最新化することができます。This policy can be used to modernize APIs based on XML-only backend web services.

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

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>

Example

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
    </outbound>
</policies>

要素Elements

名前Name 説明Description 必須Required
xml-to-jsonxml-to-json ルート要素。Root element. はいYes

属性Attributes

名前Name 説明Description 必須Required DefaultDefault
kindkind この属性の値は次のいずれかに設定する必要があります。The attribute must be set to one of the following values.

- javascript-friendly - 変換後の JSON が JavaScript 開発者にとってわかりやすい形になります。- javascript-friendly - the converted JSON has a form friendly to JavaScript developers.
- direct - 変換後の JSON に元の XML ドキュメントの構造が反映されます。- direct - the converted JSON reflects the original XML document's structure.
はいYes 該当なしN/A
applyapply この属性の値は次のいずれかに設定する必要があります。The attribute must be set to one of the following values.

- always - 常に変換します。- always - convert always.
- content-type-xml - 応答の Content-Type ヘッダーに XML の存在が示されている場合のみ変換を行います。- content-type-xml - convert only if response Content-Type header indicates presence of XML.
はいYes 該当なしN/A
consider-accept-headerconsider-accept-header この属性の値は次のいずれかに設定する必要があります。The attribute must be set to one of the following values.

- true - 要求の Accept ヘッダーで XML が要求されている場合に変換を適用します。- true - apply conversion if XML is requested in request Accept header.
- false - 常に変換を適用します。- false -always apply conversion.
いいえNo truetrue

使用法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

本文内の文字列の検索および置換Find and replace string in body

find-and-replace ポリシーは、要求または応答内の文字部分列を検索し、別の部分文字列で置き換えます。The find-and-replace policy finds a request or response substring and replaces it with a different substring.

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

<find-and-replace from="what to replace" to="replacement" />

Example

<find-and-replace from="notebook" to="laptop" />

要素Elements

名前Name 説明Description 必須Required
find-and-replacefind-and-replace ルート要素。Root element. はいYes

属性Attributes

名前Name 説明Description 必須Required DefaultDefault
fromfrom 検索する文字列。The string to search for. はいYes 該当なしN/A
toto 置換する文字列。The replacement string. 長さゼロの置換文字列を指定すると、検索文字列を削除できます。Specify a zero length replacement string to remove the search string. はい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

コンテンツ内の URL のマスクMask URLs in content

redirect-content-urls ポリシーは、応答本文内のリンクを、ゲートウェイを経由して同じリンクをポイントするように書き換えます (マスクします)。The redirect-content-urls policy re-writes (masks) links in the response body so that they point to the equivalent link via the gateway. 応答本文のリンクをゲートウェイにポイントさせる場合は outbound セクションで使用します。Use in the outbound section to re-write response body links to make them point to the gateway. 反対の効果を生じさせる場合は inbound セクションで使用します。Use in the inbound section for an opposite effect.

注意

このポリシーでは、Location ヘッダーなどのヘッダー値は変更されません。This policy does not change any header values such as Location headers. ヘッダーの値を変更するには、set-header ポリシーを使用します。To change header values, use the set-header policy.

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

<redirect-content-urls />

Example

<redirect-content-urls />

要素Elements

名前Name 説明Description 必須Required
redirect-content-urlsredirect-content-urls ルート要素。Root element. はいYes

使用法Usage

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

  • ポリシー セクション: inbound、outboundPolicy sections: inbound, outbound

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

バックエンド サービスの設定Set backend service

set-backend-service ポリシーを使用すると、該当する操作の API 設定で指定されているものとは異なるバックエンドに受信要求をリダイレクトできます。Use the set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. このポリシーでは、受信要求のバックエンド サービスのベース URL をこのポリシーで指定した URL に変更します。This policy changes the backend service base URL of the incoming request to the one specified in the policy.

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

<set-backend-service base-url="base URL of the backend service" />

oror

<set-backend-service backend-id="identifier of the backend entity specifying base URL of the backend service" />

注意

バックエンド エンティティは、管理 APIPowerShell を使用して管理できます。Backend entities can be managed via management API and PowerShell.

Example

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

この例では、バックエンド サービスの設定ポリシーにより、クエリ文字列に渡されるバージョン値に基づいて、API で指定されているものとは異なるバックエンド サービスに要求をルーティングしています。In this example the set backend service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the API.

まず、API 設定からバックエンド サービスのベース URL が読み取られます。Initially the backend service base URL is derived from the API settings. これにより、要求 URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdefhttp://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef になります。http://contoso.com/api/10.4/ は API 設定で指定されているバックエンド サービスの URL です。So the request URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef becomes http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef where http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.

<choose> ポリシー ステートメントを適用した場合、バックエンド サービスのベース URL は、要求クエリの version パラメーターの値に応じて http://contoso.com/api/8.2 または http://contoso.com/api/9.1 のどちらかに変更されます。When the <choose> policy statement is applied the backend service base URL may change again either to http://contoso.com/api/8.2 or http://contoso.com/api/9.1, depending on the value of the version request query parameter. たとえば、このパラメーターの値が "2013-15" の場合、最終的な要求 URL は http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdefになります。For example, if the value is "2013-15" the final request URL becomes http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.

さらに要求を変換する必要がある場合には、別の変換ポリシーを使用できます。If further transformation of the request is desired, other Transformation policies can be used. たとえば、要求をバージョンごとのバックエンドにルーティングしたので version クエリ パラメーターを削除するには、クエリ文字列パラメーターの設定ポリシーを使用して、余計になった version 属性を削除できます。For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.

Example

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

この例では、ポリシーは、パーティション キーとして userId クエリ文字列を使い、パーティションのプライマリ レプリカを使って、サービス ファブリック バックエンドに要求をルーティングします。In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.

要素Elements

名前Name 説明Description 必須Required
set-backend-serviceset-backend-service ルート要素。Root element. はいYes

属性Attributes

名前Name 説明Description 必須Required DefaultDefault
base-urlbase-url バックエンド サービスの新しいベース URL。New backend service base URL. base-url または backend-id のいずれかが存在しなければなりません。One of base-url or backend-id must be present. 該当なしN/A
backend-idbackend-id ルーティング先のバックエンドの識別子。Identifier of the backend to route to. (バックエンド エンティティは、APIPowerShell を使用して管理できます)。(Backend entities are managed via API and PowerShell.) base-url または backend-id のいずれかが存在しなければなりません。One of base-url or backend-id must be present. 該当なしN/A
sf-partition-keysf-partition-key バックエンドが Service Fabric サービスで、'backend-id' を使って指定されている場合にのみ適用されます。Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. 名前解決サービスからの特定のパーティションを解決するために使います。Used to resolve a specific partition from the name resolution service. いいえNo 該当なしN/A
sf-replica-typesf-replica-type バックエンドが Service Fabric サービスで、'backend-id' を使って指定されている場合にのみ適用されます。Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. 要求をパーティションのプライマリ レプリカとセカンダリ レプリカのどちらに送信する必要があるかを制御します。Controls if the request should go to the primary or secondary replica of a partition. いいえNo 該当なしN/A
sf-resolve-conditionsf-resolve-condition バックエンドが Service Fabric サービスの場合にのみ適用されます。Only applicable when the backend is a Service Fabric service. Service Fabric バックエンドへの呼び出しを新しい解決で繰り返す必要があるかどうかを識別する条件です。Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. いいえNo 該当なしN/A
sf-service-instance-namesf-service-instance-name バックエンドが Service Fabric サービスの場合にのみ適用されます。Only applicable when the backend is a Service Fabric service. 実行時にサービス インスタンスを変更できます。Allows to change service instances at runtime. いいえNo 該当なしN/A
sf-listener-namesf-listener-name バックエンドが Service Fabric サービスで、"backend-id" を使って指定されている場合にのみ適用されます。Only applicable when the backend is a Service Fabric service and is specified using ‘backend-id’. Service Fabric Reliable Services では、サービス内に複数のリスナーを作成できます。Service Fabric Reliable Services allows you to create multiple listeners in a service. この属性は、バックエンドのリライアブル サービスに複数のリスナーがある場合に、特定のリスナーを選択するために使用されます。This attribute is used to select a specific listener when a backend Reliable Service has more than one listener. この属性が指定されていない場合、API Management によって名前のないリスナーの使用が試行されます。If this attribute is not specified, API Management will attempt to use a listener without a name. リスナーが 1 つのみのリライアブル サービスでは、通常、リスナーに名前がありません。A listener without a name is typical for Reliable Services that have only one listener. いいえNo 該当なしN/A

使用法Usage

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

  • ポリシー セクション: inbound、backendPolicy sections: inbound, backend

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

本文の設定Set body

着信要求と発信要求のメッセージ本文を設定するには、set-body ポリシーを使用します。Use the set-body policy to set the message body for incoming and outgoing requests. メッセージ本文へのアクセスには、ポリシーを inbound セクションと outbound セクションのどちらに記載するかに応じて context.Request.Body プロパティまたは context.Response.Body を使用します。To access the message body you can use the context.Request.Body property or the context.Response.Body, depending on whether the policy is in the inbound or outbound section.

重要

既定では、context.Request.Body または context.Response.Body を使用してメッセージ本文にアクセスした場合元のメッセージ本文は失われるため、この本文を式で返して設定する必要があります。Note that by default when you access the message body using context.Request.Body or context.Response.Body, the original message body is lost and must be set by returning the body back in the expression. 本文の内容を保持するには、メッセージへのアクセス時に preserveContent パラメーターを true に設定します。To preserve the body content, set the preserveContent parameter to true when accessing the message. preserveContenttrue に設定している場合に式から別の本文が返されると、返された本文が使用されます。If preserveContent is set to true and a different body is returned by the expression, the returned body is used.

set-body ポリシーを使用する際は次の考慮事項に注意してください。Please note the following considerations when using the set-body policy.

  • set-body ポリシーを使用して新しい本文はまたは更新した本文を返す場合、新しい本文の内容を明示的に指定しているため、preserveContenttrue に設定する必要はありません。If you are using the set-body policy to return a new or updated body you don't need to set preserveContent to true because you are explicitly supplying the new body contents.
    • 受信パイプラインには応答が存在しないため、このパイプラインで応答の内容を保持しても意味がありません。Preserving the content of a response in the inbound pipeline doesn't make sense because there is no response yet.
    • 送信パイプラインで要求の内容を保持しても、要求はこの時点で既にバックエンドに送信されているため意味がありません。Preserving the content of a request in the outbound pipeline doesn't make sense because the request has already been sent to the backend at this point.
    • 受信パイプラインの GET 内など、メッセージ本文がない場合にこのポリシーを使用すると、例外がスローされます。If this policy is used when there is no message body, for example in an inbound GET, an exception is thrown.

詳細については、コンテキスト変数に関する表の context.Request.Body``context.Response.Body``IMessage の各セクションを参照してください。For more information, see the context.Request.Body, context.Response.Body, and the IMessage sections in the Context variable table.

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

<set-body>new body value as text</set-body>

Examples

リテラル テキストの例Literal text example

<set-body>Hello world!</set-body>

文字列である本文にアクセスする例。Example accessing the body as a string. 後からパイプラインでアクセスできるように、元の要求本文を保持していることに注意してください。Note that we are preserving the original request body so that we can access it later in the pipeline.

<set-body>
@{ 
    string inBody = context.Request.Body.As<string>(preserveContent: true); 
    if (inBody[0] =='c') { 
        inBody[0] = 'm'; 
    } 
    return inBody; 
}
</set-body>

JObject である本文にアクセスする例。Example accessing the body as a JObject. 元の要求本文を予約していないため、後でパイプラインでそこにアクセスすると例外が発生することに注意してください。Note that since we are not reserving the original request body, accessing it later in the pipeline will result in an exception.

<set-body> 
@{ 
    JObject inBody = context.Request.Body.As<JObject>(); 
    if (inBody.attribute == <tag>) { 
        inBody[0] = 'm'; 
    } 
    return inBody.ToString(); 
} 
</set-body>

製品に基づいて応答をフィルター処理するFilter response based on product

次の例に、バックエンド サービスから受信した応答で 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>

本文の設定がある Liquid テンプレートの使用Using Liquid templates with set body

set-body ポリシーは、Liquid テンプレート作成言語を使用して要求または応答の本文を変換するように構成できます。The set-body policy can be configured to use the Liquid templating language to transform the body of a request or response. これは、メッセージの形式を完全に再構築する必要がある場合にとても効果的な場合があります。This can be very effective if you need to completely reshape the format of your message.

重要

set-body ポリシーで使用される Liquid の実装は、「C# mode」で構成されます。The implementation of Liquid used in the set-body policy is configured in 'C# mode'. これは、フィルター処理などを実行する際に特に重要です。This is particularly important when doing things such as filtering. たとえば、日付フィルターを使用するには、次のような Pascal 形式と C# date 形式を使用する必要があります。As an example, using a date filter requires the use of Pascal casing and C# date formatting e.g.:

{{body.foo.startDateTime| Date:"yyyyMMddTHH:mm:ddZ"}}{{body.foo.startDateTime| Date:"yyyyMMddTHH:mm:ddZ"}}

重要

Liquid テンプレートを使用して XML 本文に正しくバインドするには、set-header ポリシーを使用して、Content-Type を application/xml、text/xml (または任意の種類の終了 +xml) に設定します。JSON 本文の場合は、application/json、text/json (または任意の種類の終了 +json) にする必要があります。In order to correctly bind to an XML body using the Liquid template, use a set-header policy to set Content-Type to either application/xml, text/xml (or any type ending with +xml); for a JSON body, it must be application/json, text/json (or any type ending with +json).

Liquid テンプレートを使用して JSON を SOAP に変換するConvert JSON to SOAP using a Liquid template

<set-body template="liquid">
    <soap:Envelope xmlns="http://tempuri.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <GetOpenOrders>
                <cust>{{body.getOpenOrders.cust}}</cust>
            </GetOpenOrders>
        </soap:Body>
    </soap:Envelope>
</set-body>

Liquid テンプレートを使用した JSON の変換Transform JSON using a Liquid template

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

要素Elements

名前Name 説明Description 必須Required
set-bodyset-body ルート要素。Root element. 本文のテキストか、または本文を返す式を記載します。Contains the body text or an expressions that returns a body. はいYes

propertiesProperties

名前Name 説明Description 必須Required DefaultDefault
templatetemplate 本文の設定ポリシーが実行されるテンプレート作成モードの変更に使用されます。Used to change the templating mode that the set body policy will run in. 現在サポートされている値:Currently the only supported value is:

- liquid - 本文の設定ポリシーでは、liquid テンプレート作成エンジンが使用されます- liquid - the set body policy will use the liquid templating engine
いいえNo

要求と応答に関する情報にアクセスするために、Liquid テンプレートは次のプロパティでコンテキスト オブジェクトにバインドできます。For accessing information about the request and response, the Liquid template can bind to a context object with the following properties:

context.
    Request.
        Url
        Method
        OriginalMethod
        OriginalUrl
        IpAddress
        MatchedParameters
        HasBody
        ClientCertificates
        Headers

    Response.
        StatusCode
        Method
        Headers
Url.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

OriginalUrl.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

使用法Usage

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

  • ポリシー セクション: inbound、outbound、backendPolicy sections: inbound, outbound, backend

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

HTTP ヘッダーの設定Set HTTP header

set-header ポリシーは、既存の応答ヘッダーまたは要求ヘッダーに値を割り当てるか、新しい応答ヘッダーまたは要求ヘッダーを追加します。The set-header policy assigns a value to an existing response and/or request header or adds a new response and/or request header.

HTTP ヘッダーのリストを HTTP メッセージに挿入します。Inserts a list of HTTP headers into an HTTP message. 受信パイプラインに配置した場合、このポリシーは、ターゲット サービスに渡される要求の HTTP ヘッダーを設定します。When placed in an inbound pipeline, this policy sets the HTTP headers for the request being passed to the target service. 送信パイプラインに配置した場合、このポリシーは、ゲートウェイのクライアントに送信される応答の HTTP ヘッダーを設定します。When placed in an outbound pipeline, this policy sets the HTTP headers for the response being sent to the gateway’s client.

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

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

Examples

例 - ヘッダーの追加、既存のオーバーライドExample - adding header, override existing

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

例 - ヘッダーの削除Example - removing header

 <set-header name="some header name" exists-action="delete" />

バックエンド サービスにコンテキスト情報を転送するForward context information to the backend service

次の例では、API レベルでポリシーを適用して、バックエンド サービスにコンテキスト情報を提供する方法を示します。This example shows how to apply policy at the API level to supply context information to the backend service. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177:More API Management Features」(クラウド カバー エピソード 177: その他の API Management 機能の紹介) を 10: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 10:30. 12:10 に開発者ポータルで操作を呼び出すデモが示されており、このポリシーの動作を確認できます。At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。For more information, see Policy expressions and Context variable.

注意

ヘッダーの複数の値が次のように CSV 文字列に連結されます。headerName: value1,value2,value3Multiple values of a header are concatenated to a CSV string, for example: headerName: value1,value2,value3

値が次の性質を持つ標準化されたヘッダーは例外です。Exceptions include standardized headers, which values:

  • コンマを含む可能性がある (User-AgentWWW-AuthenticateProxy-Authenticate)。may contain commas (User-Agent, WWW-Authenticate, Proxy-Authenticate),
  • 日付を含む可能性がある (CookieSet-CookieWarning)。may contain date (Cookie, Set-Cookie, Warning),
  • 日付を含む (DateExpiresIf-Modified-SinceIf-Unmodified-SinceLast-ModifiedRetry-After)。contain date (Date, Expires, If-Modified-Since, If-Unmodified-Since, Last-Modified, Retry-After).

これらの例外の場合は、複数のヘッダー値が 1 つの文字列に連結されることはなく、次のように個別のヘッダーとして渡されます。User-Agent: value1 User-Agent: value2 User-Agent: value3In case of those exceptions, multiple header values will not be concatenated into one string and will be passed as separate headers, for example: User-Agent: value1 User-Agent: value2 User-Agent: value3

要素Elements

名前Name 説明Description 必須Required
set-headerset-header ルート要素。Root element. はいYes
valuevalue 設定するヘッダーの値を指定します。Specifies the value of the header to be set. 同じ名前のヘッダーが複数ある場合は、value 要素をさらに追加します。For multiple headers with the same name add additional value elements. いいえNo

propertiesProperties

名前Name 説明Description 必須Required DefaultDefault
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
名前name 設定するヘッダーの名前を指定します。Specifies name of the header to be set. はい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

クエリ文字列パラメーターの設定Set query string parameter

set-query-parameter ポリシーは、要求クエリ文字列パラメーターの追加、値の置換、または削除を行います。The set-query-parameter policy adds, replaces value of, or deletes request query string parameter. このポリシーを使用すると、オプションであるかまたは要求内に存在しない、バックエンド サービスで必要とされるクエリ パラメーターを渡すことができます。Can be used to pass query parameters expected by the backend service which are optional or never present in the request.

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

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->
</set-query-parameter>

Examples

Example


<set-query-parameter>
  <parameter name="api-key" exists-action="skip">
    <value>12345678901</value>
  </parameter>
  <!-- for multiple parameters with the same name add additional value elements -->
</set-query-parameter>

バックエンド サービスにコンテキスト情報を転送するForward context information to the backend service

次の例では、API レベルでポリシーを適用して、バックエンド サービスにコンテキスト情報を提供する方法を示します。This example shows how to apply policy at the API level to supply context information to the backend service. このポリシーの構成と使用についてのデモは、「Cloud Cover Episode 177:More API Management Features」(クラウド カバー エピソード 177: その他の API Management 機能の紹介) を 10: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 10:30. 12:10 に開発者ポータルで操作を呼び出すデモが示されており、このポリシーの動作を確認できます。At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">
  <value>@(context.Product.Name)</value>
</set-query-parameter>

詳細については、ポリシー式およびコンテキスト変数に関する各ページを参照してください。For more information, see Policy expressions and Context variable.

要素Elements

名前Name 説明Description 必須Required
set-query-parameterset-query-parameter ルート要素。Root element. はいYes
valuevalue 設定するクエリ パラメーターの値を指定します。Specifies the value of the query parameter to be set. 同じ名前のクエリ パラメーターが複数ある場合は、value 要素をさらに追加します。For multiple query parameters with the same name add additional value elements. はいYes

propertiesProperties

名前Name 説明Description 必須Required DefaultDefault
exists-actionexists-action 対象のクエリ パラメーターが既に指定されている場合の操作を指定します。Specifies what action to take when the query parameter is already specified. この属性の値は次のいずれかに設定する必要があります。This attribute must have one of the following values.

- override - 既存のパラメーターの値を置き換えます。- override - replaces the value of the existing parameter.
- skip - 既存のクエリ パラメーターの値を置き換えません。- skip - does not replace the existing query parameter value.
- append - 既存のクエリ パラメーターの値に値を追加します。- append - appends the value to the existing query parameter value.
- delete - 要求からクエリ パラメーターを削除します。- delete - removes the query parameter from the request.

override に設定した場合、同じ名前の複数のエントリを記載すると、すべてのエントリに従ってクエリ パラメーターが設定されます (複数回記載されます)。結果に設定されるのは記載した値のみです。When set to override enlisting multiple entries with the same name results in the query parameter being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
いいえNo overrideoverride
名前name 設定するクエリ パラメーターの名前を指定します。Specifies name of the query parameter to be set. はいYes 該当なしN/A

使用法Usage

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

  • ポリシー セクション: inbound、backendPolicy sections: inbound, backend

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

URL の書き換えRewrite URL

rewrite-uri ポリシーは、次の例に示すように、要求 URL をパブリックな形式から Web サービスで想定されている形式に変換します。The rewrite-uri policy converts a request URL from its public form to the form expected by the web service, as shown in the following example.

  • パブリック URL - http://api.example.com/storenumber/ordernumberPublic URL - http://api.example.com/storenumber/ordernumber

  • 要求 URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&StateRequest URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

    このポリシーは、人間やブラウザーにとって使いやすい URL を Web サービスで求められる URL 形式に変換する必要がある場合に使用します。This policy can be used when a human and/or browser-friendly URL should be transformed into the URL format expected by the web service. このポリシーを適用する必要があるのは、クリーン URL、RESTful URL、ユーザーフレンドリ URL、SEO フレンドリ URL など、(スキーマと機関の後に) クエリ文字列を含まずリソースのパスのみを含む純粋に構造的な URL のような代替 URL 形式を公開する場合のみです。This policy only needs to be applied when exposing an alternative URL format, such as clean URLs, RESTful URLs, user-friendly URLs or SEO-friendly URLs that are purely structural URLs that do not contain a query string and instead contain only the path of the resource (after the scheme and the authority). これは、一般的に、美学上、使いやすさ、または検索エンジン最適化 (SEO) の目的で行われます。This is often done for aesthetic, usability, or search engine optimization (SEO) purposes.

注意

ポリシーを使用して追加できるのはクエリ文字列パラメーターのみです。You can only add query string parameters using the policy. 書き換え URL にさらにテンプレート パス パラメーターを追加することはできません。You cannot add extra template path parameters in the rewrite URL.

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

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />

Example

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put?c=d -->
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" copy-unmatched-params="false" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put -->

要素Elements

名前Name 説明Description 必須Required
rewrite-urirewrite-uri ルート要素。Root element. はいYes

属性Attributes

AttributeAttribute 説明Description 必須Required DefaultDefault
templatetemplate クエリ文字列パラメーターを設定した実際の Web サービス URL。The actual web service URL with any query string parameters. 式を使用する場合は、値の全体が式である必要があります。When using expressions, the whole value must be an expression. はいYes 該当なしN/A
copy-unmatched-paramscopy-unmatched-params 元の URL テンプレートに存在しない着信要求のクエリ パラメーターを、書き換えテンプレートで定義されている URL に追加するかどうかを指定します。Specifies whether query parameters in the incoming request not present in the original URL template are added to the URL defined by the re-write template いいえNo truetrue

使用法Usage

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

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

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

XSLT を使用した XML の変換Transform XML using an XSLT

Transform XML using an XSLT ポリシーは、要求本文または応答本文に含まれる XML に XSL 変換を適用します。The Transform XML using an XSLT policy applies an XSL transformation to XML in the request or response body.

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

<xsl-transform>
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml" indent="yes" />
        <xsl:param name="User-Agent" />
        <xsl:template match="* | @* | node()">
            <xsl:copy>
                <xsl:if test="self::* and not(parent::*)">
                    <xsl:attribute name="User-Agent">
                        <xsl:value-of select="$User-Agent" />
                    </xsl:attribute>
                </xsl:if>
                <xsl:apply-templates select="* | @* | node()" />
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
  </xsl-transform>

Example

<policies>
  <inbound>
      <base />
  </inbound>
  <outbound>
      <base />
      <xsl-transform>
        <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
            <xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />
            <!-- Copy all nodes directly-->
            <xsl:template match="node()| @*|*">
                <xsl:copy>
                    <xsl:apply-templates select="@* | node()|*" />
                </xsl:copy>
            </xsl:template>
        </xsl:stylesheet>
    </xsl-transform>
  </outbound>
</policies>

要素Elements

名前Name 説明Description 必須Required
xsl-transformxsl-transform ルート要素。Root element. はいYes
パラメーターparameter 変換で使用する変数の定義に使用します。Used to define variables used in the transform いいえNo
xsl:stylesheetxsl:stylesheet ルート スタイルシート要素。Root stylesheet element. この中で定義する要素と属性はすべて、標準的な XSLT の仕様に従う必要があります。All elements and attributes defined within follow the standard XSLT specification はいYes

使用法Usage

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

  • ポリシー セクション: inbound、outboundPolicy sections: inbound, outbound

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

次の手順Next steps

詳細については、次のトピックを参照してください。For more information, see the following topics: