Pendoのデータ同期イベントのエクスポート処理

最終更新日: 2024年09月09日 13:50

Pendoのデータ同期を使用すると、特定のクラウドストレージの宛先にPendoからイベントデータを直接送信できます。そこから、一元化されたデータレイクやウェアハウスにデータを定期的に自動で取り込むことができます。

イベントのエクスポートはアプリケーションレベルで構成され、実行されます。エクスポートは1回限りでも、定期的なものでもかまいません。この記事では、データ同期のフローを理解して実装の準備をすることを目的として、以下の内容を説明します。

前提条件となる手順の概説
エクスポートの流れと頻度の説明
エクスポートに含まれるファイルの階層と目的の明確化
データレイクやウェアハウスへのエクスポートの読み込み方法の詳細

前提条件

データ同期が設定されており、宛先が1つあること。詳細については、以下をご覧ください。
avroファイルソースからテーブルを作成して読み込むための、データウェアハウスの宛先コマンドまたはSDKを使用する能力があること。

イベントのエクスポートを作成する

データ同期をご利用のお客様は、宛先を作成して保存すると、2種類のイベントエクスポートのいずれかを作成できます。

日次の［定期エクスポート（Recurring export）］では、昨日のデータと約9日前の確定データの2日分のデータが送信されます。確定データの処理の詳細については、「確定日数」をご参照ください。
最大3暦年分のデータを送信する履歴データの［単発エクスポート（One-time export）］では、データ同期の実装中に数日分のデータを一度だけエクスポートすることで、データ構造の把握を支援します。

注：Pendoサブスクリプションにデータ同期が含まれていない場合、トライアルとして1日間の［テストエクスポート（Test export）］を作成できます。詳細については、Pendoのデータ同期機能の概要を参照してください。

また、Pendoは必要に応じて遡及的なエクスポートを自動作成します。詳細については、本記事の遡及処理を参照してください。

エクスポートの作成方法

［設定（Settings）］>［データ同期（Data Sync）］に移動し、ページの右上にある［+エクスポートを作成（+ Create export）］を選択します。
開いた画面で以下の操作を行います。
- 適切な名前を入力します。
- イベントの種類として［イベント（Events）］をクリックします。
- エクスポートするアプリケーションを選びます。
- 作成するエクスポートのタイプ（1回限りまたは定期）を選択します。
- 日付範囲を指定します。
［次へ：エクスポート概要（Next: Export Summary）］を選択します。
概要を確認して［エクスポートを作成（Create export）］を選択します。

各エクスポートはサブスクリプション内のアプリケーションごとに固有であり、Pendoのクラウドストレージの宛先として使用される特定のパスに送信されます。たとえば、gs://pendo-data/abcdeというパスを指定すると、Pendoはgs://pendo-data/abcde/datasyncにdatasyncフォルダを作成します。その後、エクスポートはgs://pendo-data/abcde/datasync/<subscription-id>/<application-id>に送信されます。

複数のPendoサブスクリプションが同じ宛先にエクスポートされた場合、それぞれのサブスクリプションIDに分割されてdatasyncフォルダに表示されます。

イベントのエクスポートを表示する

すでに作成したイベントのエクスポートを表示するには、［設定］>［データ同期］に移動します。デフォルトでは、イベントタブが開いています。エクスポートテーブルには、ページ上部のフィルターで指定された日付範囲内のイベントのエクスポート一覧が表示されます。このテーブルには、次の列が含まれています。

名前（Name）：エクスポートに付けたタイトル。
アプリケーション（Application）：イベントのエクスポートに関連付けられているアプリケーション。
ステータス（Status）：エクスポートの進捗状況（進行中、完了、失敗）を示しています。
エクスポートのタイプ（Export type）：1回限り、または定期的なエクスポートかを示しています。
作成日時（Created time）：エクスポートが作成された日時。
作成者（Created by）：エクスポートの作成者。
最終同期成功日時（Last successful sync）：エクスポートが最後に正常に更新された日時。

ページ上部のドロップダウンメニューを使用して、エクスポートテーブルの項目を以下'の方法で絞り込むことができます。

アプリケーション
作成者
ステータス
エクスポートのタイプ
作成日時

特定のエクスポートの概要を表示するには、エクスポートテーブルからエクスポート名を選択します。この操作で、画面右側にパネルが表示されます。表と同じ情報に加え、エクスポートのサイズなどの詳細や、エクスポートが失敗した場合などに役立つメッセージが表示されます。

イベントのエクスポートを読み込む

Pendoのイベントデータをクラウドストレージからデータレイクやウェアハウスに読み込むには、次の情報が必要です。

クラウドストレージ内のdatasyncフォルダへのエクスポートは、アプリケーションごとのフォルダで構成されます。各アプリケーションフォルダには、以下が含まれます。

エクスポートの各部分についてフォルダ内のファイルを参照し、アプリケーションのエクスポート完了後に更新されるエクスポートマニフェスト（ファイル階層内のexportmanifest.json）。エクスポートマニフェストは、過去30日以内に生成されたエクスポートが対象です。
最新のエクスポートの部品表ファイルおよびavroファイル内のイベントデータやビジネスオブジェクトメタデータを含む、一意のハッシュフォルダ（ファイル階層内のexport-uuid）。

ファイル名のみでは内容を十分説明できないため、以下の内容を理解しておくことも重要です。

エクスポートの構造。視覚的な概要と説明については、ファイル階層を参照してください。
エクスポート内のファイルの目的。各エクスポートファイルの説明については、ファイルの説明を参照してください。エクスポートファイルに含まれるデータの詳細については、データ同期スキーマの定義を参照してください。

ファイル階層

以下の図は、エクスポートに含まれるファイル構造の概要を示しています。ファイルに含まれる情報の詳細については、本記事のファイルの説明およびデータ同期スキーマの定義の記事を参照してください。

gs://pendo-data/datasync/<subscription-id>/<application-id>/

├── exportmanifest.json
└── <export-uuid>/
   ├── billofmaterials.json
   ├── allevents.avro
   ├── allfeatures.avro
   ├── allguides.avro
   ├── allpages.avro
   ├── alltracktypes.avro
   └── matchedEvents/
       ├── Feature/
       │   └── <feature_id>.avro
       ├── Page/
       │   └── <page_id>.avro
       └── TrackType/
            └── <track_id>.avro

このファイル構造は、以下の色分けされた画像にもあるように、以下の情報を提供します。

サブスクリプション、アプリケーション、エクスポートの一意の識別子（オレンジ色）
エクスポート内容をJSONファイルに一覧表示するエクスポート管理ファイル（青色）
avroファイル内のイベントデータを含むイベントファイル（緑色）
avroファイル内のビジネスオブジェクトメタデータを含む定義ファイル（ピンク色）

Screenshot 2024-05-07 at 13.41.09.png

一意の識別子

PendoのアグリゲーションAPIからアプリケーションとサブスクリプションに関する詳細情報を取得するには、階層の最上位にあるパスの一意の識別子であるsubscription-idとapplication-idを使用します。

一意のエクスポート識別子に従って名前が付けられるイベントデータのフォルダは、エクスポートマニフェスト（exportmanifest.json）と同じ階層レベルに存在します。

管理ファイルをエクスポートする

エクスポート内容には2つのリストがあります。

日次部品表の連結リストであるエクスポートマニフェスト（exportmanifest.json）。詳細については、本記事のエクスポートマニフェストを参照してください。
エクスポートされたavroイベントファイルをデータウェアハウスまたはデータレイクに読み込むためにETL自動化によって使用されるエクスポート内容のJSON表現である、個々のエクスポート内の日次部品表（billofmaterials.json）。詳細については、本記事の部品表を参照してください。

イベントファイル

イベントデータファイルには2種類あります。

ページルールやフィーチャルールに一致しないイベントまたはすべてのガイドイベントなどの全イベントデータを含むallevents.avroファイル。
matchedEvents/フォルダ内の定義済みのページ、フィーチャー、またはトラックイベントごとの個別のavroファイル。一致するIDは、Pendoアプリケーションからページ、フィーチャー、またはトラックイベントの詳細を表示する際に定義ファイルとURLで使用できる識別子に対応します。

各イベントは、訪問者IDとアカウントIDにも対応しています。

定義ファイル

billofmaterials.jsonおよびallevents.avroと並行して、フィーチャー、ページ、ガイド、トラックイベントのavroファイル内のビジネスオブジェクトメタデータを検索します。これらのファイルを参照することで、matchableIdを使用してイベントの詳細を確認できます。

ファイルの説明

次の表にて、エクスポートに含まれるファイルを説明します。エクスポートファイルに含まれるデータの詳細については、データ同期スキーマの定義を参照してください。

ファイル名は相対的なものです。絶対的なファイル名は、エクスポートマニフェストの［rootUrl］フィールドを相対ファイル名の前に追加することで取得できます。rootUrlは、billofmaterials.jsonファイルのパスにも対応します（ファイル名は除く）。

ファイルサイズの上限は約3GBです。ファイルサイズが3GBを超える場合は、適切に自動分割され、同じ期間IDが追加ファイルで送信されます。

コンテンツタイプ	ファイル名	説明
定義管理ファイル：複数のエクスポートファイルとメタデータの記録	`exportmanifest.json`	日次エクスポートファイルの各部分を連結したリストで、過去30日間以内に生成されたエクスポートのローリングウィンドウを網羅しています。カウンターは、新しいエクスポートを受信するたびに反復処理を行います。ゼロ（0）の場合は何もする必要がなく、コンテンツが削除可能であることを意味します。
エクスポート管理ファイル：エクスポート内容の記録	`billofmaterials.json`	エクスポート内容のJSON表現。これは、エクスポートされたavroイベントファイルをデータウェアハウスで読み込むために、ETLオートメーションで使用されます。
イベントファイル	`allevents.avro`	すべてのイベントデータ。これには、ページ、フィーチャー、またはトラックイベントに関連付けられているPendoのイベントと、関連付けられていないイベントの両方が含まれます。
定義ファイル：イベントに関する追加情報（イベントデータ自体ではありません）	`allfeatures.avro`	アプリケーションからエクスポートされたフィーチャーのリストと、`matchableID`に基づく各フィーチャーの追加メタデータ
	`allguides.avro`	アプリケーションからエクスポートされたガイドのリストと、`matchableID`に基づく各ガイドの追加メタデータ
	`allpages.avro`	アプリケーションからエクスポートされたフィーチャーのリストと、`matchableID`に基づく各ページの追加メタデータ
	`alltracktypes.avro`	アプリケーションからエクスポートされたトラックイベントのリストと、`matchableID`に基づく各トラックイベントの追加メタデータ
イベントファイル：ページ、フィーチャー、トラックイベントで分割されたイベントデータ。定義に一致しないイベントは除外されます。	`<feature_id>.avro`	指定されたフィーチャーIDのすべてのイベント。このフィーチャーIDの値は、フィーチャーの詳細を表示する際にPendoアプリのURLに表示される一意の識別子です。
	`<page_id>.avro`	指定されたページIDのすべてのイベント。このページIDの値は、ページの詳細を表示する際にPendoアプリのURLに表示される一意の識別子です。
	`<track_id>.avro`	指定されたトラックイベントIDのすべてのイベント。このトラックイベントIDの値は、トラックイベントの詳細を表示する際にPendoアプリのURLに表示される一意の識別子です。

BOL

部品表にはエクスポート内容が記録されます。以下のコードスニペットは、データ同期のエクスポートにおけるbillofmaterials.jsonの表示例です。

{
   "timestamp": "2023-02-16T20:21:11Z",
   "numberOfFiles": 65,
   "application": {
     "displayName": "Acme CRM",
     "id": "-323232"
   },
   "subscription": {
     "displayName": "(Demo) Pendo Experience",
     "id": "6591622502678528"
   },
   "pageDefinitionsFile": [
     "allpages.avro"
   ],
   "featureDefinitionsFile": [
     "allfeatures.avro"
   ],
   "trackTypeDefinitionsFile": [
     "alltracktypes.avro"
   ],
   "guideDefinitionsFile": [
     "allguides.avro"
   ],
   "timeDependent": [
     {
       "periodId": "2023-02-22T00:00:00Z"
       "allEvents": {
         "eventCount": 9515,
         "files": [
           "allevents.avro"
         ]
       },
       "matchedEvents": [
         {
           "eventCount": 48314,
           "files": [
             "matchedEvents/Page/OMZ5WpI3HXIhNIIf8Sl_5zJF688.avro"
           ],
           "id": "Page/OMZ5WpI3HXIhNIIf8Sl_5zJF688",
           "type": "Page"
         },
   ]
}

エクスポートマニフェスト

エクスポートマニフェストは、エクスポートを読み取って取り込むための重要なファイルです。エクスポートマニフェストは、複数の部品表と追加のメタデータを連結したものです。エクスポートされる日付データに関係なく、過去30日間のデータ同期アクティビティのローリングレコードで構成されています。

部品表は単一のエクスポートですべての詳細を提供するのに対して、エクスポートマニフェストはより高いレベルで動作し、全エクスポートの状況を長期にわたって追跡できます。これにより、カウンターを反復処理できるようになります。これは、以前のエクスポートファイルが変更される可能性があるエクスポートされたデータの更新において重要です。

以下のコードスニペットは、billofmaterials.jsonと重複する部分を除いたデータ同期エクスポートexportmanifest.jsonの表示例です。

{
  "exports": [
    {
      // complete billofmaterials object present but omitted for brevity
      "exportType": [...],
      "counter": 1,
      "finishTime": "2023-03-03T14:10:15.311651Z",
      "storageSize": 12130815,
      "rootUrl": "gs://pendo-data/datasync/6591622502678528/-323232/0f39bdf6-09c2-4e4d-6d4f-b02c961d8aaf"
    },
    {
      // complete billofmaterials object present but omitted for brevity
      "exportType": [...],
      "counter": 2,
      "finishTime": "2023-03-03T14:20:12.9489274",
      "storageSize": 23462682,
      "rootUrl": "gs://pendo-data/datasync/6591622502678528/-323232/b979502c-1a01-4569-74cf-e4a7f5049d8f"
    }
  ],
  "generatedTime": "2023-03-05T04:17:59.853205005Z"
}

exportTypeは次のいずれかになります。

null エクスポートが1回限りまたは定期的な場合。
["Retroactive"] エクスポートが遡及的な場合。
["Test"]エクスポートがテストエクスポートの場合。これは、1回のテストエクスポートを実行する無料のデータ同期ユーザーのみ使用可能です。

エクスポートマニフェストには、エクスポートとクラウドストレージに完全に読み込まれた後続ファイルのみが反映されます。エクスポートマニフェストに部分的なエクスポートは含まれません。エクスポートマニフェストに一覧表示されるエクスポートは常に完全なエクスポートですが、後に置き換える必要がある未確定のデータを含む可能性があります。

エクスポートされたデータの更新

以前にエクスポートされた日付データがPendoによって自動的に再エクスポートされるのは、確定日数と遡及処理の2つのケースです。この場合も、ディレクトリ構造とスキーマが変わらないため、通常のエクスポートと同じ方法で処理できます。重複する日（期間ID）が誤って取り込まれないようにするには、ETLプロセスに適切な「ドロップアンドリプレース」ロジックが含まれていることを確認してください。

確定日数

Pendoのイベントデータは、約9日後に確定されます（確定までの正確な日数は、お住まいの地域のタイムゾーンによって異なります）。

データが確定するまでの間、Pendoによる追加データの収集が実施されるため、小さな更新が発生する可能性があります。たとえば、ユーザーがブラウザウィンドウを開いたままにしていると、その日のセッション情報は翌日まで取得されません。これらの変更はPendoアプリケーションでシームレスに処理されます。変更量がごくわずかであっても、データ同期機能により自動エクスポートで変更に対応します。これにより、データウェアハウス内のPendoデータと、Pendoアプリケーション内のPendoデータの整合性が長期にわたって維持されます。

データ同期エクスポートに変更を反映するために、日次の定期エクスポートには以下の2つの固有のエクスポートが含まれます。

未確定の昨日のデータ
8～10日前の確定データ

以下はその例です。

エクスポート日	昨日のデータ	確定データ
2024年4月15日	2024年4月14日	2024年4月7日より、2024年4月8日に受け取る未確定エクスポートに代わるもの

昨日のエクスポートと確定エクスポート間で、以下のようなデータの変更が発生する可能性があります。

昨日のデータには表示されなかったイベントが確定データに表示される。
昨日のデータに表示されたイベントが確定データに表示される。
未確定データ内のallevents.avroにのみ存在するイベントがmatchedEventsの確定データに表示される。

特定のイベント用のBrowserTimeStampは、未確定データと確定データ間で変化しません。データ同期のタイムスタンプの詳細については、この記事の「タイムスタンプとタイムゾーン」をご参照ください。

遡及処理

フィーチャーやページのルールが追加または更新されると、Pendoがインストールされて以降の有効期間内のデータに対し、新規または更新されたタグが適用されます。

以前にエクスポートしたデータを最新の状態に保つために、ルールが追加または変更されるたびに、1日に1回遡及的なエクスポートを実施します。これにより、関連するページとフィーチャーについて、過去のエクスポート期間のデータが再エクスポートされます。このエクスポートのスキーマは通常のエクスポートと同じですが、再処理されたフィーチャーまたはページのイベントデータのみを再エクスポートするため、遡及的なエクスポートにはallevents.avroファイルは含まれません。allpages.avroなどのフィーチャーやページの定義ファイルが含まれます。

すでにウェアハウスに読み込まれている期間のデータを受け取った場合は、新しいデータを読み込む前に、期間IDに対応するイベントデータを完全に削除する必要があります。これにより、重複するデータが取り込まれなくなります。確定データと遡及的なエクスポートの両方に同じロジックが適用されます。唯一の違いは、遡及的なエクスポートでは変更に関連するデータのみの小さなサブセットが提供される点です。詳細については、ステップ3. 時間依存イベントを反復処理するを参照してください。

エクスポートされたデータの検証

データ同期はPendoのすべてのデータを渡しますが、Pendoで見るデータとデータ同期用のavroファイルのデータには違いがあります。これらの違いは通常、タイムスタンプと除外リストによって発生します。エクスポートされたデータ同期のデータをPendoのデータと比較する前に：

Pendoアプリケーションとデータ同期エクスポート間でタイムスタンプが揃っていることを確認します。
Pendoの除外リストで除外されているデータを考慮に入れてください。

タイムスタンプとタイムゾーン

periodIdやbrowserTimestamp など、データ同期のavroファイルのすべてのタイムスタンプは、協定世界時（UTC）に基づいています。Pendoアプリケーション内のすべてのデータは、サブスクリプションのローカルタイムゾーンを使用して計算されます。つまり、Pendoのデータとデータ同期から抽出したデータを比較したい場合は、UTCとローカルタイムゾーンの間で適切なコンバージョンを行う必要があります。

エクスポートされたデータ同期のデータをPendoのデータと比較する前に、時間のコンバージョンを実行します。データ同期のエクスポートとPendoで表示されるデータを一致させるには、データレイクやウェアハウスのイベントにlocalTimestampフィールドを作成します。これは、クラウドストレージからデータを取得するのと同じETLスクリプトを使用するか、データがデータレイクまたはウェアハウスに読み込まれた後に実行できます。時間を加算または減算してコンバージョンを実行し、データ同期からの UTCイベントをローカルタイムゾーンに合わせます。

除外リスト

Pendoでは除外リストを使用して、特定のドメイン、訪問者、アカウント、IPアドレスによって生成されたイベントがPendoアナリティクスに表示されないようにすることができます。データ同期のエクスポートには、除外リストによってPendoアプリケーションの分析から除外されたものを含むすべてのイベントが含まれます。つまり、データ同期のエクスポートに表示されるイベントの数とPendoアプリケーションに表示されるイベントの数に不一致が生じる可能性があります。

データ同期のエクスポートで、Pendoのイベント数から予想されるよりも多くのイベントがある場合は、左側のメニューから［設定（Settings）］>［リストを含めるまたは除外する（Include & Exclude Lists）］に移動して、除外リストを確認してください。

読み込みの流れの例

この例では、イベントタイプファイルごとにデータウェアハウスに別々のテーブルを作成します。データが正しく置き換えられている限り、必要に応じてデータを読み込むことができます。

ステップ1. 最新のエクスポートマニフェストを読む

最新のexportmanifest.jsonファイルを読んで、最後にデータを読み込んで以降まだ処理されていないエクスポートデータをすべて見つけます。この際、カウンタフィールドを読み込み用のマーカーとして使用できます。

ステップ 2. エクスポートリストの各エントリを反復処理する

リスト内のエントリを循環処理し、テーブルに書き込みます。

Pendoのイベントタイプ説明ファイルの最新バージョンは、エクスポートごとに送信されます。このようなファイルをデータウェアハウスに書き込むときは、以前のイベントタイプの説明ファイルを各エクスポートデータに置き換え、論理的なavroタイプマッピングを使用する必要があります。

allpagesを読み込みます。

allpagesテーブルが存在しない場合は、作成します。allpagesテーブルが存在する場合は、すべてのデータを削除します。次に、 pageDefinitionsFileフィールドが指すリストのすべてのavroファイルをallpagesテーブルに書き込みます。
allfeaturesを読み込みます。

allfeaturesテーブルが存在しない場合は、作成します。allfeaturesテーブルが存在する場合は、すべてのデータを削除します。次に、 featureDefinitionsFileフィールドが指すリストのすべてのavroファイルをallfeaturesテーブルに書き込みます。
alltracktypesを読み込みます。

alltracktypesテーブルが存在しない場合は、作成します。alltracktypesテーブルが存在する場合は、すべてのデータを削除します。次に、 trackTypeDefinitionsFileフィールドが指すリストのすべてのavroファイルをalltracktypesテーブルに書き込みます。
allguidesを読み込みます。

allguidesテーブルが存在しない場合は、作成します。allguidesテーブルが存在する場合は、すべてのデータを削除します。次に、guideDefinitionsFileフィールドが指すリストのすべてのavroファイルをallguidesテーブルに書き込みます。

ステップ3. 時間依存イベントを反復処理する

部品表内のtimeDependentブロックには、特定のperiodId値に関連付けられたデータが含まれています。periodIDは、特定のイベントが存在する論理的期間を示します。この期間はイベントデータの日と同じであるため、同じイベントが2つの異なる期間に発生することはありません。データ同期のタイムスタンプの詳細については、この記事の「タイムスタンプとタイムゾーン」をご参照ください。

timeDependentリスト内のすべての項目を反復処理します。次に、allevents.avroを論理型マッピングで読み込みます。alleventsテーブルが存在しない場合は、作成します。alleventsテーブルが存在する場合は、指定されたperiodIDのイベントデータをテーブルから削除し、allevents.avroファイルのデータをalleventsテーブルに追加します。これは重複を避けるためです。

次に、matchedEventsリスト内のすべての項目を反復処理します。さらにidフィールドで指定されたイベントタイプごとにイベントを読み込みます。イベントタイプのテーブルが存在しない場合は、作成します。イベントタイプのテーブルが存在する場合は、指定されたperiodIDのイベントデータをテーブルから削除し、filesフィールドのすべてのavroファイルのデータをイベントタイプのテーブルに追加します。