API 管理進階原則

本主題提供下列 API 管理原則的參考。 如需有關新增和設定原則的資訊,請參閱 API 管理中的原則

Advanced 原則

控制流程

choose 原則會根據布林運算式 (類似於 if-then-else 或程式語言中的參數建構) 的評估結果套用括住的原則陳述式。

原則陳述式

<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>

控制流程原則至少必須包含一個 <when/> 元素。 <otherwise/> 則是選擇性元素。 <when/> 元素中的條件會依其在原則內的出現順序進行評估。 系統會套用條件屬性等於 true 的第一個 <when/> 元素內所括住的原則陳述式。 如果所有 <when/> 元素的條件屬性都是 false,則會套用 <otherwise/> 元素內所括住的原則 (如果有的話)。

範例

範例

下列範例示範一個 set-variable 原則和兩個控制流程原則。

設定變數原則位於輸入區段中,並建立 isMobile 布林值內容變數,如果 User-Agent 要求標頭包含文字 iPadiPhone,此變數會設為 true。

第一個控制流程原則也位於 inbound 區段中,並且會按照條件,根據 isMobile 內容變數的值套用兩個設定查詢字串參數原則的其中一個。

第二個控制流程原則位於 outbound 區段中,並且會按照條件,在 isMobile 設為 true 時套用將 XML 轉換為 JSON 原則。

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("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>

範例

這個範例示範如何在使用 Starter 產品時,移除「從後端服務收到的回應」中的資料元素,藉此執行內容篩選。 如需設定和使用此原則的示範,請觀賞 Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky,快轉到 34:30。 從31:50 開始,以瞭解用於此示範的 深天空預測 API

<!-- 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>

元素

元素 描述 必要
choose 根元素。
when 要用於 choose 原則之 ififelse 組件的條件。 如果 choose 原則有多個 when 區段,則會依序評估這些區段。 一旦 when 元素的 condition 評估為 true 後,就不會再評估後面的 when 條件。
otherwise 內含沒有任何 when 條件評估為 true 時,所要使用的原則片段。

屬性

屬性 描述 必要
condition="Boolean expression | Boolean constant" 所包含之 when 原則陳述式受到評估時,所要評估的布林運算式或常數。

使用

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

轉寄要求

forward-request 原則會將內送要求轉送給要求內容中指定的後端服務。 後端服務 URL 是在 API 設定 中指定,而且可以使用 設定後端服務 原則來變更。

注意

移除此原則會導致要求不會轉送到後端服務中,而且當 inbound 區段中的原則一順利完成,就會立即評估 outbound 區段中的原則。

原則陳述式

<forward-request timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

範例

範例

下列 API 層級原則會將所有 API 要求轉寄至後端服務,其逾時間隔為60秒。

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

範例

此作業層級原則使用 base 元素,從父 API 層級範圍繼承後端原則。

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

範例

此作業層級原則會明確地將所有要求轉送至後端服務 (逾時值為 120),且不會繼承父 API 層級的後端原則。 如果後端服務回應的錯誤狀態碼為400到599(含),則會觸發 錯誤 區段。

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

範例

此作業層級原則不會將要求轉送到後端服務。

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

元素

元素 描述 必要
forward-request 根元素。

屬性

屬性 描述 必要 預設
timeout="integer" 在引發逾時錯誤之前,等候後端服務傳回 HTTP 回應標頭的時間長度(以秒為單位)。 最小值為0秒。 可能無法接受大於240秒的值,因為基礎網路基礎結構可能會在這段時間之後卸載閒置連接。 None
跟著-重新導向 = "false | true" 指定來自後端服務的重新導向會由閘道遵循或傳回給呼叫者。 false
緩衝區-要求-主體 = "false | true" 當設定為 "true" 時,會緩衝處理要求,並在 重試時重複使用。 false
緩衝區-回應 = "false | true" 影響區塊回應的處理。 當設定為 "false" 時,從後端收到的每個區塊都會立即傳回給呼叫端。 當設定為 "true" 時,會緩衝處理 (8KB 的區塊,除非偵測到資料流程的結尾) ,而且只傳回給呼叫端。 true
失敗-錯誤-狀態-代碼 = "false | true" 當設為 true 時,會在 錯誤 區段中觸發回應碼,範圍從400到599(含)。 false

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 後端
  • 原則範圍: 所有範圍

限制並行

limit-concurrency 原則可防止超過指定數目的要求在任何時間執行括住的原則。 超出該數目時,新的要求會立即失敗,並產生「429 太多要求」狀態碼。

原則陳述式

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

範例

範例

下列範例示範如何根據內容變數的值,限制轉送至後端的要求數目。

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

元素

元素 描述 必要
limit-concurrency 根元素。

屬性

屬性 描述 必要 預設
索引鍵 字串。 允許的運算式。 指定並行範圍。 可由多個原則共用。 N/A
max-count 整數。 指定允許輸入原則的要求數目上限。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

記錄到事件中樞

log-to-eventhub 原則會將指定格式的訊息傳送至記錄器實體所定義的事件中樞。 此原則正如其名,可用來儲存選取的要求或回應內容資訊,以進行線上或離線分析。

注意

如需如何設定事件中樞和記錄事件的逐步指南,請參閱如何使用 Azure 事件中樞記錄 API 管理事件

原則陳述式

<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>

範例

任何字串皆可做為值來記錄到事件中樞內。 在此範例中,所有輸入呼叫的日期和時間、部署服務名稱、要求識別碼、IP 位址和作業名稱都會記錄到以識別碼註冊的事件中樞記錄器 contoso-logger

<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>

元素

元素 描述 必要
log-to-eventhub 根元素。 此元素的值是要記錄至事件中樞的字串。

屬性

屬性 描述 必要
logger-id 使用您的 API 管理服務註冊之記錄器的識別碼。
partition-id 指定訊息傳送目的地的資料分割索引。 選擇性。 如果使用 partition-key,就不能使用這個屬性。
partition-key 指定在傳送訊息時,用來指派資料分割的值。 選擇性。 如果使用 partition-id,就不能使用這個屬性。

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

Mock 回應

如名稱所示,mock-response 是用來模擬 API 和作業。 它會中止正常的管線執行,並將模擬回應傳回給呼叫者。 原則一律會嘗試傳回最高精確度的回應。 它偏好使用回應內容範例 (若可使用)。 當提供結構描述而無提供範例時,它會從結構描述產生範例回應。 如果沒有找到範例或結構描述,則會傳回沒有內容的回應。

原則陳述式

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

範例

<!-- 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'/>

元素

元素 描述 必要
mock-response 根元素。

屬性

屬性 描述 必要 預設
status-code 指定回應狀態碼,且用來選取對應範例或結構描述。 200
Content-Type 指定 Content-Type 回應標頭值,且用來選取對應範例或結構描述。 None

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、錯誤

  • 原則範圍: 所有範圍

重試

retry原則會執行其子原則一次,然後重試其執行,直到重試 condition 變成 false 或重試 count 用盡為止。

原則陳述式


<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>

範例

下列範例會使用指數重試演算法來重試要求轉送最多十次。 因為 first-fast-retry 設定為 false,所以所有重試嘗試都會使用指數重試演算法。


<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>

元素

元素 描述 必要
retry 根元素。 可包含其他任何原則來做為其子元素。

屬性

屬性 描述 必要 預設
condition (條件) 布林常值或運算式,指定應停止 (false) 還是繼續 (true) 重試。 N/A
count 正數,指定要嘗試的重試次數上限。 N/A
interval 以秒為單位的正數,指定重試嘗試之間的等待間隔。 N/A
max-interval 以秒為單位的正數,指定重試嘗試之間的最大等待間隔。 此屬性可用來實作指數重試演算法。 N/A
delta 以秒為單位的正數,指定等待間隔的增量。 此屬性可用來實作線性和指數的重試演算法。 N/A
first-fast-retry 如果設定為 true ,則會立即執行第一次重試嘗試。 false

注意

當只有指定 interval 時,會執行 固定 間隔的重試。 當只有指定 intervaldelta 時,會使用 線性 的間隔重試演算法,其中,重試之間的等待時間會根據下列公式來進行計算:interval + (count - 1)*delta。 當指定了 intervalmax-intervaldelta 時,則會套用 指數 的間隔重試演算法,其中,重試之間的等待時間會根據下列公式,以指數方式從 interval 的值增加到 max-interval 的值:min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval)

使用方式

此原則可用於下列原則區段範圍。 請注意,此原則會繼承子原則的使用方式限制。

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

傳回回應

return-response 原則會中止管線的執行,並將預設或自訂的回應傳回給呼叫者。 預設回應是 200 OK,且沒有本文。 透過內容變數或原則陳述式即可指定自訂回應。 若同時提供兩者,原則陳述式會先修改內容變數中包含的回應,再傳回給呼叫者。

原則陳述式

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

範例

<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>

元素

元素 描述 必要
return-response 根元素。
set-header set-header 原則陳述式。
set-body set-body 原則陳述式。
set-status set-status 原則陳述式。

屬性

屬性 描述 必要
response-variable-name 所參考的內容變數名稱,其參考來源為 (舉例來說) 上游 send-request 原則,且包含 Response 物件 選擇性。

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

傳送單向要求

send-one-way-request 原則會將所提供的要求傳送到指定的 URL,無須等待回應。

原則陳述式

<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>

範例

此一相同原則會舉例說明如何使用 send-one-way-request 原則,以在 HTTP 回應碼大於或等於 500 時,將訊息傳送至 Slack 聊天室。 如需此範例的詳細資訊,請參閱使用來自 Azure API 管理服務的外部服務

<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>

元素

元素 描述 必要
send-one-way-request 根元素。
url 要求的 URL。 mode=copy 時為 [否];否則為 [是]。
method 要求的 HTTP 方法。 mode=copy 時為 [否];否則為 [是]。
header 要求標頭。 若有多個要求標頭,請使用多個 header 元素。
body 要求本文。
authentication-certificate 用於用戶端驗證的憑證

屬性

屬性 描述 必要 預設
mode="string" 判斷這是新要求還是現行要求的複本。 在輸出模式中,mode=copy 不會初始化要求本文。 新增
NAME 指定要設定之標頭的名稱。 N/A
exists-action 指定當已指定標頭時要採取的動作。 此屬性必須具有下列其中一個值。

-override-取代現有標頭的值。
-skip-不取代現有的標頭值。
-append-將值附加至現有的標頭值。
-delete-移除要求中的標頭。

設為 override 時,編列多個相同名稱的項目會導致根據所有項目來設定標頭 (列出多次);只有列出的值才會設定在結果中。
override

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

傳送要求

send-request 原則會將所提供的要求傳送至指定的 URL,等候時間不會超過所設定的逾時值。

原則陳述式

<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>

範例

此範例會顯示向授權伺服器確認參考權杖的方法。 如需此範例的詳細資訊,請參閱使用來自 Azure API 管理服務的外部服務

<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>

元素

元素 描述 必要
send-request 根元素。
url 要求的 URL。 mode=copy 時為 [否];否則為 [是]。
method 要求的 HTTP 方法。 mode=copy 時為 [否];否則為 [是]。
header 要求標頭。 若有多個要求標頭,請使用多個 header 元素。
body 要求本文。
authentication-certificate 用於用戶端驗證的憑證

屬性

屬性 描述 必要 預設
mode="string" 判斷這是新要求還是現行要求的複本。 在輸出模式中,mode=copy 不會初始化要求本文。 新增
response-variable-name="string" 將會收到回應物件之內容變數的名稱。 如果變數不存在,則會在原則成功執行時建立,且將可透過 context.Variable 集合存取。 N/A
timeout="integer" 以秒為單位的逾時間隔,URL 的呼叫在經過此間隔後便會失敗。 60
ignore-error 如果為 true,則要求會導致錯誤︰

-如果指定了回應變數名稱,則會包含 null 值。
-如果未指定回應變數名稱,則為 coNtext。將不會更新要求。
false
NAME 指定要設定之標頭的名稱。 N/A
exists-action 指定當已指定標頭時要採取的動作。 此屬性必須具有下列其中一個值。

-override-取代現有標頭的值。
-skip-不取代現有的標頭值。
-append-將值附加至現有的標頭值。
-delete-移除要求中的標頭。

設為 override 時,編列多個相同名稱的項目會導致根據所有項目來設定標頭 (列出多次);只有列出的值才會設定在結果中。
override

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

設定 HTTP Proxy

proxy 原則可讓您透過 HTTP Proxy 將要求路由轉送至後端。 在閘道與 Proxy 之間僅支援 HTTP (不是 HTTPS)。 僅限基本和 NTLM 驗證。

原則陳述式

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

範例

請注意,其中使用屬性作為 username 和 password 的值,以避免將機密資訊儲存在原則文件中。

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

元素

元素 描述 必要
proxy 根元素

屬性

屬性 描述 必要 預設
url="string" http://host:port 格式的 Proxy URL。 N/A
username="string" 用於向 Proxy 驗證的使用者名稱。 N/A
password="string" 用於向 Proxy 驗證的密碼。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ inbound

  • 原則範圍: 所有範圍

設定要求方法

set-method 原則允許您變更要求的 HTTP 要求方法。

原則陳述式

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

範例

這個使用 set-method 原則的相同原則會舉例說明如何在 HTTP 回應碼大於或等於 500 時,將訊息傳送至 Slack 聊天室。 如需此範例的詳細資訊,請參閱使用來自 Azure API 管理服務的外部服務

<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>

元素

元素 描述 必要
set-method 根元素。 元素的值會指定 HTTP 方法。

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、錯誤

  • 原則範圍: 所有範圍

設定狀態碼

set-status 原則會將 HTTP 狀態碼設為指定值。

原則陳述式

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

範例

此範例會說明如何在授權權杖無效時傳回 401 回應。 如需詳細資訊,請參閱使用來自 Azure API 管理服務的外部服務

<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>

元素

元素 描述 必要
set-status 根元素。

屬性

屬性 描述 必要 預設
code="integer" 要傳回的 HTTP 狀態碼。 N/A
reason="string" 狀態碼傳回原因的描述。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸出、後端、錯誤
  • 原則範圍: 所有範圍

設定變數

set-variable 原則會宣告內容變數,並對其指派透過運算式或字串常值指定的值。 包含常值的運算式會轉換成字串,且值的類型為 System.String

原則陳述式

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

範例

下列範例會示範 inbound 區段中的設定變數原則。 此設定變數原則建立 isMobile 布林值內容變數,如果 User-Agent 要求標頭包含文字 iPadiPhone,此變數會設為 true。

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

元素

元素 描述 必要
set-variable 根元素。

屬性

屬性 描述 必要
NAME 變數的名稱。
value 變數的值。 此值可為運算式或常值。

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤
  • 原則範圍: 所有範圍

允許的類型

set-variable 原則中使用的運算式必須傳回下列其中一個基本類型。

  • System.Boolean
  • System.SByte
  • System.Byte
  • System.UInt16
  • System.UInt32
  • System.UInt64
  • System.Int16
  • System.Int32
  • System.Int64
  • System.Decimal
  • System.Single
  • System.Double
  • System.Guid
  • System.String
  • System.Char
  • System.DateTime
  • System.TimeSpan
  • System.Byte?
  • System.UInt16?
  • System.UInt32?
  • System.UInt64?
  • System.Int16?
  • System.Int32?
  • System.Int64?
  • System.Decimal?
  • System.Single?
  • System.Double?
  • System.Guid?
  • System.String?
  • System.Char?
  • System.DateTime?

跟蹤

trace原則會將自訂追蹤新增至 API 偵測器輸出、Application Insights 遙測和(或)資源記錄。

  • 當觸發追蹤時,原則會將自訂追蹤新增至 API 偵測器 輸出,也 Ocp-Apim-Trace 就是要求標頭存在且設為 true,而且 Ocp-Apim-Subscription-Key 要求標頭存在且保存有效的金鑰以允許追蹤。
  • Application Insights 整合已啟用,而且 severity 原則中指定的等於或大於診斷設定中指定的時,原則會在 Application Insights 中建立追蹤遙測 verbosity
  • 資源記錄 已啟用,而且原則中指定的嚴重性層級等於或高於診斷設定中指定的詳細等級時,原則會在記錄專案中新增屬性。

原則陳述式


<trace source="arbitrary string literal" severity="verbose|information|error">
    <message>String literal or expressions</message>
    <metadata name="string literal or expressions" value="string literal or expressions"/>
</trace>

範例

<trace source="PetStore API" severity="verbose">
    <message>@((string)context.Variables["clientConnectionID"])</message>
    <metadata name="Operation Name" value="New-Order"/>
</trace>

元素

元素 描述 必要
追蹤 根元素。
message 要記錄的字串或運算式。
中繼資料 將自訂屬性新增至 Application Insights 的 追蹤 遙測。

屬性

屬性 描述 必要 預設
source 對追蹤檢視器有意義,並指定了訊息來源的字串常值。 N/A
severity 指定追蹤的嚴重性層級。 允許的值為 verboseinformationerror (從最低到最高) 。 「詳細資訊」
NAME 屬性的名稱。 N/A
value 屬性的值。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端、錯誤

  • 原則範圍: 所有範圍

wait 原則會以平行方式執行其直屬子原則,並等候其所有或其中一個直屬子原則完成後再完成。 等候原則可擁有做為其直屬子原則傳送要求從快取取得值控制流程原則。

原則陳述式

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

範例

在下列範例中,有兩個 choose 原則做為 wait 原則的直屬子原則。 在這些 choose 原則中,每一個都會以平行方式執行。 每個 choose 原則都會嘗試擷取快取的值。 如果有快取遺漏,便會呼叫後端服務以提供值。 在此範例中,因為 for 屬性設為 all,所以要等到其所有直屬子原則完成後,wait 原則才會完成。 在此範例中,內容變數 (execute-branch-onevalue-oneexecute-branch-twovalue-two) 會在此範例原則的範圍之外進行宣告。

<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>

元素

元素 描述 必要
wait 根元素。 只能包含做為子元素 send-requestcache-lookup-valuechoose 原則。

屬性

屬性 描述 必要 預設
對象 決定 wait 原則是要等候所有直屬子原則完成或只等候一個完成。 允許的值包括:

- all - 等候所有直屬子原則完成
-any-等待任何直屬子原則完成。 第一個直屬子原則完成後,wait 原則便會完成,並終止執行任何其他直屬子原則。
all

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸入、輸出、後端
  • 原則範圍: 所有範圍

下一步

如需使用原則的詳細資訊,請參閱︰