1. Pendoヘルプセンター
  2. インテグレーション
  3. Pendoデータ同期

データ同期のエクスポート処理

最終更新日:

データ同期が設定されると、指定したクラウドストレージにPendoのデータがエクスポートされます。この記事では、そのエクスポートデータをお使いのデータウェアハウスで読み込む方法について説明します。

Google Cloud StorageからGoogle BigQueryへのデータ同期エクスポートの処理を示すサンプルコードについては、data-sync-gcp-export-loading-exampleを参照してください。

前提条件

読み込みについて

Pendoのデータ同期が設定されると、エクスポートデータが、指定されたクラウドストレージバケットパスに1日に1回配信されます。そのためには、クラウドストレージバケットとそのバケットにアクセスできるサービスアカウントの作成、およびそのバケットにデータを書き込むために必要な権限をPendoに与える秘密キーが必要です。

作成したバケットパスは、［設定（Settings）］>［データ管理（Data Management）］>［一括エクスポート（Bulk Exports）］>［バケットアドレス（Bucket Address）］の下の［宛先（Destinations）］にある［宛先（Destinations）］テーブルで確認できます。

上記のプロセスに従って宛先を保存したら、エクスポートを作成します。毎日のエクスポートデータは、Pendoのクラウドストレージの場所として使用されていたパスに送信されます。たとえば、gs://pendo-dataというパスが使用されていた場合、毎日のエクスポートデータはgs://pendo-data/datasync/<subscription-id>/<application-id>/に送信されます。

Pendoでは、データをエクスポートするアプリケーションごとに、クラウドストレージのdatasyncフォルダにフォルダを作成します。各アプリケーションフォルダには、そのアプリケーションのエクスポートが完了した後に更新されるエクスポートマニフェストと、エクスポートごとに作成されるそのエクスポートに固有のハッシュフォルダがあります。ハッシュフォルダには、その最新のエクスポートに関するすべてのavroファイルとBOMファイルが格納されます。これらのファイルの詳細については、 Pendoのデータ同期のスキーマ定義を参照してください。

このディレクトリには、次のファイルとディレクトリが含まれます。各テーブルは、Pendoからエクスポートした各avroファイルに対応します。

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

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

以前にエクスポートした数日間のデータを再エクスポートしなければならないことがあります。この場合も、ディレクトリ構造とスキーマが変わらないため、通常のエクスポートと同じ方法で処理できます。

遡及処理

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

以前にエクスポートされたデータをPendo UIでの再処理で最新の状態に保つため、Pendoでは、ルールが追加または変更されるたびに遡及エクスポートを開始します。この場合、既存の履歴または定期エクスポートでエクスポートされた日数分のデータが再エクスポートされます。このエクスポートの内容は、次の例外を除き、通常のエクスポートと同じです。

  • 再処理されたフィーチャーまたはページのイベントデータのみを再エクスポートするため、訴求エクスポートには、allevents.avroファイルはありません。

  • 履歴または定期エクスポートでエクスポートされた日数分、再処理されたフィーチャーやページのイベントデータを再エクスポートします。

未完了の日数

Pendoイベントデータは8日後に確定します。それまではPendoによる追加データの収集が実施されるため、集計データに小さな変更が発生する可能性があります。たとえば、ユーザーがブラウザウィンドウを開いたままにしていると、その日のセッション情報は翌日まで取得されません。これらの変更はPendo UIでシームレスに処理されます。

これらの変更をデータ同期機能のエクスポートデータに反映するため、Pendoでは、確定データ（8日後のデータ）と未確定データ（前日のデータ）の2回の日次エクスポートを実施します。たとえば、日次エクスポートでは、gs://pendo-data/datasync/<subscription-id>/<application-id>/に対して、一意にハッシュ化された2つのフォルダで2回のエクスポートを実施します。1つには8日前以降のデータが、もう1つには前日以降のデータが含まれます。つまり、当日のデータの確定バージョンがエクスポートされるのは8日後になります。

2023年7月14日より前は、確定データのみがエクスポートされていました。この日付より前に定期的なエクスポートを有効にしていた場合、2023年7月14日以降は、日付ごとではなく、確定データと未確定データの2つのエクスポートが実施されます。未確定データは、この日付より前の7日間はエクスポートされません。その期間のデータについては、2023年7月14日から7日後に確定データが送信されます。

ファイルの説明

詳細については、 Pendoのデータ同期のスキーマ定義を参照してください。

ファイル名 説明
exportmanifest.json 日次エクスポートbillofmaterials.jsonの連結リスト。
billofmaterials.json エクスポート内容のJSON表現。これは、エクスポートされたavroイベントファイルをデータウェアハウスで読み込むために、ETLオートメーションで使用されます。
allevents.avro すべてのイベントデータ。これには、ページ、フィーチャー、またはトラックイベントに関連付けられているPendoのイベントと、関連付けられていないイベントの両方が含まれます。
allfeatures.avro そのアプリケーションのエクスポートされたフィーチャーの説明。
allguides.avro そのアプリケーションのエクスポートされたガイドの説明。
allpages.avro そのアプリケーションのエクスポートされたページの説明。
alltracktypes.avro そのアプリケーションのエクスポートされたトラックイベントの説明。
<feature_id>.avro

指定されたフィーチャーIDのすべてのイベント。このフィーチャーIDの値は一意の識別子で、Pendo UIで見つけられます。
<page_id>.avro

指定されたページIDのすべてのイベント。このページIDの値は一意の識別子で、Pendo UIで見つけられます。
<track_id>.avro

指定されたトラックイベントIDのすべてのイベント。このトラックイベントIDの値は一意の識別子で、Pendo UIで見つけられます。

 

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

BOL

BOLには、エクスポートの内容が文書化されています。以下は、データ同期のエクスポートでbillofmaterial.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": 1675728000,
       "allEvents": {
         "eventCount": 9515,
         "files": [
           "allevents.avro"
         ]
       },
       "matchedEvents": [
         {
           "eventCount": 48314,
           "files": [
             "matchedEvents/Page/OMZ5WpI3HXIhNIIf8Sl_5zJF688.avro"
           ],
           "id": "Page/OMZ5WpI3HXIhNIIf8Sl_5zJF688",
           "type": "Page"
         },
   ]
}

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

エクスポートマニフェストは、複数のBOLと追加のメタデータを連結したものです。以下は、データ同期のエクスポートでエクスポートマニフェストがどのように表示されるかを示す例になります。

{
  "exports": [
    {
      ...,
      "counter": 1,
      "finishTime": "2023-03-03T14:10:15.311651Z",
      "storageSize": 12130815,
      "rootUrl": "gs://pendo-data/datasync/6591622502678528/-323232/0f39bdf6-09c2-4e4d-6d4f-b02c961d8aaf"
    },
    {
      ...,
      "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"
}

読み込みの流れの例

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

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

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

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

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

  1. allpagesを読み込みます。

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

  2. allfeaturesを読み込みます。

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

  3. alltracktypesを読み込みます。

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

  4. allguidesを読み込みます。

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

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

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

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

データファイルをデータウェアハウスに書き込む

結果となるavroファイルをデータウェアハウスに書き込むときは、以前のイベントタイプの説明ファイルを各エクスポートデータに置き換え、論理的なavroタイプマッピングを使用する必要があります。

イベントタイプの説明を読み込む

Pendoのイベントタイプ説明ファイルの最新バージョンは、エクスポートごとに送信されます。データ同期の各エクスポートを読み込む際は、このデータを置き換える必要があります。読み込み対象となるファイルのリストについては、次のフィールドを参照してください。

  • pageDefinitionsFile
  • featureDefinitionsFile
  • trackTypeDefinitionsFile
  • guideDefinitionsFile

avroファイルがリストとして表示されている場合、そのリストは空である可能性があります。これは、その期間のデータが削除されていることを示すものであるからです。こうした状況は、次のような場合に発生する可能性があります。

  • ページが以前にタグ付けされており、期間内にゼロ以外の数のイベントと一致したとき。
  • ページの一致ルールが更新されたとき。
  • Pendoがその期間のイベントを再処理し、新しいルールがどのイベントとも一致しないとき。

時間依存イベントを読み込む

BOMのtimeDependentブロックには、特定のperiodIdの値に関連付けられたデータが含まれています。periodIdは、特定のイベントが存在する論理的期間を示します。この期間は、イベントデータの日と同じであるため、2つの異なる期間に同じイベントが見つかることはありません。

論理avroタイプマッピングを使用するためのデータウェアハウスのオプションと一緒に、avroイベントファイルを読み込みます。これで、browserTimestampの値はTIMESTAMPとして読み込まれ、periodIdはDATEデータ型として読み込まれます。

timeDependentブロックのavroファイルを読み込むには、まずイベントタイプ（ページ、フィーチャー、トラックなど）およびperiodIdに対応するデータを削除し、そのうえで新しいデータを読み込む必要があります。

Pendoでは、特定の<event type>/<periodId>に更新内容を送信できます。データを置換していない場合は、データウェアハウスに重複データの蓄積を開始できます。イベントタイプのルール定義を更新した場合、イベントデータが再送信される可能性があります。

          1.  
この記事は役に立ちましたか？
1人中0人がこの記事が役に立ったと言っています

このセクションの記事