DataCapture ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

DataCapture ポリシーは、アナリティクスで使用するために、API プロキシからデータ（ペイロード、HTTP ヘッダー、パスやクエリ パラメータなど）をキャプチャします。キャプチャしたデータをカスタム アナリティクス レポートで使用するだけでなく、収益化とモニタリングのルールを実装することもできます。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

データコレクタ リソース

DataCapture ポリシーを使用するには、まずデータコレクタ REST リソースを作成する必要があります。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> 要素です。この要素は、データをキャプチャする方法を指定します。次の 2 つの必須の子要素があります。

• データコレクタ REST リソースを指定する <DataCollector> 要素。 この場合、リソース名は dc_data_collector になります。
• データをキャプチャするための手段を指定する<Collect> 要素。

この例では、別のプロキシで作成された my_data_variable という変数からデータが抽出されています。この変数は 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>

この要素には、すべてのポリシーに共通する次の属性があります。

次の表は、<DataCapture> の子要素の概要をまとめたものです。

例

次の例は、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 だとします。アナリティクスに送信されるエントリは次のようになります

{
    "dc_data_collector": "1120"
}

<Capture>

<Capture> 要素は、データを取得する方法を指定します。

<Capture />

次の表は、<Capture> の子要素の概要をまとめたものです。

<DataCollector>

<DataCollector> 要素には、データコレクタ リソースを指定します。

<DataCollector>dc_data_collector</DataCollector>

<DataCollector> 要素の本文には、データコレクタ リソース名が含まれます。

<Collect>

<Collect> 要素は、データを取得する手段を指定します。

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

次の表は、<Collect> 要素の属性を示したものです。

データは、ref 属性または<Collect> 子要素を使用して、既存の変数からキャプチャできます。

<Collect> の子要素

次の表は、<Collect> の子要素の概要をまとめたものです。

<Source>

解析するメッセージの名前を指定する変数を指定します。<Source> の値がデフォルトの message に設定されます。message 値はコンテキストに依存します。リクエスト フローで、message がリクエスト メッセージに解決されます。レスポンス フローの中では、message はレスポンス メッセージになります。

<Source> で指定された変数を解決できない場合、またはメッセージ以外のタイプに解決される場合、ポリシーはレスポンスを返しません。

<Source >request</Source>

<URIPath>

request ソース メッセージの proxy.pathsuffix から値を抽出します。パターンに適用されるパスは proxy.pathsuffix で、API プロキシのベースパスは含まれません。ソース メッセージが response であるメッセージ タイプに解決された場合、要素は何もしません。

属性

<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>
    <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>
    <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>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

変数の値を抽出する JSON 形式のメッセージを指定します。JSON 抽出は、メッセージの Content-Type ヘッダーが application/json の場合にのみ実行されます。

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

<JSONPath>

<JSONPayload> 要素の必須の子要素。JSON 形式のメッセージから値を抽出するために使用される、JSON パスを指定します。

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

<XMLPayload>

変数の値を抽出する XML 形式のメッセージを指定します。XML ペイロードは、メッセージの Content-Type ヘッダーがtext/xml、application/xml、または application/*+xml の場合にのみ抽出されます。

次の表は、<XMLPayload> の子要素の概要をまとめたものです。

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

<Namespace>

XPath 式で使用する名前空間と対応する接頭辞を 1 つずつ指定します。例

属性

<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 式のみがサポートされています。

   <XPath>/test/example</XPath>

注: XPath 式で名前空間を使用する場合、ポリシーの <XMLPayload><Namespaces> セクションで名前空間を宣言する必要があります。

<ThrowExceptionOnLimit>

<ThrowExceptionOnLimit> 要素は、変数のキャプチャ上限または変数の最大サイズに達した場合の動作を指定します。キャプチャ上限の適用をご覧ください。

<ThrowExceptionOnLimit> の値は、次のいずれかです。

• false: 変数のデータはアナリティクスに送信されます。
• true: エラー メッセージが返されます。データはアナリティクスに送信されません。

エラー リファレンス

ランタイム エラー

次の表では、ポリシーの実行時に発生する可能性のあるランタイム エラーについて説明します。

ランタイム エラーは次の 2 つの方法で返されます。

• クライアントへのエラー レスポンス（continueOnError=false）

  ポリシーの continueOnError 属性が false に設定されている場合、ポリシー実行中に発生したエラーはメッセージ処理を中止し、わかりやすいエラー メッセージを返します。ポリシーを使用して、メッセージを返す前にデータ キャプチャ ポリシーに関連するすべてのエラーをキャプチャしようとします。

• DataCapture エラー分析項目

  dataCapturePolicyErrors フィールドには、発生したすべてのエラーの一覧が含まれています。分析データマップでの表示例を次に示します。

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

このフィールドには、400 バイトの変数サイズの上限が適用されます。

デプロイエラー

デバッグツールで DataCaptureDataCapture エラーを検出する

dataCapturePolicyErrors 変数はデバッグツールで使用できます。これは、アナリティクスにアクセスせずにエラーを検出するためのツールです。たとえば、ハイブリッド ランタイムのバージョンをアップグレードし、すでにデプロイされているプロキシで分析が意図せず中断すると、発生するエラーを検出できます。

キャプチャ上限の適用

Apigee では、キャプチャされたデータの変数に次の上限が適用されます。

• 変数の数は 最大で100 です。
• 各変数（リスト値を含む）の最大サイズは 400 バイトです。

データ キャプチャ ポリシーが実行された場合は、メッセージ コンテキストのデータ キャプチャ マップに値が追加される前に、次の処理が行われます。

• 変数の数が上限に達すると、新しい変数は破棄されます。
• 変数のサイズの上限に達すると、値は該当する上限に合わせてカットされます。

どちらの場合も、次のようになります。

• デバッグ メッセージが Message Processor のログに記録されます。
• limit reached エラー メッセージが dataCapturePolicyErrors に追加されます。これは、アナリティクスとデバッグの両方で利用できます。注: 許容される変数の最大数に達した場合、エラー メッセージが 1 つのみ追加されます。
• <ThrowExceptionOnLimit> が true の場合、データはアナリティクスに送信されず、クライアントにエラーが返されます。

関連トピック

• ExtractVariables ポリシー