本頁面由 Cloud Translation API 翻譯而成。

DataCapture 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

DataCapture 政策會從 API Proxy 擷取資料 (例如酬載、HTTP 標頭，以及路徑或查詢參數)，以供 Analytics 使用。您可以在自訂 Analytics 報表中使用擷取的資料，也可以用來實作營利和監控規則。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

資料收集器資源

如要使用 DataCapture 政策，您必須先建立資料收集器資源。如要瞭解如何使用 Apigee UI 和 Apigee API 建立資料收集器資源，請參閱建立資料收集器。

`<DataCapture>`

<DataCapture> 元素會定義 DataCapture 政策。

<DataCapture async="true" continueOnError="true" enabled="true" name="DC">

以下是 DataCapture 政策的範例：

<DataCapture name="DC-1">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="my_data_variable" />
    </Capture>
</DataCapture>

DataCapture 政策的主要元素是 <Capture> 元素，用於指定擷取資料的方式。必須使用下列兩個子元素：

<DataCollector> 元素，用於指定資料收集器 REST 資源。在本例中，資源名稱為 dc_data_collector。
<Collect> 元素，用於指定擷取資料的方式。

在這個簡單的範例中，資料是從名為 my_data_variable 的變數中擷取，該變數已在 Proxy 的其他位置建立。變數是由 ref 屬性指定。

<Collect> 元素也提供其他幾種方式，透過子項元素從各種來源擷取資料。如需更多使用 DataCapture 政策擷取資料的範例，請參閱「範例」。

注意：你可以使用多個 <Capture> 元素，但必須為各自的子項 <DataCollector 元素使用不同的值。舉例來說，如果您定義了另一個名為 dc_data_collector2 的資料收集器資源，可以將下列 <Capture> 區塊新增至上述政策：

    <Capture>
        <DataCollector>dc_data_collector2</DataCollector>
            <Collect ref="my_data_variable2"/>
    </Capture>

不過，您無法在同一項政策中，納入兩個參照相同資料收集器資源的 <Capture> 元素。

DataCapture 元素的語法如下。

<DataCapture name="capturepayment" continueOnError="false" enabled="true"> 
  <DisplayName>Data-Capture-Policy-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

  <!-- Existing Variable -->
  <Capture>
    <Collect ref="existing-variable" default="0"></Collect>
    <DataCollector>dc_1</DataCollector>
  </Capture>

  <!-- JSONPayload -->
  <Capture>
    <DataCollector>dc_2</DataCollector>
    <Collect default="0">
      <Source>request</Source>
      <JSONPayload>
        <JSONPath>result.var</JSONPath>
      </JSONPayload>
    </Collect>
  </Capture>

  <!-- URIPath -->
  <Capture>
    <DataCollector>dc_3</DataCollector>
    <Collect default="0">
      <URIPath>
        <!-- All patterns must specify a single variable to extract named $ -->
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
        <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
      </URIPath>
    </Collect>
  </Capture>
</DataCapture>

注意：DataCapture 政策的部分元素與同名的 ExtractVariables 政策元素行為不同。包括： <URIPath>、 <QueryParam>、 <Header>、 <FormParam>、 <JSONPayload> 和 <XMLPayload>。

如要瞭解這些元素在 DataCapture 政策中的運作方式，請參閱 <Collect> 的子元素。

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

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

下表提供 <DataCapture> 子元素的高階說明。

子元素	必填	說明
`<Capture>`	必填	擷取指定變數的資料。

範例

下列範例說明如何以各種方式使用 DataCapture 政策。

擷取內建變數的資料

以下程式碼範例說明如何擷取內建變數 message.content 的資料，其中包含要求、回應或錯誤訊息的內容。如要進一步瞭解內建變數，請參閱「流程變數」。

<DataCapture name="DC-FullMessage">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="message.content" />
    </Capture>
</DataCapture>

在上方程式碼中，</Collect> 元素的 ref 屬性會指定要擷取的變數，在本例中，該變數名為 "message.content"。

範例會使用 <Capture> 元素擷取資料，其中也包含 <DataCollector> 元素，用於指定資料收集器資源的名稱。

內嵌擷取資料

下一個範例說明如何使用 <Collect> 元素的子項元素 <JSONPayload>，擷取內嵌資料。

<DataCapture name="DC-Currency">
    <Capture>
        <DataCollector>dc_data_collector<DataCollector>
        <Collect>
            <JSONPayload>
                <JSONPath>$.results[0].currency</JSONPath>
            </JSONPayload>
        </Collect>
    </Capture>
</DataCapture>

在上述程式碼中：

<JSONPayload> 元素會指定 JSON 格式的訊息，系統會從中擷取變數值。
<JSONPath> 元素會指定用於從訊息中擷取值的 JSON 路徑，在本例中為 $.results[0].currency。

舉例來說，假設系統在收到訊息時擷取的值為 1120。然後，傳送至 Analytics 的結果項目會是

{
    "dc_data_collector": "1120"
}

<Capture>

<Capture> 元素會指定擷取資料的方式。

<Capture />

下表提供 <Capture> 子元素的高階說明。

子元素	是否必要	說明
`<DataCollector>`	必要	指定資料收集器資源。
`<Collect>`	必要	指定擷取資料的方式。

<DataCollector>

<DataCollector> 元素會指定資料收集器資源。

<DataCollector>dc_data_collector</DataCollector>

下表說明 <DataCollector> 元素的屬性。

屬性	說明	預設	是否必要	類型
範圍	如要擷取營利變數，請指定這個屬性並將值設為 `monetization`。如要進一步瞭解可擷取的營利變數，請參閱「擷取營利資料」。	不適用	選用	字串

<DataCollector> 元素的本文包含資料收集器資源的名稱。

<Collect>

<Collect> 元素會指定擷取資料的方式。

<Collect ref="existing-variable" default="0"/>

下表說明 <Collect> 元素的屬性。

屬性	說明	預設	是否必要	類型
ref	您要擷取資料的變數。	不適用	選用 - 如果省略 `ref`，則必須指定下列其中一項： `QueryParam`、 `Header`、 `FormParam`、 `URIPath`、 `JSONPayload` 或 `XMLPayload`。	字串
預設	指定在執行階段未填入變數值時，要傳送至 Analytics 的值。舉例來說，如果您設定 `default="0"`，傳送至 Analytics 的值會是 0。	如未指定 `default` 的值，且變數的值在執行階段未填入，則傳送至 Analytics 的值會是數字變數的 `null` 或字串變數的 `"Not set"`。	必填	字串

您可以使用 ref 屬性從現有變數擷取資料，也可以使用子元素 <Collect>。

`<Collect>` 的子元素

下表提供 <Collect> 子元素的高階說明：

注意：下列 <Collect> 的子元素行為，與 ExtractVariables「ExtractVariables」政策中名稱相同的對應元素不同。

子元素	是否必要	說明
`<Source>`	選用	指定要剖析的變數。
`<URIPath>`	選用	從要求來源訊息的 `proxy.pathsuffix` 擷取值。
`<QueryParam>`	選用	從要求來源訊息的指定查詢參數中擷取值。
`<Header>`	選用	從指定要求或回應訊息的指定 HTTP 標頭中擷取值。
`<FormParam>`	選用	從指定要求或回應訊息的指定表單參數中擷取值。
`<JSONPayload>`	選用	指定要從中擷取變數值的 JSON 格式訊息。注意：與 ExtractVariables 政策中的對應元素不同，`DataCapture` 政策中的 `<JSONPayload>` 元素不需要 `<Variable>` 元素，也不會與其巢狀化。
`<XMLPayload>`	選用	指定要從中擷取變數值的 XML 格式訊息。注意：與 ExtractVariables 政策中的對應元素不同，`DataCapture` 政策中的 `<XMLPayload>` 元素不需要或巢狀包含 `<Variable>` 元素。

<Source>

指定變數，命名要剖析的訊息。<Source> 的值預設為 message。message 值會因情境而異。在要求流程中，message 會解析為要求訊息。在回覆流程中，message 會解析為回覆訊息。

如果無法解析 <Source> 中指定的變數，或解析為非訊息類型，政策將無法回應。

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<Collect>`
子元素	不適用

<Source >request</Source>

<URIPath>

從 request 來源訊息的 proxy.pathsuffix 擷取值。套用至模式的路徑是 proxy.pathsuffix，不包含 API Proxy 的 basepath。如果來源訊息解析為 response 訊息類型，這個元素不會執行任何動作。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	<Pattern>

屬性

屬性	說明	預設	是否必要	類型
ignoreCase	指定比對模式時忽略大小寫。	false	選用	布林值

<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

你可以使用多個 <Pattern> 元素：

<URIPath>
   <Pattern ignoreCase="false">/foo/{$}</Pattern>
   <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
</URIPath>

注意：您必須指定名為 {$} 的單一變數。可能有多個不重複的 Pattern 元素，但系統會為特定要求解析第一個相符模式。

<QueryParam>

從 request 來源訊息的指定查詢參數中擷取值。如果來源訊息解析為 response 訊息類型，這個元素不會執行任何動作。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	<Pattern>

屬性

屬性	說明	預設	是否必要	類型
名稱	指定查詢參數的名稱。如果多個查詢參數的名稱相同，請使用索引參照，其中查詢參數的第一個例項沒有索引，第二個例項的索引為 2，第三個例項的索引為 3，依此類推。	不適用	必填	字串

<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

如果多個查詢參數的名稱相同，請使用索引參照參數：

<Collect>
    <QueryParam name="code.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

注意：您必須指定名為 {$} 的單一變數。可能有多個不重複的 Pattern 元素，但系統會針對特定要求解析第一個相符模式。

<Header>

從指定 request 或 response 訊息的指定 HTTP 標頭中擷取值。如果多個標頭的名稱相同，這些標頭的值會儲存在陣列中。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	<Pattern>

屬性

屬性	說明	預設	是否必要	類型
名稱	指定要從中擷取值的標頭名稱。如果多個標頭的名稱相同，請使用索引參照，其中第一個標頭例項沒有索引，第二個標頭例項的索引為 2，第三個標頭例項的索引為 3，依此類推。使用 `.values` 即可取得陣列中的所有標頭。	不適用	必填	字串

<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

如果多個標頭的名稱相同，請使用陣列中的索引參照個別標頭：

<Collect>
    <Header name="my_header.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

或者，您也可以使用下列指令列出陣列中的所有標題：

<Collect>
    <Header name="my_header.values">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

注意：您必須指定名為 {$} 的單一變數。可能有多個不重複的 Pattern 元素，但系統會為特定要求解析第一個相符模式。

<FormParam>

從指定 request 或 response 訊息的指定表單參數中擷取值。只有在指定郵件的 Content-Type 標頭為 application/x-www-form-urlencoded 時，才能擷取表單參數。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	<Pattern>

屬性

屬性	說明	預設	是否必要	類型
名稱	您要從中擷取值的表單參數名稱。	不適用	選用	字串

<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

注意：您必須指定名為 {$} 的單一變數。可能有多個不重複的 Pattern 元素，但系統會為特定要求解析第一個相符模式。

<JSONPayload>

指定要從中擷取變數值的 JSON 格式訊息。只有在郵件的 Content-Type 標頭為 application/json 時，才會執行 JSON 擷取作業。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	<JSONPath>

<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

注意：與 ExtractVariables 政策中的對應元素不同，DataCapture 政策中的 <JSONPayload> 元素不需要 <Variable> 元素，也不會與其巢狀化。

<JSONPath>

<JSONPayload> 元素的必要子元素。指定用於從 JSON 格式訊息中擷取值的 JSON 路徑。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<JSONPayload>`
子元素	不適用

注意：<JSONPath> 元素支援稱為訊息範本的動態字串替代功能。

<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

指定 XML 格式的訊息，系統會從中擷取變數值。只有在郵件的 Content-Type 標頭為 text/xml、application/xml 或 application/*+xml 時，系統才會擷取 XML 酬載。

預設值	不適用
必填與否	選用
類型	複雜
父項元素	`<Collect>`
子元素	`<Namespaces>` `<XPath>`

下表提供 <XMLPayload> 子元素的高階說明。

子元素	是否必要	說明
`<Namespaces>`	選用	指定要在 XPath 評估中使用的零或多個命名空間。
`<XPath>`	必填	指定為變數定義的 XPath。

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
            <Namespace prefix="ns1">http://ns1.example.com/operations</Namespace>
        </Namespaces>
        <!-- get the local name of the SOAP operation -->
        <XPath>local-name(/soap:Envelope/soap:Body/ns1:*[1])</XPath>
    </XMLPayload>
</Collect>

注意：與 ExtractVariables 政策中的 <XMLPayload> 元素不同，DataCapture 政策中的 <XMLPayload> 元素不會巢狀內嵌於 <Variable> 元素中。

<Namespaces>

指定可在 XPath 運算式中使用的命名空間集。範例

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
            <Namespace prefix="places">http://places.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint/places:name</XPath>
    </XMLPayload>
</Collect>

如果您未在 XPath 運算式中使用命名空間，可以省略或註解掉 <Namespaces> 元素，如下例所示：

<Collect>
    <XMLPayload>
        <!-- <Namespaces/> -->
        <XPath>/Directions/route/leg/name</XPath>
    </XMLPayload>
</Collect>

<Namespace>

指定一個命名空間和對應的前置字元，供 XPath 運算式使用。範例

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<Namespaces>`
子元素	不適用

屬性

屬性	說明	預設	是否必要	類型
`prefix`	您在 XPath 運算式中參照命名空間時使用的前置字元。這不一定要與原始 XML 文件中使用的前置字元相同。	不適用	必填	字串

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint</XPath>
    </XMLPayload>
</Collect>

<XPath>

XMLPayload 元素的必要子元素。指定為變數定義的 XPath。系統僅支援 XPath 1.0 運算式。

預設值	不適用
必填與否	必填
類型	字串
父項元素	`<XMLPayload>`
子元素	不適用

<XPath> 元素不支援訊息範本。

   <XPath>/test/example</XPath>

注意：如果在 XPath 運算式中使用命名空間，您必須在政策的 <XMLPayload><Namespaces> 區段中宣告命名空間。

注意：Apigee 不支援在 XPath 運算式中使用 parent、ancestor、following 和 preceding。如要取得相同的比對結果，請嘗試明確比對或建立節點名稱索引。例如：

<XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
取得 foo_attribute 的值。
<XPath>/Attributes/Attribute[4]/Value</XPath>
取得第 4 個屬性的值。

<ThrowExceptionOnLimit>

<ThrowExceptionOnLimit> 元素會指定達到變數數量或變數大小上限時的處理方式。請參閱「強制執行擷取限制」。

<ThrowExceptionOnLimit> 的值可設為下列任一選項：

false：變數的資料會傳送至 Analytics。
true：系統會傳回錯誤訊息，且不會將資料傳送至 Analytics。

錯誤參考資料

執行階段錯誤

下表說明政策執行時可能發生的執行階段錯誤。

錯誤碼	原因
`DataCollectorTypeMismatch`	要擷取的值與 `DataCollector` 類型不符。
`ExtractionFailure`	資料擷取作業失敗。
`UnresolvedVariable`	變數不存在。
`VariableCountLimitExceeded`	擷取的變數數量超過 100 個變數的上限
`VariableValueLimitExceeded`	擷取的值超過單一變數的 400 位元組限制。
`MsgContentParsingFailed`	無法將訊息內容剖析為 XML 或 JSON。
`InvalidMsgContentType`	郵件內容類型與政策擷取子句中預期的郵件內容類型不符。
`NonMsgVariable`	`<Source>` 元素值未參照訊息變數。
`JSONPathQueryFailed`	`JSONPath` 查詢無法解析為值。
`PrivateVariableAccess`	嘗試存取私有變數失敗。
`XPathEvaluationFailed`	`XPath` 無法解析為值。

系統會透過下列兩種方式傳回執行階段錯誤：

錯誤回應傳回給用戶端 (continueOnError=false)
如果政策的 continueOnError 屬性設為 false，政策執行期間發生的錯誤會中止訊息處理作業，並傳回說明性錯誤訊息。政策會嘗試擷取資料擷取政策中的所有相關錯誤，然後傳回訊息。

DataCapture 錯誤分析欄位

dataCapturePolicyErrors 欄位會列出所有發生的錯誤。以下範例顯示這類資料在 Analytics 資料對應中的顯示方式：

# Example payload
[
     {
         errorType: TypeMismatch,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchaseValue
     },
     {
         errorType: MaxValueSizeLimitReached,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchasedItems
     },
]

這個欄位的大小上限為 400 個位元組。

部署錯誤

錯誤碼	原因
`DeploymentAssertionError`	部署期間，系統在機構中找不到政策參照的 DataCollector。
`JsonPathCompilationFailed`	使用指定的 `JSONPath` 編譯失敗。
`XPathCompilationFailed`	如果 `XPath` 元素中使用的前置字元或值不屬於政策中任何已宣告的命名空間，API 代理伺服器部署作業就會失敗。
`PatternCompilationFailed`	模式編譯失敗。

在偵錯工具中找出 `DataCapture` 錯誤

「偵錯」工具中會顯示 dataCapturePolicyErrors 變數。這是額外工具，可協助您在不前往 Analytics 的情況下找出錯誤。舉例來說，如果您升級混合式執行階段版本，不慎中斷已部署 Proxy 中的 Analytics，即可偵測到錯誤。

強制執行擷取限制

Apigee 會對擷取資料中的變數強制執行以下限制：

允許的變數數量為 100 個。
每個變數 (包括清單值) 的大小上限為 400 個位元組。

執行資料擷取政策時，系統會在訊息環境中將值新增至資料擷取對應前，執行下列動作：

如果達到變數數量上限，系統會捨棄新變數。
如果變數大小已達上限，系統會將值截斷，以符合所需限制。

無論是哪種情況：

偵錯訊息會記錄到訊息處理工具記錄檔。
limit reached 錯誤訊息會附加至 dataCapturePolicyErrors，Analytics 和 Debug 都會提供這項資訊。注意： 系統只會附加一則錯誤訊息，說明您已達到允許的變數數量上限。
如果 <ThrowExceptionOnLimit> 為 true，系統不會將資料傳送至 Analytics，而是會向用戶端傳回錯誤。

DataCapture 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

資料收集器資源

<DataCapture>

範例

擷取內建變數的資料

內嵌擷取資料

<Capture>

<DataCollector>

<Collect>

<Collect> 的子元素

<Source>

<URIPath>

屬性

<QueryParam>

屬性

<Header>

屬性

<FormParam>

屬性

<JSONPayload>

<JSONPath>

<XMLPayload>

<Namespaces>

<Namespace>

屬性

<XPath>

<ThrowExceptionOnLimit>

錯誤參考資料

執行階段錯誤

部署錯誤

在偵錯工具中找出 DataCapture 錯誤

強制執行擷取限制

相關主題

DataCapture 政策

`<DataCapture>`

`<Collect>` 的子元素

在偵錯工具中找出 `DataCapture` 錯誤