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

最終更新日:

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

この記事では、データ同期のフローを理解して実装の準備をすることを目的として、以下の内容を説明します。

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

前提条件

セットアップ

概して、データ同期の設定には以下のタスクが含まれます。

  1. 宛先を作成して管理する
  2. エクスポートを作成する

宛先を作成して管理する

データ同期を設定する際は、クラウドストレージの宛先を設定し、Pendoで定義を行います。正確なプロセスと前提条件は、選択した宛先によって異なります。

宛先を設定した後、[データ同期(Data Sync)]ページから[宛先を管理(Manage destination)]を選択してバケットパスを検索し、必要に応じて更新できます。

Settings_DataSync_ManageDestination.png

エクスポートを作成する

データ同期を利用するお客様は、宛先を作成して管理するで概説したプロセスに従って宛先を保存した後、2種類のエクスポートのいずれかを作成できます。

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

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

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

エクスポートの作成方法

  1. [設定(Settings)]>[データ同期(Data Sync)]に移動し、ページの右上にある[+エクスポートを作成(+ Create export)]を選択します。

    DS_CreateExport.png

  2. 開いた画面でわかりやすい名前を入力し、エクスポートするアプリケーションを選択し、作成するエクスポートの種類を選択してから日付範囲を選択します。

    Create Export Step 1.png

  3. [次へ:エクスポート概要(Next: Export Summary)]を選択します。
  4. 概要を確認して[エクスポートを作成(Create export)]を選択します。

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

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

エクスポート

クラウドストレージ内の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

 

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

Screenshot 2024-05-07 at 13.41.09.png

一意の識別子

PendoのアグリゲーションAPIからアプリケーションとサブスクリプションに関する詳細情報を取得するには、階層の最上位にあるパスの一意の識別子であるsubscription-idapplication-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. 時間依存イベントを反復処理するを参照してください。

読み込みの流れの例

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

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

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

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

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

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

  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ブロックには、特定のperiodId値に関連付けられたデータが含まれています。periodIDは、特定のイベントが存在する論理的期間を示します。この期間はイベントデータの日と同じであるため、同じイベントが2つの異なる期間に発生することはありません。

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

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

 

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