DataCapture 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

DataCapture 圖示

總覽

DataCapture 政策會從 API 代理程擷取資料 (例如酬載、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> 元素，可用於指定擷取資料的方式。這個元素有兩個必要的子元素：

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

<Collect> 元素也透過其子元素，提供多種擷取來自不同來源的資料的方式。如要瞭解更多使用 DataCapture 政策擷取資料的範例，請參閱「範例」。

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>

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

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

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

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError false 選用 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
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> 元素，可指定資料收集器資源的名稱。

在文字中擷取資料

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

<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> 的子元素：

子元素 是否必要 說明
<Source> 選用 指定要剖析的變數。
<URIPath> 選用 從要求來源訊息的 proxy.pathsuffix 擷取值。
<QueryParam> 選用 從要求來源訊息的指定查詢參數中擷取值。
<Header> 選用 從指定要求或回應訊息的指定 HTTP 標頭中擷取值。
<FormParam> 選用 從指定要求或回應訊息的指定表單參數中擷取值。
<JSONPayload> 選用 指定要從中擷取變數值的 JSON 格式訊息。
<XMLPayload> 選用 指定要從中擷取變數值的 XML 格式訊息。

<Source>

指定要剖析的訊息名稱變數。<Source> 的值預設為 message。message 值會依據情境而有所不同。在要求流程中，message 會解析為要求訊息。在回應流程中，message 會解析為回應訊息。

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

預設值 不適用
是否必要？ 選用
類型 字串
上層元素 <Collect>
子元素 N/A 
<Source >request</Source>

<URIPath>

從 request 來源訊息的 proxy.pathsuffix 擷取值。套用至模式的路徑是 proxy.pathsuffix，其中不包含 API 代理程式的 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>

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

<FormParam>

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

預設值 不適用
是否必要？ 選用
類型 複合式園區
上層元素 <Collect>
子元素 <Pattern>

屬性

屬性 說明 預設 是否必要 類型
名稱 您要從中擷取值的資料表單參數名稱。

不適用

 選用 字串 
<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

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

預設值 不適用
是否必要？ 選用
類型 複合式園區
上層元素 <Collect>
子元素 <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

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

預設值 不適用
是否必要？ 必填
類型 字串
上層元素 <JSONPayload>
子元素 N/A 
<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>

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

<命名空間>

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

預設值 不適用
是否必要？ 選用
類型 字串
上層元素 <Namespaces>
子元素 N/A

屬性

屬性 說明 預設 是否必要 類型
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>
子元素 N/A 
   <XPath>/test/example</XPath>

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

<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 欄位會列出所有發生的錯誤。以下範例說明這項資訊會如何顯示在數據分析資料地圖中：

    # 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 錯誤

您可以在「Debug」工具中使用 dataCapturePolicyErrors 變數。這是另一個工具，可用來擷取錯誤，而無須前往 Analytics。舉例來說，如果您升級混合式執行階段版本，並在已部署的 Proxy 中不小心中斷 Analytics，您可以擷取發生的錯誤。

強制執行擷取限制

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

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

執行資料擷取政策時，在訊息內容中將值新增至資料擷取對應項目之前：

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

無論是哪種情況，請注意：

  • 系統會將偵錯訊息記錄到訊息處理工具記錄檔。
  • limit reached 錯誤訊息會附加至 dataCapturePolicyErrors，這兩者都會在 Analytics 和 Debug 中顯示。注意： 系統只會附加一則錯誤訊息，指出已達到允許的變數數量上限。
  • 如果 <ThrowExceptionOnLimit> 為 true，系統就不會將資料傳送至 Analytics，而是傳回錯誤給用戶端。

相關主題