Google Cloud Storage（GCS）

AmplitudeのGCSインポート機能を使用すると、GCSバケットからイベントやユーザープロパティをAmplitudeプロジェクトにインポートできます。 この記事は、Amplitude内でこのデータソースを設定する方法を説明します。

はじめに

前提条件

作業を開始する前に、いくつかの前提条件を満たしていることを確認してください。

• 適切な権限を持つGCSサービスアカウントを持っていることを確認してください。詳細はこちら。
• データを受け取るためにAmplitudeプロジェクトが存在することを確認してください。 そうでない場合は、新しいプロジェクトを作成してください。
• 自分がAmplitudeプロジェクトの管理者またはマネージャであることを確認してください。
• GCS バケットにデータファイルを取り込む準備ができていることを確認してください。これらは、コンバータファイルで説明したマッピングに準拠している必要があります。
• GCS バケット内のデータが、Amplitude の HTTP API v2 仕様に記載されている形式に従っていることを確認してください。

ファイル要件

Amplitudeに送信したいファイルは、いくつかの基本的な要件に従っている必要があります：

• ファイルにはイベントが含まれています。イベントは 1 行につき 1 つです。
• ファイルはイベントの時系列順にアップロードされます。
• ファイル名は一意です。
• ファイルサイズは1MBを超え、5GB未満である必要があります。大規模なイベントを処理するお客様の場合、Amplitudeは最適なパフォーマンスを得るために500MB近くのファイルサイズを推奨しています。
• ファイルは、圧縮または非圧縮の JSON、CSV、または Parquet ファイルです。

GCS サービスアカウントを作成し、権限を設定する

まだ作成していない場合は、Google Cloud コンソール内でAmplitudeのサービスアカウントを作成してください。 これにより、AmplitudeはデータをGoogle Cloudプロジェクトにエクスポートできます。

サービスアカウントを作成したら、サービスアカウントキーファイルを生成してダウンロードし、Amplitudeにアップロードしてください。 AmplitudeのアカウントキーをJSON形式でエクスポートしてください。

このサービスアカウントを、データをエクスポートしたいバケットのメンバーとして追加してください。 このメンバーにストレージ管理者の役割を必ず付与して、Amplitudeがデータをバケットにエクスポートするために必要な権限を持つようにしてください。

必要に応じて、独自のロールを作成することもできます。

エクスポート処理には、少なくとも以下の権限が必要であることに注意してください。

• storage.buckets.get。
• storage.objects.get。
• storage.objects.create。
• storage.objects.delete。
• storage.objects.list。

新しいGCSソースを追加

Amplitudeがデータを取得するための新しいGCSデータソースを追加するには、以下の手順に従ってください：

1. Amplitudeデータで、[カタログ] をクリックし、[ソース] タブを選択します。
2. [ウェアハウスソース] セクションで、**[GCS] **をクリックします。
3. サービスアカウントキーファイルをアップロードします。 これにより、AmplitudeはGCSバケットからデータをプルする権限を得ることができます。
4. サービスアカウントキーファイルをアップロードしたら、バケット名とデータが保存されているフォルダを入力します。
5. Next をクリックして、認証情報をテストします。 すべての情報に問題がなければ、Amplitudeは成功メッセージを表示します。次へ > をクリックして処理を続行します。
6. 「データソースを有効にする」パネルで、データソースに名前を付け、それに説明を付けます。この情報は、後で設定から編集できます。 次に、「ソースを保存」をクリックします。 Amplitudeは、あなたがソースを作成して有効化したことを確認します。
7. ［完了］をクリックして、データソースのリストに戻ります。 コンバータをすでに設定済みの場合、データのインポートは数分後に開始されます。 それ以外の場合は、データコンバータを作成する必要があります。

コンバータ設定を作成する

AmplitudeのGCS取り込みソースを設定する最後のステップは、コンバータファイルを作成することです。 コンバータの設定により、連携に次の情報が提供されます。

• 有効なデータファイルがどのようなものかをAmplitudeに伝えるパターンです。 たとえば、"\w+_\d{4}-\d{2}-\d{2}.json.gz" です。
• ファイルが圧縮されているかどうか、圧縮されている場合はどのように圧縮されているか。
• ファイルのフォーマットです。 たとえば、CSV(特定の区切り文字付き)やJSONオブジェクトの行などです。
• ファイルからAmplitudeイベントへの各行のマップ方法。

コンバータファイルは、取り込まれたファイルをどのように処理するかをAmplitudeに伝えます。 これを作成するには2つのステップが必要です。まず、ファイルの圧縮タイプ、ファイル名、およびエスケープ文字を設定します。 次に、JSONを使用してコンバータが従うルールを記述します。

ガイド付きコンバータ作成

Amplitudeの新しいガイド付きコンバータ作成インターフェイスを使用してコンバータを作成できます。 これによりフィールドを視覚的にマッピングおよび変換できるようになり、JSON 設定ファイルを手動で作成する必要がなくなります。 内部的には、UIはAmplitudeで使用されている既存のJSON設定言語にコンパイルされます。

まず、インポートできるさまざまなデータタイプ（イベントデータ、ユーザープロパティデータ、グループプロパティデータ）について確認します。

特定のフィールドを選択した後、データベース内のフィールドを変換することを選択できます。 これを行うには、「変換」をクリックし、適用したい変換の種類を選択します。 各変換の簡単な説明をご覧いただけます。

フィールドを選択すると、変換モードを開き、さまざまな変換の中から選択できます。

選択する変換によっては、より多くのフィールドを含める必要がある場合があります。

変換に必要なすべてのフィールドが整ったら、それを保存できます。要件が変わった場合は、これらの情報を更新できます。

Amplitudeはデータを取り込むために特定のフィールドを必要としますが、「マッピングを追加」ボタンをクリックすることで追加できるフィールドもサポートしています。 ここでは、Amplitudeはイベントプロパティ、ユーザープロパティ、グループプロパティ、および追加プロパティの4種類のマッピングをサポートしています。

イベント用にサポートされているフィールドの一覧は、HTTP V2 API のドキュメントを参照してください。ユーザープロパティ用にサポートされているフィールドの一覧は、Identify API のドキュメントを参照してください。 これらのリストに含まれていない列は、event_properties または user_properties のいずれかに追加してください。そうしないと、Amplitude はそれらを無視します。

Amplitudeに持ち込みたいすべてのフィールドを追加した後、この設定のサンプルをデータプレビューセクションで確認できます。 データプレビューは、フィールドやプロパティを追加または削除すると自動的に更新されます。 データプレビューでは、ソースレコードに基づくいくつかのサンプルレコードと、Amplitudeがそのデータをどのようにインポートするかを見ることができます。 これにより、必要なすべてのデータポイントを確実にAmplitudeに取り込むことができます。 10種類の異なるサンプルソースレコードと、それに対応するAmplitudeイベントを確認できます。

コンバータ言語は、JSON 要素に与えられた値を抽出することを記述しています。 これを指定するには、SOURCE_DESCRIPTION を使用します。この値には次のものが含まれます。

• BASIC_PATH。
• リスト演算子。
• JSON_OBJECT。

Amplitudeでコンバータを設定する

1. ［Edit Import Config］をクリックして、ファイルの圧縮タイプ、ファイル名、およびエスケープ文字を設定します。コンバータファイルのボイラープレートは、この手順で行った選択に基づいて事前に入力されます。また、［Pull File］をクリックすることで、設定が機能するかどうかをテストすることもできます。
2. [次へ] をクリックします。
3. テキストエディタでコンバータ規則を入力します。
4. コンバージョンをテストしてください。 テスト変換 をクリックします。コンバージョンプレビューを確認します。 必要に応じてコンバータの設定を調整してください。
5. 完了 をクリックします。

{bucket name}/{GCSPrefix}/2024/09/01/00/
  to  
{bucket name}/{GCSPrefix}/2024/09/03/00/