データ同期スキーマの定義

最終更新日: 2024年11月20日 02:44

Pendoのデータ同期機能を使用すると、AvroファイルをGoogle Cloud Storage（GCS）バケット、Amazon S3、Microsoft Azure Storageにエクスポートできます。「抽出、変換、読み込み」（ETL）パイプラインでの使用に適しているため、Avroファイルタイプを使用します。この記事では、データ同期プロセスの一環としてエクスポートされるAvroファイルと、Avroファイルの各タイプに含まれる値について説明します。

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

Pendoは、データ同期プロセスの一環として、イベントのエクスポート、訪問者のエクスポート、アカウントのエクスポートの3種類のavroファイルをエクスポートします。

日付とタイムスタンプは協定世界時（UTC）です。詳細については、「データ同期のエクスポート処理」の「タイムスタンプとタイムゾーン」をご参照ください。

イベントのエクスポート

エクスポートされる内容には、イベントファイルやイベントタイプの定義のほか、コンテキスト情報が含まれるため、追加のルックアップやAPIコールを行うことなく、イベントから最大限の価値を引き出すことができます。エクスポートされる内容は以下のとおりです。

すべてのイベントのイベントファイル（チームで未定義のものを含む）
ページ、フィーチャー、トラックイベントなど、定義された各イベントタイプ（「一致」）のイベントファイル。
各イベントタイプの定義ファイルと、定義された各イベントのメタデータと詳細を含むガイドイベント。
上記のすべてのファイルを参照するエクスポートマニフェスト。クラウドストレージからデータウェアハウスにデータを読み込むのに使用します。

訪問者のエクスポート

訪問者のエクスポートには、訪問者ファイルと訪問者メタデータのスキーマ定義が含まれます。エクスポートには次のものが含まれます。

エクスポートされたすべての訪問者に対して1つ以上の訪問者ファイル。訪問者数が多い場合、visitors-000.avro、visitors-001.avroと続く形式で名付けられたバッチファイルで送信されることがあります。
metadataschema.avroという名前のメタデータスキーマ定義ファイル。
上記のすべてのファイルを参照するエクスポートマニフェスト。クラウドストレージからデータウェアハウスにデータを読み込むのに使用します。

アカウントのエクスポート

アカウントのエクスポートには、アカウントファイルとアカウントメタデータスキーマ定義が含まれます。エクスポートには次のものが含まれます。

エクスポートされたすべてのアカウントに対して1つ以上のアカウントファイル。アカウント数が多い場合、accounts-000.avro、accounts-001.avroと続く形式で名付けられたバッチファイルで送信されることがあります。
metadataschema.avroという名前のメタデータスキーマ定義ファイル。
上記のすべてのファイルを参照するエクスポートマニフェスト。クラウドストレージからデータウェアハウスにデータを読み込むのに使用します。

イベントファイルスキーマ

イベントファイルスキーマは、データ同期用のAvroファイルでエクスポートするイベントデータの構造と形式を定義します。スキーマは、以下のイベントファイルのすべてのタイプに適用されます。

すべてのイベント
ページ
フィーチャー
トラックイベント

ガイドイベントは上記のイベントタイプファイルに含まれているため、独自のイベントファイルはありませんが、独自の定義ファイルがあります。

以下のスキーマ定義には、生成できるさまざまなイベントタイプ、各イベントタイプに関連付けられているフィールド、および各フィールドの定義に使用するデータタイプに関する情報が含まれています。

指標	タイプ	説明
`matchableId`	文字列	各イベントと一致するルールを持つ一致（ページ、フィーチャー、トラックイベント）への参照。すべてのイベントファイルには存在しません。
`periodId`	DATE	データウェアハウスへの読み込みを支援する便利なフィールドで、特定のイベントの`browserTimestamp`の日付部分に等しい。日付はすべてUTCで、形式は`YYYY-MM-DD`です。
`visitorId`	文字列	イベントの訪問者ID。
`accountId`	文字列	イベントのアカウントID。アカウント情報が利用できない場合は、空の文字列が使用されます。
`browserTimestamp`	LONG	イベントのタイムスタンプ。`use_avro_logical_types`フラグで日付としてデータウェアハウスに読み込むことができます。
`country`	文字列	`remoteIp`に関連付けられた国。このフィールドは空白でもかまいません。
`destinationStepId`	文字列	フローを示すガイドの宛先ステップのIDを指定する`guideAdvanced`イベントに関連します。前のステップIDまたは次のステップIDにできます。`singleEvents`および`guideEvents`ソースに表示されます。
`elementPath`	文字列	ウェブイベント用。空白か、イベントに関連するDOM要素を指定するCSSスタイルの文字列。モバイルの場合、イベントに関連するウィジェットのJSON形式の説明。
`eventClass`	文字列	`ui`または`track`。
`eventId`	文字列	一意のイベント識別子。
`eventSource`	文字列	イベントソースには、`email`（実際のメールにより発生したイベント）、`mobile`（モバイルアプリで発生したイベント）、`web`（ウェブページで発生したイベント）などがあります。
`eventType`	文字列	イベントのタイプ。次のような例が挙げられます。`change`：訪問者がアプリ内の要素を変更したことを示します。`click`：訪問者がアプリ内の要素をクリックしたことを示します。`focus`：訪問者がアプリ内の要素にフォーカスしたことを示します。`group`：Twilioセグメントのインテグレーションによる「グループ」呼び出しに応答するイベント。`guideActivity`：訪問者がPendoガイドを使用したことを示します。`guideDismissed`：訪問者がPendoガイドを閉じたことを示します。`guideSeen`：訪問者がPendoガイドを閲覧したことを示します。`identify`：アプリが訪問者やアカウントのアイデンティティを特定したことを示します。`load`：ページがロードされたことを示します。`meta`：アプリが訪問者やアカウントのメタデータを送信したことを示します。`pollResponse`：訪問者がPendoの投票とアンケート調査を送信したことを示します。
`guideId`	文字列	ガイド関連イベントや投票調査関連イベントを生成するガイドの一意の識別子。このフィールドは空白でもかまいません。
`guideSeenReason`	文字列	`guideSeen`イベントタイプの場合、ガイドがユーザーに表示された理由。
`guideSeenTimeoutMS`	LONG	`guideTimeout`イベントの場合、`guideTimeout`イベントの送信前に、特定のガイドステップが表示されるまでエージェントが待機した時間。
`guideSessionId`	文字列	ガイドや同時に読み込まれたその他納品物のリストの識別子。このIDは、クライアントからガイドがリクエストされるたびに変更され、読み込み中に発生するイベントは同じIDを持ちます。
`guideSnoozeDurationMS`	LONG	`guideSnoozed`イベントタイプの場合、ガイドのスヌーズ時間（ミリ秒単位）。
`guideStepId`	文字列	ガイド関連イベントや投票調査関連イベントを生成するガイドステップの一意の識別子。このフィールドは空白でもかまいません。
`language`	文字列	`guideSeen`イベントタイプの場合、表示されているガイドの言語。このフィールドは空白でもかまいません。
`latitude`	小数	イベントの`remoteIp`の緯度。このフィールドは空白でもかまいません。
`longitude`	小数	イベントの`remoteIp`の経度。このフィールドは空白でもかまいません。
`oldVisitorId`	文字列	Pendoが認証を通じて識別する前に、訪問者に割り当てられた匿名の訪問者 ID。
`loadDurationMS`	LONG	`load`イベントの場合、ウェブページのレンダリングにかかった時間（ミリ秒単位）。ページの動的部分の読み込みにかかる時間は含まれません。
`pollId`	文字列	`pollResponse`イベントを生成した投票調査の識別子。
`pollResponse`	文字列	`pollResponse`イベントを生成した投票調査に対するJSON形式の回答。投票調査でのみ利用可能なデータへのインデックスにできます。`eventType`が`pollResponse`でない場合、`pollResponse`プロパティはありません。
`pollType`	文字列	`pollResponse`イベントを生成した投票調査のタイプ。`NumberScale`、`PositiveNegative`、`FreeForm`、`PickList`のいずれかです。
`propertiesJson`	文字列	ページパラメータを含む、このイベントのすべてのユーザー定義イベントプロパティのJSON形式のマップ。履歴メタデータが訪問者またはアカウントに昇格された場合、このJSONにはそれぞれ`visitormetadata`と`visitormetadata`文字列が含まれます。
`region`	文字列	イベントの`remoteIp`のうち、州を表す2文字のコードで示される米国の地域。このフィールドは空白でもかまいません。
`remoteIp`	文字列	イベントを生成した`remoteIp`。このデータを収集しない場合、代わりに0.0.0.0が保存されます。ipv6アドレスにすることもできます。一部のプロキシとモバイルネットワークでは、有用なIPアドレスは収集されません。
`server`	文字列	イベントのURLのサーバー名部分。このフィールドは空白でもかまいません。
`uiElementActions`	文字列	エージェントによって`guideActivity`イベントが送信されるガイドとのインタラクションに関連付けられた要素アクション（`openLink`や`guideSnoozed`など）。これは、`singleEvents`および`guideEvents`のソースに表示されます。
`uiElementId`	文字列	ガイド内のUI要素がクリックされたときのガイド要素の一意の識別子。これにより、`guideActivity`イベントがエージェントに送信されます。これは、`singleEvents`、`guideEvents`、`guideElementClick`、および`guideElementClickEver`のソースに表示されます。
`uiElementText`	文字列	エージェントが`guideActivity`イベントの一環としてフィールドを送信するときのガイド要素のテキスト。`guideActivity`イベントがガイド要素のテキストと共に送信されると、`ui_element_text`が`singleEvents`および`guideEvents`のソースに表示されます。`ui_element_text`フィールドなしで`guideActivity`イベントが送信された場合でも、処理は実行されます。サブスクリプションによりすべてのテキストの除外を選択した場合、イベントが同時に送信されたとしても、`ui_element_text`は保存されません。
`uiElementType`	文字列	`guideActivity`イベントの送信時にクリックされた要素のタイプ。これは、`singleEvents`および`guideEvents`のソースに表示されます。
`url`	文字列	ウェブイベントを生成したページの正規化されたURL。モバイルイベントの場合、URLは画面構造をJSON形式で表したものになります。
`userAgent`	文字列	ウェブイベントを受信したときの、HTTPSリクエストからのユーザーエージェント。モバイルイベントの場合、`userAgent`はイベントを生成したデバイスタイプをテキスト形式で表したものになります。どちらのタイプの値も、ユーザーエージェントの解析機能と集計によって適切に解析されます。

イベントタイプの定義

ページ、フィーチャー、およびトラックイベントの定義は、それぞれのAvroファイルに含まれており、該当するイベントファイルに含まれるイベントデータに追加できます。

ページ

指標	タイプ	説明
`pageId`	文字列	ページの識別子。
`kind`	文字列	オブジェクトの種類の説明。常に`Page`になります。
`lastUpdatedAt`	LONG	ページが最後に更新されたときのエポックタイムスタンプ（ミリ秒単位）。
`createdAt`	LONG	ページが作成されたときのエポックタイムスタンプ（ミリ秒単位）。
`rulesJson`	文字列	Pendoの従来の（レガシー版）デザイナー（Designer）によって作成されたページを定義する正規表現ルール。従来のデザイナーではなくビジュアルデザインスタジオ（Visual Design Studio）で作成されたページでは、このフィールドは空になります。
`name`	文字列	ページに付けられた名前。
`isCoreEvent`	ブール値	イベントがPendo Coreイベントかどうか。

フィーチャー

指標	タイプ	説明
`featureId`	文字列	フィーチャーの識別子（サブスクリプションごとに一意）。
`kind`	文字列	オブジェクトの種類の説明。常に`Feature`になります。
`lastUpdatedAt`	LONG	フィーチャーが最後に更新されたときのエポックタイムスタンプ（ミリ秒単位）。
`createdAt`	LONG	フィーチャーが作成されたときのエポックタイムスタンプ（ミリ秒単位）。
`pageId`	文字列	フィーチャーを含むページの識別子。
`name`	文字列	フィーチャーに付けられた名前。
`isCoreEvent`	ブール値	イベントがPendo Coreイベントかどうか。

トラックイベント

指標	タイプ	説明
`trackTypeId`	文字列	トラックイベントの識別子（サブスクリプションごとに一意）。
`kind`	文字列	オブジェクトの種類の説明。常に`TrackType`になります。
`lastUpdatedAt`	LONG	トラックイベントが最後に更新されたときのエポックタイムスタンプ（ミリ秒単位）。
`createdAt`	LONG	トラックイベントが作成されたときのエポックタイムスタンプ（ミリ秒単位）。
`eventPropertyNames`	文字列	含まれているトラックイベントプロパティの名前。
`name`	文字列	トラックイベントに付けられた名前。
`isCoreEvent`	ブール値	イベントがPendo Coreイベントかどうか。

ガイド

指標	タイプ	説明
`guideId`	文字列	ガイドの識別子（サブスクリプションごとに一意）。
`kind`	文字列	オブジェクトの種類の説明。常に`Guide`になります。
`lastUpdatedAt`	LONG	ガイドが最後に更新されたときのエポックタイムスタンプ（ミリ秒単位）。
`createdAt`	LONG	ガイドが作成されたときのエポックタイムスタンプ（ミリ秒単位）。
`state`	文字列	ガイドの可視性の状態（`draft`、`staged`、`public`、`disabled`）。
`name`	文字列	ガイドに付けられた名前。
`emailState`	文字列	NPSのメールバックアップの状態（無効の場合は`draft`、有効の場合は`public`）。
`launchMethod`	文字列	ハイフンで区切られた、ガイドに適用される起動方法のセット。
`isMultiStep`	ブール値	ガイドに複数のステップがあるかどうか。
`isTraining`	ブール値	ガイドが「Adopt for Partners」のエンドユーザーアプリケーションに属するかどうか。
`recurrence`	LONG	NPSガイドの反復期間（ミリ秒単位）。
`recurrenceEligibilityWindow`	LONG	均等配信が有効になっている場合に、個々の訪問者がNPSガイドの対象となる時間（ミリ秒単位）。
`attributeJson`	文字列	ガイドのタイプ、バッジの説明、ガイドが有効になるデバイスのタイプ、最後にガイドを編集したビジュアルデザインスタジオ（Visual Design Studio）のバージョンなどを含む、ガイド属性のJSON表現。
`audience`	文字列	ガイドがターゲットとする訪問者を定義するロジック。
`audienceUiHint`	文字列	ガイドに適用されたセグメントを人間が判読できる形式で表したもの。
`resetAt`	LONG	ガイドが最後にリセットされたときのタイムスタンプ。
`publishedAt`	LONG	ガイドが最後に公開されたときのタイムスタンプ。
`steps`	レコード	`guideStepId`、`name`、`pageId`、`appRelayUrl`、`elements`のSTRING値を含むガイドステップ。

現時点では、投票とアンケート調査の質問はガイドオブジェクトスキーマでは送信されません。

訪問者ファイルスキーマ

Pendoの訪問者ファイルスキーマでは、訪問者データの構造と形式が定義されます。このデータは、データ同期の訪問者エクスポート用にAvroファイル形式でエクスポートされます。

指標	タイプ	説明
`id`	文字列	訪問者の一意の識別子。
`accountids`	配列	訪問者に割り当てられた一意のアカウントIDs（文字列の値）のリスト
`accountId`	文字列	訪問者に関連付けられたアカウントID。
`lastservername`	文字列	最後に使用したサーバー名。
`firstvistMS`	LONG	イベントが訪問者に対して最初にキャプチャされたときのタイムスタンプ（ミリ秒単位）
`idhash`	整数	訪問者IDのハッシュ。
`lastbrowsername`	文字列	最後に使用したブラウザ名。
`lastbrowserversion`	文字列	最後に使用したブラウザのバージョン。
`lastoperatingsystem`	文字列	最後に使用したオペレーティングシステム。
`lastvisitMS`	LONG	訪問者に対してイベントが最後に記録された時刻のタイムスタンプ（ミリ秒単位）。
`lastupdatedMS`	LONG	訪問者が最後に更新された時刻のタイムスタンプ（ミリ秒単位）。
`lastuseragent`	文字列	最後に使用したユーザーエージェント（未解析）。
`identifiedvisitoratMS`	LONG	Pendoアイデンティティ管理によって匿名の訪問者IDと識別済みの訪問者IDが統合された際に、訪問者が特定された時刻のタイムスタンプ（ミリ秒単位）が表示されるフィールドです。
`identifiedvisitorid`	文字列	Pendoアイデンティティ管理によって匿名の訪問者IDと識別済みの訪問者IDが統合された際に、識別済みの訪問者IDが表示されるフィールドです。これにより、訪問者ジャーニーを一元的に表示できます。
`<fieldname>_<APP>_<ID>`	STRING、LONG、INTのいずれかで、フィールドによって異なる	複数アプリのサブスクリプションの場合、Pendoは、上記のメタデータフィールドのいずれかに、`__`__の値を送信します。この値はアプリケーションによって異なる場合があります。これが可能なメタデータフィールドでは、メタデータスキーマファイルの`IsPerApp`が`true`に設定されています。
`agent_<fieldname>`	フィールドによって異なる	各エージェントメタデータフィールドに対して、フィールドが訪問者のAvroファイルに作成されます。フィールドタイプは、PendoのData Mappingsページでどのようにデータを設定したかによって異なります。PendoメタデータフィールドタイプとAvroタイプのマッピングについては、「PendoとAvroのデータマッピング」を参照してください。
`<metadata_group>`	文字列	`エージェント`以外のメタデータグループに対しては、メタデータグループとそのすべてのフィールドのJSON表現を送信します。メタデータスキーマファイルには、メタデータグループの各フィールドの名前、タイプ、その他の情報が含まれています。
`incompleteFields`	STRINGのリスト	メタデータスキーマで指定されたタイプと互換性のない値を持つメタデータフィールドのリスト。

アカウントファイルのスキーマ

アカウントファイルのスキーマは、データ同期のアカウントエクスポート用にAvroファイルでエクスポートするアカウントデータの構造と形式を定義します。

指標	タイプ	説明
`id`	文字列	アカウントの一意の識別子。
`auto.id`	文字列	`id`と同じ一意の識別子。
`firstvistMS`	LONG	アカウントに対してイベントが最初にキャプチャされた時刻のタイムスタンプ（ミリ秒単位）。
`idhash`	整数	アカウントIDのハッシュ。
`lastvisitMS`	LONG	アカウントに対してイベントが最後にキャプチャされた時刻のタイムスタンプ（ミリ秒単位）。
`lastupdatedMS`	LONG	アカウントが最後に更新された時刻のタイムスタンプ（ミリ秒単位）。
`<fieldname>_<APP>_<ID>`	STRING、LONG、INTのいずれかで、フィールドによって異なる	複数アプリのサブスクリプションの場合、Pendoは、上記のメタデータフィールドのいずれかに、`__`__の値を送信します。この値はアプリケーションによって異なる場合があります。これが可能なメタデータフィールドでは、メタデータスキーマファイルの`IsPerApp`が`true`に設定されています。
`agent_<fieldname>`	フィールドによって異なる	各エージェントメタデータフィールドに対して、フィールドが訪問者のAvroファイルに作成されます。フィールドタイプは、PendoのData Mappingsページでどのようにデータを設定したかによって異なります。PendoメタデータフィールドタイプとAvroタイプのマッピングについては、「PendoとAvroのデータマッピング」を参照してください。
`<metadata_group>`	文字列	`エージェント`以外のメタデータグループに対しては、メタデータグループとそのすべてのフィールドのJSON表現を送信します。メタデータスキーマファイルには、メタデータグループの各フィールドの名前、タイプ、その他の情報が含まれています。
`incompleteFields`	STRINGのリスト	メタデータスキーマで指定されたタイプと互換性のない値を持つメタデータフィールドのリスト。

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

指標	タイプ	説明
`avroFieldName`	文字列	訪問者のAvroファイル内のフィールド名。
`name`	文字列	Pendoのメタデータフィールド名。
`グループ`	文字列	Pendoのメタデータフィールド内のグループ名。
`displayName`	文字列	Pendoのメタデータフィールドの表示名。
`type`	文字列	フィールドのデータ型。`string`、`int`、`float`、`boolean`、`time`、`list`などをオプションとして選択できます。
`elementType`	文字列	`型`が`list`の場合、各要素のデータ型。それ以外の場合は空です。
`elementformat`	文字列	メタデータフィールドのデータ形式。たとえば、`型`が`time`の場合、`elementformat`は`milliseconds`で表されることがあります。
`isDeleted`	ブール値	フィールドが削除済みの場合はtrue。
`isPerApp`	ブール値	フィールドが各アプリケーションに存在できる場合は、true。これは、マルチアプリサブスクリプションの場合にのみ可能です。

PendoとAvroのデータマッピング

Pendoデータマッピングのフィールドタイプ	Avroタイプ
テキスト（string）	文字列
数値型（整数）	整数
数値型（小数）	小数
ブール値（boolean）	ブール値
日付（time）	LONG（ミリ秒の論理タイプ）
リスト（list）	配列

例

イベントファイルスキーマは、各イベントタイプ（すべてのイベント、ページ、フィーチャー、トラックイベント）のすべてのファイルに適用されます。ガイド専用のファイルはありません。代わりに、ガイドイベントは、該当するページ、フィーチャー、およびトラックイベントのファイルと同様に、すべてのイベントファイルに含まれます。

たとえば、「ガイドY」が「ページX」で起動された場合、guideActivityイベントはすべてのイベントファイルおよび「ページX」のイベントストリームに存在し、guideIdは「Y」に設定されます。イベントがguideActivityイベントでない場合、ガイドイベントに関連付けられたフィールドは空白になります。

さらに、イベントタイプごとに複数のイベントファイルが存在する場合があります。たとえば、アプリケーションに3件のタグ付きページ、2件のタグ付きフィーチャー、および2件の定義済みトラックイベントがある場合、エクスポートごとに以下の12個のavroファイルを受け取ります。

ガイド定義（allguides.avro）
ページ定義（allpages.avro）
フィーチャー定義（allfeatures.avro）
トラックイベント定義（alltracktypes.avro）
すべてのイベントファイル（allevents.avro）
3件のページイベントファイル（page1.avro、page2.avro、page3.avro）
2件のフィーチャーイベントファイル（feature1.avro、feature2.avro）
2件のトラックイベントファイル（tracktype1.avro、tracktype2.avro）

上記リスト内のファイル名は、説明を目的としたものです。実際のページ、フィーチャー、トラックイベントのファイル名は、各エクスポートの「billofmaterials.json」にある適切なIDを反映したものになります。