データ同期アカウントと訪問者のエクスポート処理

最終更新日: 2025年01月07日 09:45

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

アカウントと訪問者のエクスポートは、イベントとは異なる独立したデータ型で、サブスクリプションレベルで適用されます。アカウント、訪問者、またはその両方をエクスポートできます。アカウントと訪問者のエクスポートは、Pendoのデータ同期で設定する保存先のサブフォルダに配信されます。1回限りのエクスポートを作成するか、継続的なメタデータ更新を作成するかを選択できます。メタデータ更新では、過去24時間以内にメタデータが更新されたアカウントまたは訪問者に対してすべてのメタデータを最初にエクスポートし、続いて毎日エクスポートします。

この記事は、Pendoのデータ同期でのアカウントと訪問者のエクスポートのフローを理解し、実装の準備に役立つように説明しています。特にこの記事では以下について説明します。

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

前提条件

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

アカウントと訪問者のエクスポートの作成

送信先を設定後に、Pendoのデータ同期をご利用のお客様は、アカウントと訪問者の2種類のエクスポートのうちいずれかを作成できます。

1回限りの履歴エクスポートでは、エクスポート時にサブスクリプション内のすべてのアカウントまたは訪問者がエクスポートされます。
継続的なメタデータ更新エクスポートでは、過去24時間に更新されたサブスクリプション内のすべてのアカウントまたは訪問者がエクスポートされます。このエクスポートは毎日実行され、過去24時間に更新されたメタデータがエクスポートされます。

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

エクスポートの作成方法

［設定（Settings）］>［データ同期（Data Sync）］に移動し、ページの右上にある［+エクスポートを作成（+ Create export）］を選択します。
開いた画面で以下の操作を行います。
- 適切な名前を入力します。
- データ型として［アカウントと訪問者（Accounts and visitors）］を選択します。
- データレベルとして［アカウント（Accounts）］または［訪問者（Visitors）］を選択します。
- エクスポートの種類として、［1回限り（One-time）］または［継続的なメタデータ更新（Ongoing metadata updates）］を選択します。
［次へ：エクスポート概要（Next: Export Summary）］を選択します。
概要を確認して［エクスポートを作成（Create export）］を選択します。

各エクスポートは、宛先構成で指定されたバケットURLとパスに配信されます。たとえば、gs://pendo-data/abcdeというパスを指定すると、Pendoはgs://pendo-data/abcde/datasyncにdatasync フォルダを作成します。エクスポートは、エクスポートされたエンティティのデータレベルにちなんだ名前のサブフォルダに配信されます。この例では、各アカウントのエクスポートはgs://pendo-data/abcde/datasync/<subscription-id>/accounts下のサブフォルダに追加され、各訪問者のエクスポートはs://pendo-data/abcde/datasync/<subscription-id>/visitors下のサブフォルダに追加されます。

アカウントと訪問者のエクスポートの表示

すでに作成した訪問者とアカウントのエクスポートを表示するには、［設定（Settings）］>［データ同期（Data Sync）］に移動し、［アカウントと訪問者（Accounts and visitors）］タブを開きます。エクスポートテーブルには、ページ上部のフィルターで指定された日付範囲内のエクスポート一覧が表示されます。このテーブルには、次の列が含まれています。

名前（Name）：エクスポートに付けたタイトル。
データ型（Data type）：エクスポートにアカウントレベル、訪問者レベル、またはその両方のメタデータが含まれるかどうか。
ステータス（Status）：エクスポートの進捗状況（進行中、完了、失敗）を示しています。
エクスポートの種類（Export type）：1回限りのエクスポートまたは継続的なエクスポート。
作成日時（Create time）：エクスポートが作成された日時。
作成者（Created by）：エクスポートの作成者。
最終同期成功日時（Last successful sync）：エクスポートが最後に正常に更新された日時。

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

日付範囲
データレベル
作成者
ステータス
エクスポートの種類

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

アカウントと訪問者のエクスポートの読み込み

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

アカウントと訪問者のメタデータはサブスクリプションレベルのデータのため、Pendoはサブスクリプションフォルダ内にアカウント用と訪問者用のフォルダを別々に作成します。これらのサブスクリプションレベルのサブフォルダ（1つはアカウント用、もう1つは訪問者用）には、次のものがあります。

エクスポートマニフェスト（exportmanifest.json）。エクスポートの完了後に更新されます。
一意のハッシュフォルダ（export-uuid）は、そのエクスポートの部品表ファイルとエクスポートされたデータを含むavroファイルで構成されています。

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

エクスポートの構造。「アカウントエクスポートファイル階層」および「訪問者エクスポートファイル階層」を参照してください。
エクスポート内のファイルの目的。各エクスポートファイルの説明については、「ファイルの説明」を参照してください。エクスポートファイルに含まれるデータの詳細については、データ同期スキーマの定義を参照してください。

ファイル階層

次のセクションでは、アカウントエクスポートと訪問者エクスポートに含まれるファイル構造の概要を説明します。ファイルに含まれる情報の詳細については、本記事の「ファイルの説明」および「データ同期スキーマの定義」を参照してください。

アカウントエクスポートファイル階層

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

├── exportmanifest.json
└── <export-uuid>/
   ├── billofmaterials.json
  ├── accounts.avro
   ├── metadata schema.avro
└── <export-uuid>/
   ├── ...

サブスクリプションに大量のアカウントがある場合は、次の形式の複数のアカウントファイルを受け取ることがあります。accounts-000.avro、accounts-001.avroなどです。

訪問者エクスポートファイル階層

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

├── exportmanifest.json
└── <export-uuid>/
   ├── billofmaterials.json
  ├── visitors.avro
   ├── metadata schema.avro
└── <export-uuid>/
   ├── ...

サブスクリプションに大量の訪問者がいる場合、次の形式の複数のアカウントファイルを受け取ることがあります。visitors-000.avro、visitors-001.avroなどです。

一意の識別子

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

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

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

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

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

アカウントファイル

アカウントエクスポートのコンテンツは、アカウントファイル内に存在します。アカウント量が少ない場合、この情報はaccounts.avroに保存されます。大量のアカウントエクスポートを含むサブスクリプションは、複数のアカウントファイルに分割される場合があり、次のような形式で名前が付けられます。accounts-000.avro、accounts-001.avroなどです。

次のコード例は、アカウントファイル内のエントリがどのようなものかを示しています。

{
    "agent_email": "testUser@pendo.io",
    "agent_firstname": "test",
    "agent_full_name": "test user",
    "agent_lastname": "user",
    "agent_user_job_role": "developer",
    "lastbrowsername": "Chrome",
    "lastbrowserversion": "89.0.4328",
    "lastservername": "local.pendo.io:3000",
    "accountid": "account1",
    "firstvisitMS": 1659627208875,
    "idhash": 5419074444
    "id": "accountId123",
    "accountids": [
        "account1"
    ],
    "lastupdatedMS": 1659627209099,
    "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4_0) AppleWebKit/537.36 (KHTML, like Gecko) Cypress/7.7.0 Chrome/89.0.4328.0 Electron/12.0.0-beta.14 Safari/537.36",
    "lastoperatingsystem": "Mac OS X",
    "lastvisitMS": 1659627208875,
    "custom": "{
        "myCustomField": "test"
    }",
    "pendo_hubspot": "{
        "record_id": 12345
    }",
    "salesforce": "{}"
}

エージェントメタデータグループのフィールドは、agent_field-nameに平坦化されます。カスタムメタデータやインテグレーションによって入力されたグループなど他のメタデータグループは、単一の文字列オブジェクトにまとめられます。メタデータファイルスキーマには、含まれる各フィールドの名前とタイプが含まれます。アカウントファイルのスキーマ定義の詳細については、「データ同期スキーマ定義」を参照してください。

訪問者ファイル

訪問者エクスポートのコンテンツは、ビジターファイル内に存在します。訪問者が少ない場合、この情報はvisitors.avroに保存されます。大量の訪問者エクスポートを含むサブスクリプションは、複数の訪問者ファイルに分割されることがあり、次のような形式で名前が付けられます。visitors-000.avro、visitors-001.avroなどです。

次のコード例は、訪問者ファイル内のエントリがどのようなものかを示しています。

{
    "agent_email": "testUser@pendo.io",
    "agent_firstname": "test",
    "agent_full_name": "test user",
    "agent_lastname": "user",
    "agent_user_job_role": "developer",
    "lastbrowsername": "Chrome",
    "lastbrowserversion": "89.0.4328",
    "lastservername": "local.pendo.io:3000",
    "accountid": "account1",
    "firstvisitMS": 1659627208875,
    "idhash": 5419074444
    "id": "visitorId123",
    "accountids": [
        "account1"
    ],
    "lastupdatedMS": 1659627209099,
    "lastuseragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4_0) AppleWebKit/537.36 (KHTML, like Gecko) Cypress/7.7.0 Chrome/89.0.4328.0 Electron/12.0.0-beta.14 Safari/537.36",
    "lastoperatingsystem": "Mac OS X",
    "lastvisitMS": 1659627208875,
    "custom": "{
        "myCustomField": "test"
    }",
    "pendo_hubspot": "{
        "record_id": 12345
    }",
    "salesforce": "{}"
}

エージェントメタデータグループのフィールドは、agent_field-nameに平坦化されます。カスタムメタデータやインテグレーションによって入力されたグループなど他のメタデータグループは、単一の文字列オブジェクトにまとめられます。メタデータファイルスキーマには、含まれる各フィールドの名前とタイプが含まれます。訪問者ファイルのスキーマ定義の詳細については、「データ同期スキーマ定義」を参照してください。

メタデータスキーマファイル

各エクスポートには、エクスポートファイルのスキーマを含むmetadataschema.avroファイルが含まれます。これを使用することで、メタデータがETLツールに適切にインポートされることを確実にできます。次のコード例は、metadataschema.avroファイル内のエントリがどのようなものかを示しています。

ファイルの説明

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

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

コンテンツタイプ	ファイル名	説明
定義管理ファイル：複数のエクスポートファイルとメタデータの記録	`exportmanifest.json`	日次エクスポートファイルの各部分を連結したリストで、過去30日間以内に生成されたエクスポートのローリングウィンドウを網羅しています。カウンターは、新しいエクスポートを受信するたびに反復処理を行います。ゼロ（0）の場合は何もする必要がなく、コンテンツが削除可能であることを意味します。
エクスポート管理ファイル：エクスポート内容の記録	`billofmaterials.json`	エクスポート内容のJSON表現。これは、エクスポートされたavroイベントファイルをデータウェアハウスで読み込むために、ETLオートメーションで使用されます。
アカウントファイル	`accounts.avro`	アカウントメタデータのエクスポートが含まれます。
訪問者ファイル	`visitors.avro`	訪問者メタデータのエクスポートが含まれます。
メタデータスキーマファイル	`metadataschema.avro`	エクスポートのスキーマが含まれます。

部品表

部品表にはエクスポート内容が記録されます。

アカウントエクスポートの部品表

次のコードスニペットは、アカウントデータ同期のエクスポートにおけるbillofmaterials.jsonの表示例です。

{
    "timestamp": "2023-02-16T20:21:11Z",  
    "numberOfFiles":65,
    "subscription": 65,
        "displayName": "ACME CRM",
        "id": "6591622502678528"
    },
    "accounts": {
        "count": 243,
        "files": [
            "accounts.avro"
        ]
    },
    "metadataSchemaFile": [
        "metadataschema.avro"
    ],
    "exportType": [
        "One-time"
    ],
    "dataLevel": "account"
}

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

["One-time"]エクスポートが1回限りのエクスポートの場合。
["Ongoing metadata updates"]エクスポートが進行中の場合。

accountsセクションの内容

countはエクスポートされたアカウント数です。
filesはエクスポートされたアカウントを含むファイル一覧です。複数のファイルが送信される場合、名前は次のようになります。accounts-000.avro、accounts-001.avroなどです。

アカウントがエクスポートされていない場合、accountsセクションは存在しません。

訪問者エクスポートの部品表

以下のコードスニペットは、訪問者データ同期のエクスポートにおけるbillofmaterials.jsonの表示例です。

{
    "timestamp": "2023-02-16T20:21:11Z",  
    "numberOfFiles":65,
    "subscription": 65,
        "displayName": "ACME CRM",
        "id": "6591622502678528"
    },
    "visitors": {
        "count": 243,
        "files": [
            "visitors.avro"
        ]
    },
    "metadataSchemaFile": [
        "metadataschema.avro"
    ],
    "exportType": [
        "One-time"
    ],
    "dataLevel": "visitor"
}

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

["One-time"]エクスポートが1回限りのエクスポートの場合。
["Ongoing metadata updates"]エクスポートが進行中の場合。

visitorsセクションの内容

countはエクスポートされたアカウント数です。
filesはエクスポートされたアカウントを含むファイル一覧です。複数のファイルが送信される場合、名前は次のようになります。visitors-000.avro、visitors-001.avroなどです。

訪問者がエクスポートされていない場合、visitorsセクションは存在しません。

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

訪問者とアカウントのエクスポートは、別々のエクスポートマニフェストによって管理されます。

エクスポートマニフェストは、エクスポートを読み取って取り込むための重要なファイルです。エクスポートマニフェストは、複数の部品表と追加のメタデータを連結したものです。エクスポートされる日付データに関係なく、過去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"
}

エクスポートマニフェストには、エクスポートとクラウドストレージに完全に読み込まれた後続ファイルのみが反映されます。エクスポートマニフェストに部分的なエクスポートは含まれません。エクスポートマニフェストにリストされているエクスポートは、常に完全なエクスポートです。

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

進行中のメタデータ更新には、以前にエクスポートされたメタデータの更新が含まれます。ETLプロセスには、アカウント（アカウントID）や訪問者（訪問者ID）の重複が誤って取り込まれないように、適切な「ドロップアンドリプレース」ロジックを含める必要があります。

読み込みの流れの例

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

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

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

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

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

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

メタデータスキーマを読み込みます。メタデータスキーマテーブルが存在しない場合は、作成します。メタデータスキーマテーブルが存在する場合は、すべてのデータを削除します。

ステップ3. アカウントまたは訪問者の反復処理

論理型マッピングを使用して、exportmanifest.jsonファイルまたはエクスポートのbillofmaterials.json内のリストから各アカウントまたは訪問者ファイルを読み込みます。アカウントまたは訪問者テーブルが存在しない場合は、作成します。重複を避けるため、アカウントまたは訪問者テーブルが存在する場合は、特定のアカウントIDまたは訪問者IDのアカウントまたは訪問者メタデータをテーブルから削除し、アカウントまたは訪問者ファイルのデータをアカウントまたは訪問者テーブルに追加します。