Azure API Management ポリシーでの名前付きの値の使用方法How to use named values in Azure API Management policies

API Management のポリシーは、Azure Portal がその構成を通じて API の動作を変更できる、システムの強力な機能の 1 つです。API Management policies are a powerful capability of the system that allow the Azure portal to change the behavior of the API through configuration. API の要求または応答に対して順に実行される一連のステートメントが集まってポリシーが形成されます。Policies are a collection of statements that are executed sequentially on the request or response of an API. ポリシー ステートメントは、リテラル テキストの値、ポリシーの式、名前付きの値を使用して構築できます。Policy statements can be constructed using literal text values, policy expressions, and named values.

それぞれの API Management サービス インスタンスには、名前付きの値と呼ばれる、サービス インスタンスにグローバルなキー/値ペアのプロパティ コレクションがあります。Each API Management service instance has a properties collection of key/value pairs, which is called named values, that are global to the service instance. コレクション内の項目の数に制限はありません。There is no imposed limit on the number of items in the collection. 名前付きの値を利用し、すべての API の構成とポリシーを対象に、定数文字列値を管理できます。Named values can be used to manage constant string values across all API configuration and policies. 各名前付きの値は、次の属性を持つことができます。Each named value may have the following attributes:

AttributeAttribute 種類Type 説明Description
Display name stringstring ポリシー内の名前付きの値を参照するために使用されます。Used for referencing the named value in policies. 1 から 256 文字の文字列。A string of one to 256 characters. 文字、数字、ドット、ダッシュのみを使用できます。Only letters, numbers, dot, and dash are allowed.
Value stringstring 実際の値。Actual value. 空にしたり、空白のみで構成したりすることはできません。Must not be empty or consist only of whitespace. 最大文字数は 4,096 文字です。Maximum of 4096 characters long.
Secret ブール値boolean 値がシークレットかどうかと暗号化する必要があるかどうかを決定します。Determines whether the value is a secret and should be encrypted or not.
Tags 文字列の配列array of string 名前付きの値の一覧をフィルター処理するために使用されます。Used to filter the named value list. 最大 32 のタグ。Up to 32 tags.

名前付きの値

名前付きの値には、リテラル文字列とポリシー式を含めることができます。Named values can contain literal strings and policy expressions. たとえば、Expression の値は、現在の日時を含む文字列を返すポリシー式です。For example, the value of Expression is a policy expression that returns a string containing the current date and time. 名前付きの値 Credential はシークレットとしてマークされているので、既定では、その値は表示されません。The named value Credential is marked as a secret, so its value is not displayed by default.

NameName ValueValue SecretSecret TagsTags
Value 4242 FalseFalse vital-numbersvital-numbers
資格情報Credential •••••••••••••••••••••••••••••••••••••••••••• TrueTrue securitysecurity
Expression @(DateTime.Now.ToString())@(DateTime.Now.ToString()) FalseFalse

名前付きの値を追加および編集するにはTo add and edit a named value

名前付きの値を追加する

  1. [API Management][API] を選びます。Select APIs from under API MANAGEMENT.

  2. [名前付きの値] を選択します。Select Named values.

  3. [+ 追加] を押します。Press +Add.

    [名前] と [値] は必須値です。Name and Value are required values. 値がシークレットの場合、 [これはシークレットです] チェックボックスをオンにします。If value is a secret, check the This is a secret checkbox. 名前付きの値の整理に役立つ任意のタグを 1 つまたは複数入力し、[保存] をクリックします。Enter one or more optional tags to help with organizing your named values, and click Save.

  4. Create をクリックしてください。Click Create.

名前付きの値が作成されたら、それをクリックして編集できます。Once the named value is created, you can edit it by clicking on it. 名前付きの値の名前を変更すると、その名前付きの値を参照するすべてのポリシーが、その新しい名前を使用するように自動的に更新されます。If you change the named value name, any policies that reference that named value are automatically updated to use the new name.

REST API を利用し、名前付きの値を編集する方法については、REST API を利用して名前付きの値を編集するに関するページを参照してください。For information on editing a named value using the REST API, see Edit a named value using the REST API.

名前付きの値を削除するにはTo delete a named value

名前付きの値を削除するには、削除する名前付きの値の横にある [削除] をクリックします。To delete a named value, click Delete beside the named value to delete.

重要

名前付きの値がいずれかのポリシーで参照されている場合、その名前付きの値を使用しているすべてのポリシーからその値を削除するまで削除は完了しません。If the named value is referenced by any policies, you will be unable to successfully delete it until you remove the named value from all policies that use it.

REST API を利用して名前付きの値を削除する方法については、REST API を使用して名前付きの値を削除するに関するページを参照してください。For information on deleting a named value using the REST API, see Delete a named value using the REST API.

名前付きの値を検索し、フィルター処理するにはTo search and filter named values

[名前付きの値] タブには、名前付きの値の管理に役立つ検索とフィルター処理の機能があります。The Named values tab includes searching and filtering capabilities to help you manage your named values. 名前付きの値の一覧を名前でフィルター処理するには、 [検索プロパティ] テキストボックスに検索語句を入力します。To filter the named values list by name, enter a search term in the Search property textbox. すべての名前付きの値を表示するには、 [検索プロパティ] テキストボックスを消去し、Enter を押します。To display all named values, clear the Search property textbox and press enter.

タグで一覧をフィルター処理するには、 [タグでフィルター] テキストボックスに 1 つまたは複数のタグを入力します。To filter the list by tag, enter one or more tags into the Filter by tags textbox. すべての名前付きの値を表示するには、 [タグでフィルター] テキストボックスを消去し、Enter を押します。To display all named values, clear the Filter by tags textbox and press enter.

名前付きの値を使用するにはTo use a named value

ポリシーで名前付きの値を使用するには、{{ContosoHeader}} のように、二重の括弧の中にその名前を置きます。次に例を示します。To use a named value in a policy, place its name inside a double pair of braces like {{ContosoHeader}}, as shown in the following example:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

この例では、ContosoHeaderset-header ポリシーのヘッダー名として使用されており、ContosoHeaderValue はそのヘッダーの値として使用されています。In this example, ContosoHeader is used as the name of a header in a set-header policy, and ContosoHeaderValue is used as the value of that header. このポリシーが API Management ゲートウェイの要求または応答で評価されるとき、{{ContosoHeader}}{{ContosoHeaderValue}} はそれぞれの値で置換されます。When this policy is evaluated during a request or response to the API Management gateway, {{ContosoHeader}} and {{ContosoHeaderValue}} are replaced with their respective values.

名前付きの値は前の例のように完全な属性または要素値として使用できますが、次の例に示すように、リテラル テキスト表現に挿入するか、その一部と組み合わせることもできます: <set-header name = "CustomHeader{{ContosoHeader}}" ...>Named values can be used as complete attribute or element values as shown in the previous example, but they can also be inserted into or combined with part of a literal text expression as shown in the following example: <set-header name = "CustomHeader{{ContosoHeader}}" ...>

名前付きの値にはポリシー式を含めることもできます。Named values can also contain policy expressions. 次の例では、ExpressionProperty が使用されます。In the following example, the ExpressionProperty is used.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

このポリシーが評価されるとき、{{ExpressionProperty}} はその値 @(DateTime.Now.ToString()) で置換されます。When this policy is evaluated, {{ExpressionProperty}} is replaced with its value: @(DateTime.Now.ToString()). 値がポリシー式であるため、式が評価され、ポリシーがその実行に進みます。Since the value is a policy expression, the expression is evaluated and the policy proceeds with its execution.

名前付きの値が範囲内にあるポリシーを持つ操作を呼び出すことで、開発者ポータルでこれを試すことができます。You can test this out in the developer portal by calling an operation that has a policy with named values in scope. 次の例では、前の 2 つのサンプル set-header ポリシーと名前付きの値で操作が呼び出されています。In the following example, an operation is called with the two previous example set-header policies with named values. ポリシーと名前付きの値を利用して構成された 2 つのカスタム ヘッダーが応答に含まれることに注意してください。Note that the response contains two custom headers that were configured using policies with named values.

[開発者ポータル]

API Inspector トレースを見て、前の 2 つのサンプル ポリシーと名前付きの値が含まれる呼び出しを探すと、ポリシー式が含まれる名前付きの値のポリシー式評価に加え、名前付きの値が挿入された 2 つの set-header ポリシーを確認できます。If you look at the API Inspector trace for a call that includes the two previous sample policies with named values, you can see the two set-header policies with the named values inserted as well as the policy expression evaluation for the named value that contained the policy expression.

API Inspector トレース

名前付きの値にはポリシー式を含めることができますが、他の名前付きの値を含めることはできません。While named values can contain policy expressions, they can't contain other named values. 名前付きの値参照を含むテキストが Text: {{MyProperty}} などの値に使用されている場合、その参照は解決されず、置き換えられません。If text containing a named value reference is used for a value, such as Text: {{MyProperty}}, that reference won't be resolved and replaced.

次の手順Next steps