TraceCapture 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

總覽

您可以使用 TraceCapture 政策，在 Apigee 執行階段的追蹤資料中新增其他變數。如果您已為 Apigee 執行階段啟用分散式追蹤功能，則執行階段預設會追蹤一組預先定義的變數。詳情請參閱「追蹤報表中的預設追蹤變數」。不過，如果您希望 Apigee 執行階段追蹤其他流程、政策或自訂變數，請使用 TraceCapture 政策。您可以在要求或回應流程中使用這項政策。在分散追蹤報表中，您可以查看 TraceCapture 政策在 TraceCaptureExecution 區段中新增的變數。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

<TraceCapture>

定義 TraceCapture 政策。

預設值 不適用
是否必要？ 必填
類型 複雜類型
上層元素 N/A
子元素 <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

<TraceCapture> 元素使用以下語法：

語法

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
    <Variables>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
</TraceCapture>

範例

以下範例顯示 TraceCapture 政策定義：

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>Distributed-Trace-Capture-Policy-1</DisplayName>
    <Variables>
        <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
        <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
</TraceCapture>

這個元素包含下列所有政策都適用的屬性：

屬性 預設 是否必要？ 說明
name 不適用 必要

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
enabled 是 選用 設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async   false 已淘汰 此屬性已淘汰。

下表概略說明 <TraceCapture> 的子元素：

子元素 是否必要 說明
<DisplayName> 選用 指定政策的自訂名稱。
<Variables> 選用 指定要追蹤的變數清單。
<IgnoreUnresolvedVariables> 選用 指定在遇到未解析的變數時是否停止處理。
<ThrowExceptionOnLimit> 選用 指定變數大小若超過 256 個位元組的限制，是否必須截斷。
其他子元素
<MergeBehavior> 選用 指定回覆訊息的合併行為。

子元素參照

本節將說明 <TraceCapture> 的子元素。

<DisplayName>

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

預設值 不適用
是否必要？ (非必要) 如果省略 <DisplayName>，系統會使用政策的 name 屬性值。
類型 字串
上層元素 <PolicyElement>
子元素 無

<DisplayName> 元素使用以下語法：

語法

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

範例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素沒有屬性或子項元素。

<Variables>

指定要追蹤的變數清單。

預設值 不適用
是否必要？ 必填
類型 複雜類型
上層元素 <TraceCapture>
子元素 <Variable>

<Variables> 元素使用以下語法：

語法

<Variables>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
</Variables>

範例

以下範例會追蹤 flow-variable-1 和 flow-variable-2 流程變數：

<Variables>
    <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
    <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
</Variables>

<Variable>

指定要在追蹤記錄資料中新增的變數。

預設值 不適用
是否必要？ 必填
類型 複雜類型
上層元素 <Variables>
子元素 無

<Variable> 元素使用以下語法：

語法
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
範例

以下範例會將 trace-variable-1 追蹤變數設為 flow-variable-1 資料流變數的值：

<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>

如果無法使用 flow-variable-1 流程變數，trace-variable-1 會設為預設值 default-val-1。

下表說明 <Variable> 的屬性：

屬性 是否必要 類型 說明
name 必填 字串 用於參照為指定變數收集的資料的名稱。這個名稱會顯示在分散追蹤報表中。
ref 必填 字串 您要收集追蹤記錄資料的變數。這個變數可以是 Apigee 預先定義的流程變數，或是 API Proxy 中的自訂變數。

<IgnoreUnresolvedVariables>

判斷遇到未解析的變數時是否停止處理。

預設值 不適用
是否必要？ 選用
類型 布林值
上層元素 <TraceCapture>
子元素 無

將其設為 true 可忽略未解析的變數並繼續處理；否則為 false。預設值為 true。

將 <IgnoreUnresolvedVariables> 設為 true 與將 <TraceCapture> 的 continueOnError 設為 true 不同。如果將 continueOnError 設為 true，Apigee 會忽略所有錯誤，而非只忽略變數中的錯誤。

<IgnoreUnresolvedVariables> 元素使用以下語法：

語法

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

範例

以下範例將 <IgnoreUnresolvedVariables> 設為 false：

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

指定變數大小超過 256 位元組限制時的政策行為。

  • 如果設為 true，當變數大小超過限制時，政策就會擲回錯誤。
  • 如果設為 false，政策會截斷超出限制的變數。變數會截斷至限制的大小。
預設值 不適用
是否必要？ 選用
類型 布林值
上層元素 <TraceCapture>
子元素 無

<ThrowExceptionOnLimit> 元素使用以下語法：

語法

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

範例

以下範例將 <ThrowExceptionOnLimit> 值設為 true。

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因
steps.tracecapture.UnresolvedVariable 500

如果 TraceCapture 政策中指定的變數為下列任一情況，就會發生這個錯誤：

  • 超出範圍 (無法在執行政策的特定流程中使用)
    • 或
  • 無法解析 (未定義)
steps.tracecapture.VariableValueLimitExceeded 500

如果 <ThrowExceptionOnLimit> 元素設為 true，且任何變數的大小超過 256 個位元組，就會發生此錯誤。

錯誤變數

每當政策發生執行錯誤時，Apigee 就會產生錯誤訊息。您可以在錯誤回應中查看這些錯誤訊息。很多時候，系統產生的錯誤訊息可能與產品情境無關。您可能會根據錯誤類型自訂錯誤訊息，讓訊息更有意義。

如要自訂錯誤訊息，您可以使用錯誤規則或 RaiseFault 政策。如要瞭解錯誤規則和 RaiseFault 政策的差異，請參閱 FaultRules 與 RaiseFault 政策。您必須在錯誤規則和 RaiseFault 政策中使用 Condition 元素檢查條件。Apigee 會提供每項政策專屬的錯誤變數，而錯誤變數的值會在政策觸發執行階段錯誤時設定。您可以使用這些變數，檢查特定錯誤情況並採取適當行動。如要進一步瞭解如何檢查錯誤條件，請參閱「建構條件」。

下表說明這項政策的特定錯誤變數。

變數 地點 範例
fault.name fault.name 可與「執行階段錯誤」表格中列出的任何錯誤相符。 錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed POLICY_NAME 是擲回錯誤的政策的使用者指定名稱。 tracecapture.trace-capture-1.failed = true
如要進一步瞭解政策錯誤，請參閱「關於政策錯誤的相關資訊」。