DataCapture ポリシー

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

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

DataCapture アイコン

概要

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 つの必須の子要素があります。

この例では、別のプロキシで作成された 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>

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

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、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 だとします。この場合、アナリティクスに送信されるエントリは次のようになります。

{
    "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 のいずれかを指定する必要があります。 文字列
デフォルト 変数の値が実行時に挿入されない場合にアナリティクスに送信される値を指定します。たとえば、default="0" を設定すると、アナリティクスに送信される値は 0 になります。 default の値や変数の値を指定しない場合、実行時に挿入されません。アナリティクスに送信された値は、数値変数の 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>
子要素 なし 
<Source >request</Source>

<URIPath>

request ソース メッセージの proxy.pathsuffix から値を抽出します。パターンに適用されるパスは proxy.pathsuffix で、API プロキシのベースパスは含まれません。ソース メッセージが 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>

属性

属性 説明 デフォルト 必須かどうか 型
name クエリ パラメータの名前を指定します。複数のクエリ パラメータの名前が同じ場合、インデックス付きの参照を使用し、クエリ パラメータの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 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>

属性

属性 説明 デフォルト 必須かどうか 型
name 値を抽出するヘッダーの名前を指定します。複数のヘッダーの名前が同じ場合、インデックス付きの参照を使用し、ヘッダーの最初のインスタンスはインデックスなし、2 番目は 2、3 番目は 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>

属性

属性 説明 デフォルト 必須かどうか 型
name 値を抽出するフォーム パラメータの名前。

なし

 省略可 文字列 
<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

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

デフォルト値 なし
必須かどうか 省略可
型 複合型
親要素 <Collect>
子要素 <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

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

デフォルト値 なし
必須かどうか 必須
型 文字列
親要素 <JSONPayload>
子要素 なし 
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

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

デフォルト値 なし
必須かどうか 省略可
型 複合型
親要素 <Collect>
子要素 <Namespaces>
<XPath>

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

子要素 必須かどうか 説明
<Namespaces> 省略可 XPath 評価で使用する 0 個以上の名前空間を指定します。
<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>

<Namespace>

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

デフォルト値 なし
必須かどうか 省略可
型 文字列
親要素 <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>/test/example</XPath>

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

<ThrowExceptionOnLimit>

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

<ThrowExceptionOnLimit> の値は次のいずれかになります。

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

エラー リファレンス

ランタイム エラー

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

障害コード 原因
DataCollectorTypeMismatch

取得する値が DataCollector のタイプと一致しませんでした。
ExtractionFailure データを抽出できません。
UnresolvedVariable 変数が存在しません。
VariableCountLimitExceeded 取得された変数の数が変数数の上限の 100 を超えています
VariableValueLimitExceeded 取得された値のサイズが 1 つの変数の上限（400 バイト）を超えています。
MsgContentParsingFailed メッセージの内容を XML または JSON に解析できませんでした。
InvalidMsgContentType メッセージ コンテンツ タイプが、ポリシー キャプチャ句内の想定されるメッセージ コンテンツ タイプと一致しません。
NonMsgVariable <Source> 要素の値がメッセージ変数を参照していません。
JSONPathQueryFailed JSONPath クエリが値を解決できませんでした。
PrivateVariableAccess 限定公開変数にアクセスできませんでした。
XPathEvaluationFailed XPath は値を解決できませんでした。

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

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

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

  • DataCapture エラー分析フィールド

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

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

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

デプロイエラー

障害コード 原因
DeploymentAssertionError ポリシーで参照されている Data Collector が、デプロイ時に組織内で見つかりませんでした。
JsonPathCompilationFailed 指定された JSONPath のコンパイルに失敗しました。
XPathCompilationFailed XPath 要素で使用される接頭辞や値がポリシーで宣言された名前空間の一部でない場合、API プロキシのデプロイが失敗します。
PatternCompilationFailed パターンのコンパイルに失敗しました。

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

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

キャプチャ上限の適用

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

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

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

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

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

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

関連トピック