Databricks

早期アクセス

この機能は早期アクセスです。この期間中、機能のさまざまな側面はまだ開発されている可能性があり、このドキュメントは常に最新であるとは限りません。ご質問がある場合は、までお問い合わせください。Amplitude Support.

Amplitudeの生イベントデータをUnity CatalogのDeltaテーブル経由でDatabricksワークスペースにロードします。接続はOAuthワークロードアイデンティティフェデレーション（WIF）で認証されるため、Amplitudeはお客様のワークスペースのクライアントシークレットを長期間保持することはありません。

考慮事項

Amplitudeはベストエフォートベースでエクスポートを行います。データはAmplitudeがイベントを受信してから約20分以内にターゲットのDeltaテーブルに到着する予定ですが、タイミングは負荷やボリュームによって異なる場合があります。
同じAmplitudeプロジェクトから複数のDatabricksエクスポートを作成できます。各エクスポートには独自のイベントフィルタと送信先テーブルがあるため、単一のプロジェクトを専用のテーブルにファンアウトできます。

前提条件

Amplitudeでは管理者またはマネージャー権限が必要であり、Databricksではサービスプリンシパルの管理、Unityカタログの認可の作成、アカウントレベルのフェデレーションポリシーの作成を行うための役割が必要です。

ウィザードを開く前に、Databricksで次のことを設定してください。

Unity Catalog カタログとスキーマを備えた Databricks ワークスペース。ワークスペースホストをキャプチャします (例: https://dbc-xxxx.cloud.databricks.com)。
SQL ウェアハウス。 Databricks UIの「SQL ウェアハウス」→「対象のウェアハウス」→「JSON を表示」または「URL」からウェアハウスIDを取得します。
[設定] → [アイデンティティとアクセス] → [サービスプリンシパル] にあるサービスプリンシパル。 OAuth シークレットを生成しないでください。両方をキャプチャします：
- application_id（UUID）。ウィザードはこれを「clientId」と呼び、これはAmplitudeが実行時に使用する認証情報です。
- 数値のサービスプリンシパルID。ウィザードはこれを使用して、フェデレーションポリシーCLIコマンドを補完します。

ワークロード ID フェデレーションを使用する理由とは？

WIF は、OAuth マシン間 (M2M) 認証に必要な共有クライアントシークレットを削除します。この連携では、これはより安全なデフォルトです。

**共有シークレットはありません。**Amplitudeは、ライブエクスポート実行以外でサービスプリンシパルとして認証される認証情報を決して受け取ることはありません。
あなたがローテーションする必要はありません。 この認証情報は寿命が短いJWTであり、Amplitudeのインフラストラクチャは自動的に作成および更新します。お客様の側でパスワードやキーがドリフトしたり、期限切れになったり、バックアップを通じて漏洩したりすることはありません。
1行で失効。 サービスプリンシパル上のフェデレーションポリシーを削除すると、同じワークスペース上の他の統合を妨げることなく、Amplitudeの認証機能がすぐに終了します。

ウィザードがフェデレーションポリシーコマンドとUnity Catalogの権限付与SQLを生成します。セットアップ時にDatabricksでこれらを実行します。

連携を設定する

セットアップウィザードには、「スタート」と「セットアップ」という2つのステップがあります。ウィザードはDatabricks CLIコマンドとGRANT SQL文を入力に合わせて生成するため、ページを離れることなくDatabricksでそれらを実行できます。

Amplitudeデータで、**[カタログ]をクリックし、[宛先]**タブを選択します。
Warehouse Destinations セクションで、Databricks をクリックします。
はじめに ステップで、今日取り込まれたイベントと今後のイベントをエクスポートする を選択します。Amplitudeがデータをエクスポートする頻度を頻度ピッカーで設定します（デフォルトは1時間ごとです）。特定の基準を満たすイベントのみをエクスポートするには、フィルタを追加します。 [次へ] をクリックします。
セットアップステップで、**認証情報 (OAuth WIF)**の詳細を入力します。
- ワークスペースホスト: スキームを含む完全なワークスペース URL（例： https://dbc-xxxx.cloud.databricks.com）。
- サービスプリンシパルID（数値）：Databricks UIの「設定」→「アイデンティティとアクセス」→「サービスプリンシパル」→「対象のサービスプリンシパル」にある数値IDです。ウィザードは、この値を [フェデレーションポリシー] コマンドを入力するためにのみ使用します。Amplitudeはそれを保存しません。
- サービス・プリンシパルapplication_id (clientId):同じDatabricksページのUUID。これはAmplitudeが実行時に使用する認証情報です。
右側にあるフェデレーションポリシーコマンドをコピーし、ワークスペースではなく、Databricksアカウントに対して認証されたDatabricks CLIを使用して実行します。このコマンドは、Databricksにサービス・プリンシパルの身元証明としてAmplitudeの環境から得られたJWTを受け入れるよう指示します。ウィザードは、プロジェクトを実行している Amplitude 環境に対して、コマンド内の OIDC 発行者を自動的に設定します。
同じ手順で、Unity カタログのターゲットを入力します。
- カタログ、スキーマ、テーブル名：Amplitudeがイベントを書き込む場所の3つの部分からなるUnityカタログ識別子です。 Amplitudeはテーブルが存在しない場合、最初の実行時にテーブルを作成します。
- SQLウェアハウスID：AmplitudeがCOPY INTOステートメントを実行するために使用するウェアハウスです。
右側にあるUnity Catalog grants SQLをコピーし、Databricks SQLエディタで実行します。次に、Databricks UIで「SQL Warehouses」→「対象のウェアハウス」→「Permissions」を開き、サービスプリンシパルに「CAN USE」を許可します。ウェアハウス権限はSQL経由で付与することはできません。
完了をクリックします。

Amplitudeは認証情報とエクスポートスケジュールを作成します。最初の実行は、選択したケイデンスで次のスケジュールされたティックで実行され、認証情報がエンドツーエンドで検証されます。

Amplitudeのアクセス権を取り消す

Amplitudeがサービスプリンシパルとして認証されないようにするには、ステップ4で作成したフェデレーションポリシーを削除します。

bash

databricks account service-principal-federation-policy list <sp-application-id> \
  --profile <your-databricks-account-profile>
databricks account service-principal-federation-policy delete <sp-application-id> <policy-id> \
  --profile <your-databricks-account-profile>

セットアップ時にフェデレーションポリシーコマンドで使用したのと同じDatabricksアカウントプロファイルを使用してください。ワークスペーススコープ付きプロファイルは、これらのサブコマンドに対して401を返します。

ポリシーを削除すると、次回のスケジュール済み実行は PERMISSION_DENIED で失敗し、Databricks はサービスプリンシパルのワークスペーストークンの発行を停止します。また、有効なトークンに対するデータアクセスをブロックするには、ステップ5からUnityカタログの許可を削除します。

Databricks のエクスポート形式

データの場所

Amplitudeは、セットアップウィザードで指定したUnityカタログテーブルにイベントを書き込みます。入力した値を使用した場合、完全な識別子は {catalog}.{schema}.{table_name} となります。

異なるイベントスライスを異なるテーブルにルーティングします。

AmplitudeのDatabricks送信先を使用すると、同じプロジェクトから複数のエクスポートを作成できます。各送信先には独自のイベントフィルタと独自の送信先テーブルがあるため、プロジェクトのイベントストリームを専用のテーブルにファンアウトできます。たとえば、チェックアウトイベントをフィルタリングして analytics.finance.checkout_events に送信する 1 つの送信先と、エンゲージメントイベントをフィルタリングして analytics.product.engagement_events に送信する 2 つ目の送信先を設定します。

イベントテーブルスキーマ

イベントテーブルでは、次のデルタカラムを使用しています。

列	タイプ	概要
`amplitude_attribution_ids`	バリアント	イベントのハッシュ化されたアトリビューション ID。
`amplitude_id`	BIGINT	ユーザーのオリジナルAmplitude ID。このフィールドを使用して、マージされたユーザーを自動的に処理できます。例: 2234540891
`app`	BIGINT	プロジェクトの [設定] ページにあるプロジェクトIDです。例：123456。
`city`	文字列	市区町村たとえば、「サンフランシスコ」です。
`client_event_time`	タイムスタンプ	デバイスがイベントを記録した時点のローカルタイムスタンプ（UTC）。例: `2015-08-10T12:00:00.000000`。
`client_upload_time`	タイムスタンプ	デバイスがイベントをアップロードした時点のローカルタイムスタンプ（UTC）。例: `2015-08-10T12:00:00.000000`。
`country`	文字列	国。例：「アメリカ合衆国」。
`data`	バリアント	Amplitudeが`first_event`や`merged_amplitude_id`などの特定のフィールドを格納するディクショナリ。
`device_carrier`	文字列	デバイスキャリア。例：Verizon。
`device_family`	文字列	デバイスファミリ。例: Apple iPhone。
`device_id`	文字列	デバイス固有の識別子。例: C8F9E604-F01A-4BD9-95C6-8E5357DF265D。
`device_type`	文字列	デバイスのタイプ。例：Apple iPhone 5s。
`dma`	文字列	指定マーケティングエリア（DMA）。例: サンフランシスコ – オークランド – サンノゼ, カリフォルニア州。
`event_id`	BIGINT	イベントを区別するカウンタ。例: 1.
`event_properties`	バリアント	半構造化 JSON としてのイベントプロパティ。
`event_time`	タイムスタンプ	Amplitudeタイムスタンプ (UTC)。これは`client_event_time`、`server_received_time`と`client_upload_time`の差によって調整されます: `event_time` = `client_event_time` + (`server_received_time` - `client_upload_time`)。Amplitudeはこのタイムスタンプを使用して、Amplitudeチャート上のイベントを整理します。 `server_received_time`と `client_upload_time`の差が 60 秒未満の場合、Amplitude は `event_time` を調整せず、その値は `client_event_time` と等しくなります。例: `2015-08-10T12:00:00.000000`。
`event_type`	文字列	イベントタイプ
`group_properties`	バリアント	プロパティを半構造化 JSON としてグループ化します。
`groups`	バリアント	グループのタイプ。詳細については、「アカウントレベルのレポート作成」を参照してください。
`ip_address`	文字列	IP アドレス。例：「123.11.111.11」。
`language`	文字列	デバイスによって報告された言語。
`library`	文字列	イベントを送信したAmplitude SDK。
`location_lat`	DOUBLE	緯度。例: 12.3456789。
`location_lng`	DOUBLE	経度。例: -123.4567890。
`os_name`	文字列	OS名。例：iOS。
`os_version`	文字列	OS バージョン。
`paying`	文字列	ユーザーが収益を記録したことがある場合は True です。それ以外の場合は何もありません。プロパティ値は、Identify APIを使用して変更できます。例：trueです。
`platform`	文字列	イベントを送信したプラットフォーム。
`processed_time`	タイムスタンプ	Amplitudeがイベントを処理した時刻。
`region`	文字列	地域例：カリフォルニア州。
`sample_rate`	BIGINT	イベントサンプリングレート。
`server_received_time`	タイムスタンプ	Amplitudeがイベントを受信した時点のサーバー時間。
`server_upload_time`	タイムスタンプ	Amplitudeサーバーがイベントを受信した時のAmplitudeタイムスタンプ（UTC）。例: `2015-08-10T12:00:00.000000`。
`session_id`	BIGINT	エポックからのセッション開始時刻（ミリ秒単位）。例：1396381378123
`start_version`	文字列	Amplitudeが最初にユーザーを追跡した時のアプリのバージョン。例：1.0.0。
`user_creation_time`	タイムスタンプ	Amplitudeがこのプロジェクトで最初にユーザーを観測した時点のタイムスタンプ（UTC）。
`user_id`	文字列	指定した読み取り可能なID。変わらないものを使用してください。ユーザーのメールアドレスの使用は避けてください。
`user_properties`	バリアント	半構造化JSONとしてのユーザープロパティ。
`uuid`	文字列	イベントごとに固有の識別子をAmplitudeが取り込み時に割り当てます。これを結合キーとして使用すると、更新やバックフィルを通じてイベントを重複排除できます。
`version_name`	文字列	SDKがレポートするアプリのバージョン。例：1.0.0。

バックフィル

接続詳細ビューのバックフィルタブは、繰り返しエクスポートが書き込むのと同じデルタテーブルに過去の日付範囲を再現します。バックフィルを使用すると、接続が存在する前のイベントを使用して新しいエクスポートをシードしたり、アップストリームの再処理後に履歴ウィンドウを更新したり、Databricks側でダウンストリームのデータ損失から回復したりできます。

今後の予定

近日公開：

マージされたAmplitude IDのエクスポート。

Amplitudeのユーザーマージレジャーを追跡する2番目のテーブルです。これにより、ユーザーの正規Amplitude IDにイベントを正しく結合できます。

データ設定のエクスポート

イベント変換とカスタムイベント定義のスナップショット。これにより、ウェアハウス側のクエリはAmplitudeで構築したセマンティクスと整合性が保たれます。

これは役に立ちましたか？