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 TypeType 説明Description
Display name stringstring ポリシー内のプロパティを参照するために使用されます。Used for referencing the property 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 property 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 property

プロパティの追加

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

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

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

    [名前] と [値] は必須値です。Name and Value are required values. このプロパティの値がシークレットの場合、[これはシークレットです] チェック ボックスをオンします。If this property 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 property is created, you can edit it by clicking on the property. プロパティ名を変更すると、そのプロパティを参照するポリシーも、その新しい名前を使用するように自動的に更新されます。If you change the property name, any policies that reference that property are automatically updated to use the new name.

REST API を利用し、プロパティを編集する方法については、「 Edit a property using the REST API (REST API を利用してプロパティを編集する)」を参照してください。For information on editing a property using the REST API, see Edit a property using the REST API.

プロパティを削除するにはTo delete a property

プロパティを削除するには、削除するプロパティの横にある [削除] をクリックします。To delete a property, click Delete beside the property to delete.

重要

プロパティがポリシーに参照される場合、プロパティを使用するすべてのポリシーからプロパティを削除するまで削除は完了しません。If the property is referenced by any policies, you will be unable to successfully delete it until you remove the property from all policies that use it.

REST API を利用し、プロパティを削除する方法については、「 Delete a property using the REST API (REST API を利用してプロパティを作成する)」を参照してください。For information on deleting a property using the REST API, see Delete a property 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 property list by property 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 property list by tag values, 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 property

ポリシーでプロパティを使用するには、{{ContosoHeader}} のように、二重の括弧の中にプロパティ名を置きます。次に例を示します。To use a property in a policy, place the property 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 property 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 property values inserted as well as the policy expression evaluation for the property that contained the policy expression.

API Inspector トレース

プロパティ値にはポリシー式を含めることができますが、プロパティ値に他の名前付きの値を含めることはできません。While property values can contain policy expressions, property values can't contain other named values. Property value text {{MyProperty}}のように、プロパティ参照を含むテキストが使用されている場合、そのプロパティ参照は置換されず、プロパティ値の一部として追加されます。If text containing a property reference is used for a property value, such as Property value text {{MyProperty}}, that property reference won't be replaced and will be included as part of the property value.

次の手順Next steps