コンテンツにスキップ

Google Cloud Storageのクラウドデータ取り込み

このページでは、クラウドデータ取り込み (CDI) を使用してGoogle Cloud Storage (GCS) からBrazeにデータを同期するために必要な情報をすべて説明します。作成するGoogle Cloudリソース、Brazeでソースを接続して同期を作成する方法、各データタイプのファイル形式、GCS固有のトラブルシューティングについて取り上げます。

仕組み

Google Cloud Storageの統合は、スケジュールベースではなくイベント駆動型です。バケット内で新しいファイルが確定されると、GCSはOBJECT_FINALIZE通知をPub/Subトピックにパブリッシュします。BrazeはPub/Subサブスクリプションからこれらの通知を受け取り、新しいファイルを取り込みます。

この統合には、次のリソースが必要です。

  • データを保存するCloud Storageバケット
  • 新しいファイルの通知用のPub/Subトピックとサブスクリプション
  • Brazeがサポートされている認証方法のいずれかを通じてアクセスするサービスアカウント

GCPの用語の定義

用語 定義
Google Cloudプロジェクト プロジェクトはすべてのGoogle Cloudリソースを整理するもので、一意のプロジェクトIDとプロジェクト番号で識別されます。
Cloud Storageバケット バケットは、Brazeに取り込むデータファイルを保持するコンテナーです。
Pub/Subトピック トピックは、Cloud Storageバケットから新しいファイルの通知を受け取る名前付きリソースです。
Pub/Subサブスクリプション サブスクリプションはトピックに関連付けられ、そのメッセージを配信します。Brazeはpullサブスクリプションから新しいファイルの通知を受け取ります。
サービスアカウント サービスアカウントは、Brazeがバケットとサブスクリプションへのアクセスに使用する人間以外のIDです。BrazeはWorkload Identity Federationを通じてサービスアカウントの権限を借用するか、アップロードされたJSONキーを使用します。
Workload Identity Federation Workload Identity Federation (WIF) を使用すると、Brazeは有効期間の短いIDでサービスアカウントの権限を借用できるため、キーを作成またはアップロードする必要がありません。
IAMロール Identity and Access Management (IAM) ロールは、バケットとサブスクリプションに対してサービスアカウントに割り当てる権限の集合です。

Google Cloudでクラウドデータ取り込みを設定する

ステップ 1: Cloud Storageバケットを作成する

Google Cloudコンソールで、Cloud Storage > Buckets > Createに移動します。プロジェクトIDとバケット名を控えておいてください。これらはBrazeでソースを設定するときに必要になります。権限をIAMで管理できるように、均一なバケットレベルのアクセスを有効にすることをお勧めします。

ステップ 2: Pub/Subトピックとサブスクリプションを作成する

Google Cloudコンソールで、Pub/Sub > Topics > Create topicに移動します。Googleにデフォルトのサブスクリプションを作成させることも、別途作成することもできます。次に、そのトピックにpullサブスクリプションを作成します。

サブスクリプションIDを控えておいてください。同期を作成する際、Brazeにはトピックではなくサブスクリプションが必要です。サブスクリプションはpullサブスクリプションである必要があります。

ステップ 3: バケットの通知をトピックに送信する

まず、Cloud Storageサービスエージェントにトピックへのパブリッシュ権限を割り当ててから、OBJECT_FINALIZEの通知を作成します。OBJECT_FINALIZEイベントは、バケット内で新しいオブジェクトが作成または確定されるたびに発生します。




# Get the Cloud Storage service agent for your project
gcloud storage service-agent --project=YOUR-PROJECT-ID

# Assign it Pub/Sub Publisher on the topic
gcloud pubsub topics add-iam-policy-binding YOUR-TOPIC \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

# Create the OBJECT_FINALIZE notification (optionally scope to a folder with --object-prefix)
gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
  --topic=YOUR-TOPIC \
  --event-types=OBJECT_FINALIZE \
  --payload-format=json

YOUR-PROJECT-ID、YOUR-BUCKET-NAME、YOUR-TOPICを独自の値に置き換えてください。YOUR-PROJECT-NUMBERはサービスエージェントのメールアドレスに含まれる数値の識別子で、プロジェクトIDとは異なります。Google CloudコンソールのDashboardで確認するか、gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)"を実行してください。

ステップ 4: サービスアカウントを作成する

Google Cloudコンソールで、IAM & Admin > Service Accounts > Create service accountに移動します。この例では、アカウント名としてbraze-cdi-gcsを使用します。

ステップ 5: 権限を割り当てる

コネクターに必要な権限は、バケットに対するstorage.buckets.get、storage.objects.get、storage.objects.list、およびサブスクリプションに対するpubsub.subscriptions.consumeのみです。これらはカスタムロールまたは事前定義ロールのいずれかで割り当てることができます。

カスタムロール: これらの権限のみを持つカスタムロールを作成し、バケットとサブスクリプションにバインドします。




gcloud iam roles create brazeCdiGcs --project=YOUR-PROJECT-ID \
  --title="Braze CDI GCS" \
  --permissions=storage.buckets.get,storage.objects.get,storage.objects.list,pubsub.subscriptions.consume \
  --stage=GA

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

事前定義ロール: カスタムロールの代わりに、バケットにroles/storage.objectViewerとroles/storage.legacyBucketReaderを、サブスクリプションにroles/pubsub.subscriberを割り当てます。objectViewerロールはstorage.objects.getとstorage.objects.listを提供し、legacyBucketReaderはstorage.buckets.getを提供します。

ステップ 6: 認証を設定する

Brazeは、次のいずれかの認証方法でサービスアカウントにアクセスできます。

方法 Brazeによる認証方法 Brazeで入力する内容
Workload Identity Federation Braze impersonates your service account with a short-lived identity, so you don’t create or upload a key. Project number, Workload identity pool ID, Provider ID, and Service account email
Service account key Braze authenticates with a JSON key that you create for your service account. JSON key file for the service account

Workload Identity Federation

Workload Identity Federation（WIF）を使用すると、Brazeは自身のAWS環境からの短期間のIDでGoogle Cloudに認証し、Braze用に作成したサービスアカウントになりすまします。プロジェクトで、そのIDをワークスペースのみに信頼するよう設定します。サービスアカウントキーの作成や共有は不要です。

WIFの設定はGoogle Cloudプロジェクトごとに1回行います。1つのWIF認証情報がGoogle Cloud StorageとBigQueryの両方のソースに使用できます。BigQueryソースですでにこれらのステップを完了している場合は、既存のサービスアカウントにこのソースの権限を付与し、このセクションの残りはスキップしてください。

前提条件

Google Cloudコンソールでこれらのステップを完了するには、Workload Identity Poolを作成し、サービスアカウントおよびデータに対するIdentity and Access Management（IAM）ポリシーを管理する権限が必要です。たとえば、Workload Identity Pool Admin（roles/iam.workloadIdentityPoolAdmin）およびService Account Admin（roles/iam.serviceAccountAdmin）ロールを使用できます。

ワークスペースのプリンシパルのみを信頼する

同じBrazeインスタンス上のすべてのBrazeワークスペースは、同じAWSロールを使用します。あなた固有の値は、プリンシパルARNの末尾にあるセッション名（ワークスペースID）だけです。

GoogleのAWSプロバイダー向けデフォルト属性マッピングでは、aws_roleはセッション名を含まないロールARNに設定されます。そのため、principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARNのようにaws_roleの値に一致するIDにアクセス権を付与すると、あなたのワークスペースを含め、インスタンス上のすべてのBrazeワークスペースを信頼することになります。

データの範囲をあなたのワークスペースに限定するには、次のようにします。

  • subjectがBrazeプリンシパルARN全体と一致するIDにのみアクセス権を付与します。これはprincipal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARNプリンシパルです。
  • All identities in the poolや、aws_roleまたはaccountでフィルタリングされたIDにはアクセス権を付与しないでください。
  • AWSアカウントまたはロールのみをチェックする属性条件は記述しないでください。
  • google.subjectのデフォルト属性マッピング（assertion.arn）はそのままにしてください。

BrazeプリンシパルARNはワークスペースとBrazeインスタンスごとに異なります。また、BrazeはGoogleソースに対して、Snowflakeなど他のソースとは別のAWSロールを使用します。値は必ず、接続するワークスペースのBigQueryまたはGoogle Cloud Storageの認証情報フォームからコピーしてください。

BrazeプリンシパルARNをコピーする

BrazeでGoogle Cloud Storageソースの作成を開始し、認証方法としてWorkload Identity Federationを選択します。認証情報フォームのステップ1「Copy the Braze principal ARN」の値をコピーし、フォームは開いたままにしておきます。

フィールドにUnavailableと表示される場合、お使いのBrazeインスタンスではWIFを利用できません。代わりにサービスアカウントキーを使用してください。

必要なAPIを有効にする

Google CloudコンソールでAPIs & Services > Libraryに移動し、プロジェクトで次のAPIを有効にします。

  • IAM Service Account Credentials API
  • Security Token Service API
  • Identity and Access Management (IAM) API
Workload Identity Poolとプロバイダーを作成する
  1. IAM & Admin > Workload Identity Federationに移動し、Create poolを選択します。
  2. プールの名前（例: 「Braze CDI」）を入力します。Pool IDを控えてから、Continueを選択します。
  3. Select a providerでAWSを選択します。
  4. プロバイダー名（例: 「Braze AWS」）を入力し、Provider IDを控えます。
  5. AWS account IDに、BrazeプリンシパルARNのarn:aws:sts::に続く12桁の数字を入力し、Continueを選択します。
  6. Configure provider attributesで、google.subject = assertion.arnを含むデフォルトのマッピングをそのままにします。
  7. Saveを選択します。

プールIDとプロバイダーIDは4～32文字で、小文字、数字、ハイフンを使用する必要があります。

プロバイダーをプリンシパルに制限する（オプション）

多層防御のため、属性条件を追加して、プロバイダーがあなたのワークスペースのプリンシパルのみを受け入れるようにします。これにより、Googleはサービスアカウントの権限を確認する前に、トークン交換の段階で他のすべてのIDを拒否します。

  1. プール内でプロバイダーを選択し、Editを選択します。
  2. Attribute conditionsでAdd conditionを選択します。

  3. 次の条件を入力し、BRAZE_PRINCIPAL_ARNを認証情報フォームからコピーした値全体に置き換えます。

    


     assertion.arn == 'BRAZE_PRINCIPAL_ARN'
  4. Saveを選択します。

この条件により、プロバイダーは1つのBrazeワークスペース専用になります。別のワークスペースを接続するには、そのワークスペース用に別のプロバイダーを作成するか、assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN']のように両方のプリンシパルを列挙します。

Brazeプリンシパルをサービスアカウントにバインドする

ワークスペースのプリンシパルに、サービスアカウントになりすます権限を付与します。

  1. IAM & Admin > Workload Identity Federationに移動し、プールを選択します。
  2. Grant accessを選択し、Grant access using service account impersonationを選択します。
  3. Service accountで、Braze用に作成したサービスアカウントを選択します。
  4. Select principalsで、Only identities matching the filterを選択します。
  5. Attribute nameでsubjectを選択します。Attribute valueに、認証情報フォームからコピーしたBrazeプリンシパルARN全体を貼り付けます。
  6. Saveを選択します。Googleからクライアントライブラリー設定ファイルのダウンロードを促された場合は、Dismissを選択します。Brazeでは不要です。

これにより、サービスアカウントに対するWorkload Identity Userロール（roles/iam.workloadIdentityUser）が、次の形式のプリンシパルに付与されます。




principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN

確認するには、サービスアカウントを開いてPermissionsタブを選択します。Workload Identity Userロールに、BrazeプリンシパルARN全体で終わるこのプリンシパルが表示されているはずです。

このロールはサービスアカウントに対してのみ付与してください。プロジェクトレベルで付与すると、プリンシパルがプロジェクト内のすべてのサービスアカウントになりすませるようになります。

IAMの変更が反映されるまで数分かかる場合があります。アクセス権を付与した直後に接続テストが失敗した場合は、数分待ってから再試行してください。

サービスアカウントには、データへのアクセス権も必要です。このソースの権限を付与済みであることを確認してください。BigQueryとGoogle Cloud Storageの両方に1つの認証情報を使用する場合は、両方の権限セットを同じサービスアカウントに付与してください。

Brazeに値を入力する

Brazeの認証情報フォームに戻り、Google Cloudコンソールから取得した次の値を入力します。

Brazeのフィールド 確認場所
Project number コンソールのDashboardにあるProject infoカード。プロジェクトIDではなく、数値のプロジェクト番号を使用してください。
Workload identity pool ID 作成したプールのPool ID
Provider ID 作成したプロバイダーのProvider ID
Service account email Service AccountsページにあるサービスアカウントのEmail

Brazeはプロジェクト番号、プールID、プロバイダーIDを組み合わせてオーディエンスを作成します。これにより、Brazeからのリクエストをどのプロバイダーが検証するかがGoogleに伝えられます。デフォルトでは、プロバイダーは自身のリソース名をオーディエンスとして受け入れます。プロバイダーにカスタムの許可オーディエンスを設定している場合は、プロバイダーの完全なリソース名を含めてください。

Brazeによる接続テストの仕組み

Brazeで接続をテストすると、Brazeは設定があなたのワークスペースのみを信頼していることも確認します。テスト中、Brazeはすべてゼロのテスト用セッション名を使って、次の形式で同じ交換を試みます。




assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000

設定では、トークン交換の段階か、サービスアカウントへのなりすましを試みた段階のいずれかで、このIDを拒否する必要があります。両方のステップが成功した場合、設定がワークスペースのプリンシパル以外のIDを信頼しているため、テストは失敗します。修正方法については、設定がワークスペース以外のIDを信頼しているを参照してください。

オプションの属性条件を設定している場合、Googleはトークン交換の段階でテスト用IDを拒否します。設定していない場合は、そのIDがサービスアカウントへのなりすましを試みた段階でGoogleが拒否します。いずれの場合も、テストは成功します。

接続をテストするたびに、Google Cloudの監査ログにこの拒否された試行が記録されることがあります。これは想定どおりの動作です。この試行はBrazeのチェックによるもので、誰にもデータへのアクセス権を与えるものではありません。

このテストセッションのみを拒否する条件は追加しないでください。そのような条件ではテストに合格しても、設定は他のBrazeワークスペースを信頼したままになります。

Brazeのアクセス権を削除する

Brazeによるデータへのアクセスを停止するには、サービスアカウントのPermissionsタブからBrazeプリンシパルのWorkload Identity Userロールを削除するか、プロバイダーを削除します。

gcloud CLIで設定する

コマンドラインを使用する場合は、次のコマンドでAPIの有効化、プールとプロバイダーの作成、Brazeプリンシパルのサービスアカウントへのバインドを行えます。最初のブロックの値を置き換え、BrazeプリンシパルARNはコピーしたとおりに正確に貼り付けてください。




PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_EMAIL="YOUR-SERVICE-ACCOUNT-EMAIL"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"

PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"

gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
  --project="$PROJECT_ID"

gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="$PROJECT_ID" --location="global" --display-name="Braze CDI"

gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --account-id="$BRAZE_AWS_ACCOUNT_ID"

# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --project="$PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"

Service account key

Brazeはサービスアカウントの JSON キーを使用して認証します。既存のサービスアカウントキーの認証情報は引き続き機能するため、移行する必要はありません。

Google Cloud コンソールでサービスアカウントを開き、キー > 鍵を追加 > 新しい鍵を作成に移動して、JSON を選択します。キーファイルをダウンロードします。このファイルは、ソースを作成するときにBrazeにアップロードします。

または、gcloud を使用することもできます。




gcloud iam service-accounts keys create braze-cdi-key.json \
  --iam-account=SERVICE_ACCOUNT_EMAIL

SERVICE_ACCOUNT_EMAIL をサービスアカウントのメールアドレスに置き換えます。詳細については、Create and delete service account keys を参照してください。

Brazeでクラウドデータ取り込みを設定する

  1. Brazeでデータ設定 > クラウドデータ取り込み > ソースに移動し、データソースを追加を選択してから、Google Cloud Storageを選択します。

データソースのリストからGoogle Cloud Storageが選択された「新しいソースを追加」画面。

  1. ソースのフィールドに入力します。
    • バケット: バケット名
    • プロジェクト ID: GCPのプロジェクトID
    • 認証情報: 認証情報に名前を付け、ステップ 6で設定した認証方法を選択します。Workload Identity Federationの場合は、Project number, Workload identity pool ID, Provider ID, and Service account emailを入力します。 Service account keyの場合は、JSON key file for the service accountを入力します。

バケット、プロジェクトID、認証情報のアップロードフィールドが表示されたGoogle Cloud Storageのソースフォーム。

  1. 接続をテストを選択してから、ソースに接続を選択します。
  2. 同期を作成します。データ設定 > クラウドデータ取り込み > 同期に移動し、データ同期を作成を選択します。同期名とデータタイプ (ユーザー属性、カスタムイベント、購入イベント、カタログ、ユーザーを削除など) を選択してから、次へを選択します。
  3. データ定義ステップでGCSソースを選択し、次の項目を指定します。
    • Pub/Sub サブスクリプション ID: ステップ 2で控えたサブスクリプションID (トピックではありません)
    • フォルダーパス (オプション): バケット内のパスプレフィックス (共有バケット内のフォルダーを同期するを参照)

Pub/SubサブスクリプションIDとフォルダーパスのフィールドが表示されたGoogle Cloud Storageの同期フォーム。

  1. プレビューと検証を選択して、Brazeがサブスクリプションにアクセスし、取り込み可能なファイルを一覧表示できることを確認します。テストが成功するとバケット内の既存のファイルが一覧表示されますが、これらのファイルは自動的には同期されません。
  2. エラー通知の連絡先メールアドレスを追加します。Google Cloud Storageの同期はイベント駆動型のため、スケジュールは不要です。Brazeは新しいファイルがアップロードされると取り込みます。概要を確認してから、同期を作成を選択します。

共有バケット内のフォルダーを同期する

1つのバケットを複数の同期で再利用できますが、各同期は個別のフォルダーを対象とし、かつ専用のPub/Subサブスクリプションを持つ必要があります。

共有バケット内で同期するフォルダーごとに、次の手順を実行します。

  1. 同期のフォルダーフィールドにパスプレフィックス (例: attributes/) を設定します。Brazeは、パスがそのプレフィックスで始まるオブジェクトのみを一覧表示して取り込みます。

  2. そのフォルダー専用のトピックとプレフィックスで範囲指定された通知を作成してから、そのトピックにサブスクリプションを作成します。

    


     # One topic per folder
 gcloud pubsub topics create YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID

 # Assign the Cloud Storage service agent publisher on the topic
 gcloud pubsub topics add-iam-policy-binding YOUR-ATTRIBUTES-TOPIC \
   --project=YOUR-PROJECT-ID \
   --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
   --role="roles/pubsub.publisher"

 # Notification scoped to the folder with --object-prefix
 gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
   --topic=YOUR-ATTRIBUTES-TOPIC --event-types=OBJECT_FINALIZE \
   --payload-format=json --object-prefix=attributes/

 # One subscription per sync
 gcloud pubsub subscriptions create YOUR-ATTRIBUTES-SUBSCRIPTION \
   --topic=YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60

  3. ステップ 5と同様に、そのサブスクリプションに対するconsume権限をBrazeのサービスアカウントに割り当てます。

    


     gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \
   --project=YOUR-PROJECT-ID \
   --member="serviceAccount:[email protected]" \
   --role="roles/pubsub.subscriber"

    ステップ 5でカスタムロールを作成した場合は、代わりに--role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"を使用してください。

  4. Brazeで同期を作成する際に、このフォルダー用の新しいPub/Sub サブスクリプション IDとフォルダーパスを入力して、同期がそのフォルダーのファイルのみを取り込むようにします。

必要なファイル形式

Cloud Data Ingestionは、JSON、CSV、Parquet の各ファイルをサポートしています。必要な列はデータタイプによって異なります。Braze では、ファイルストレージプロバイダーが定める要件以外に、ファイル名に関する追加の要件はありません。ファイル名は一意にしてください。タイムスタンプを付加すると一意性を確保しやすくなります。

サポートされているすべてのファイルタイプの例については、braze-examples のサンプルファイルを参照してください。

同期するデータタイプのタブを選択してください。

各行には、ユーザー識別子を 1 つだけと PAYLOAD 列が必要です。ソースファイルには異なる識別子タイプの行を混在させることができますが、個々の行で使用する識別子は 1 つだけにしてください。

識別子 説明
EXTERNAL_ID 更新するユーザーを識別します。Braze で使用されている external_idの値と一致する必要があります。
ALIAS_NAME および ALIAS_LABEL この 2 つの列でユーザーエイリアスオブジェクトを作成します。alias_nameは一意の識別子である必要があり、alias_labelはエイリアスのタイプを指定します。ユーザーは異なるラベルを持つ複数のエイリアスを持つことができますが、alias_label ごとに alias_nameは 1 つだけです。
BRAZE_ID Braze のユーザー識別子です。これは Braze SDK によって生成されます。Cloud Data Ingestion では、Braze IDを使用して新しいユーザーを作成することはできません。新しいユーザーを作成するには、外部ユーザー ID またはユーザーエイリアスを指定してください。
EMAIL ユーザーのメールアドレスです。同じメールアドレスを持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。メールと電話番号の両方を含めた場合、Brazeはメールをプライマリ識別子として使用します。
PHONE ユーザーの電話番号です。同じ電話番号を持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。

PAYLOAD 列には、Braze のユーザーに同期するフィールドを ユーザー属性オブジェクトの形式に従って記述した JSON 文字列が含まれます。

JSON の例




{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}

CSV の例




external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"

カスタムイベントでは、ユーザー属性と同じユーザー識別子の列を使用します。PAYLOAD 列は イベントオブジェクトの形式に従います。




{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

購入イベントでは、ユーザー属性と同じユーザー識別子の列を使用します。PAYLOAD 列は 購入オブジェクトの形式に従います。




{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

カタログファイルでは、ユーザーデータファイルとは異なる識別子を使用します。カタログ同期を作成する前に、Braze で対象のカタログを作成してください。カタログのワークフロー全体については、カタログデータの同期と削除を参照してください。

列 必須 説明
ID はい カタログアイテムの一意の識別子です。Braze でアイテムを作成、更新、または削除するために使用されます。
PAYLOAD はい 同期するカタログのフィールドと値の JSON 文字列です。Braze のカタログのスキーマと一致する必要があります。
DELETED いいえ trueの場合、IDが一致するカタログアイテムが Braze のカタログから削除されます。作成または更新の操作では、この列を省略するか false に設定してください。

JSON の例

{"id":"85","payload":"{\"product_name\":\"Product 85\",\"price\":85.85}"}
{"id":"86","payload":"{\"product_name\":\"Product 86\",\"price\":86.86}"}
{"id":"1","payload":"{\"product_name\":\"Product 1\",\"price\":1.01}","deleted":true}

DELETED 列を含む CSV の例




ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
86,"{""product_name"": ""Product 86"", ""price"": 86.86}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

DELETED 列を含まない CSV の例




ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

キャンバストリガーは、ゼロコピーパーソナライゼーションを実現します。送信先キャンバスの設定と考慮事項については、ゼロコピーパーソナライゼーションを参照してください。

フィールド 必須 説明
EXTERNAL_ID はい。external_id、または alias_nameと alias_labelのいずれか 更新するユーザーを識別します。Braze で使用されている external_idの値と一致する必要があります。
ALIAS_NAME および ALIAS_LABEL はい。external_id、または alias_nameと alias_labelのいずれか この 2 つの列でユーザーエイリアスオブジェクトを作成します。alias_nameは一意の識別子である必要があり、alias_labelはエイリアスのタイプを指定します。ユーザーは異なるラベルを持つ複数のエイリアスを持つことができますが、alias_label ごとに alias_nameは 1 つだけです。
PROPERTIES はい キャンバスでパーソナライゼーションプロパティとして使用できるようにするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。

開始するには、新しい同期を作成する際に キャンバストリガー データタイプを選択します。

ソースバケット内のファイルを使用して Braze のユーザープロファイルを削除するには、次の手順に従います。

  1. 他の同期と同じ設定を使用して、新しい Cloud Data Ingestion 同期を作成します。
  2. Braze で同期を設定する際に、データタイプをユーザーを削除に設定します。
  3. ユーザー識別子の列のみを含むファイルをソースバケットにアップロードします。PAYLOAD 列は含めないでください。誤って削除されることを防ぐため、ペイロードが存在すると同期は失敗します。

ファイルの各行では、次のいずれかを使用して 1 人のユーザーのみを識別する必要があります。

識別子 説明
EXTERNAL_ID Braze で使用されている external_idと一致します。
ALIAS_NAME および ALIAS_LABEL 両方の列を組み合わせて、エイリアスでユーザーを識別します。
BRAZE_ID Brazeが生成したユーザー ID です (既存のユーザーのみ)。

JSON の例

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

CSV の例




external_id
user-to-delete-001
user-to-delete-002

同期が実行されると、Brazeはバケット内の新しいファイルを処理し、対応するユーザープロファイルを削除します。

カタログアイテムの削除

ファイルストレージを使用してカタログからアイテムを削除するには、以下の手順に従います。

  1. カタログデータの同期に使用しているものと同じ同期を使用します (データタイプは カタログ)。
  2. CSVファイルまたはJSONファイルに、オプションの deleted (または DELETED) 列を追加します。
  3. Brazeのカタログから削除したいカタログアイテムについて、deleted を true に設定します。

各行には引き続き ID と PAYLOAD が必要です。削除対象としてマークした行では、ペイロードは最小限でかまいません。Brazeは ID に基づいてアイテムを削除します。

同期が実行されると、deleted: true が設定された行に一致するカタログアイテムがBrazeで削除されます。カタログの同期と削除の動作の詳細については、カタログデータの同期と削除を参照してください。

知っておくべきこと

  • ソースバケットまたはコンテナーに追加するファイルは、512 MBを超えないようにしてください。この制限は、Amazon S3、Google Cloud Storage、Azure Blob Storageに適用されます。512 MBを超えるファイルはエラーとなり、Brazeに同期されません。Azure Blob Storage自体ははるかに大きなファイルを扱えますが、CDIはすべてのファイルストレージソースに同じ512 MBの制限を適用します。
  • ファイルあたりの行数に追加の制限はありませんが、同期の実行速度を向上させるため、Brazeでは小さいファイルの使用を推奨しています。たとえば、500 MBのファイル1つを取り込む場合は、100 MBのファイル5つを個別に取り込む場合よりも大幅に時間がかかります。
  • 一定期間内にアップロードできるファイル数に追加の制限はありません。
  • ファイル内およびファイル間の順序付けはサポートされていません。想定される競合をモニタリングしている場合、Brazeでは定期的に更新をバッチ処理することをおすすめします。
  • CDIは、同期の作成後に追加されたファイルのみを処理します。既存のファイルを使用して、Brazeがバケットにアクセスし、取り込むファイルを検出できることを検証できますが、それらのファイルはBrazeに同期されません。既存のファイルをCDIで処理するには、同期したいファイルをソースバケットに再アップロードしてください。

トラブルシューティング

ファイルのアップロードと処理

CDIは、同期の作成後にアップロードされたファイルのみを処理します。新しいオブジェクトごとに、Pub/SubトピックへのOBJECT_FINALIZEメッセージがトリガーされます。バケット内に既に存在するファイルを取り込むには、それらを再アップロードしてください。

予期しないファイルエラーへの対処

ファイルが取り込まれない場合は、次の点を確認してください。

  • バケットの通知が存在すること。gcloud storage buckets notifications list gs://YOUR-BUCKET-NAMEでバケットの通知を一覧表示します。
  • Cloud Storageサービスエージェントがトピックに対してroles/pubsub.publisherを持っていること。
  • Brazeのサービスアカウントがサブスクリプションに対するconsume権限 (カスタムロールまたはroles/pubsub.subscriberのいずれかで割り当てられたpubsub.subscriptions.consume) を持っていること。
  • サブスクリプションにデッドレターキューが設定されていないこと。Brazeは、クラウドデータ取り込みのサブスクリプションでデッドレターキューをサポートしていません。

詳しくは、Google CloudドキュメントのPub/Sub notifications for Cloud Storageを参照してください。

構成がワークスペース以外のIDを信頼している

Workload Identity Federationを使用している場合、接続テストが次のエラーで失敗することがあります。

Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.

これは、Brazeによる接続テストの仕組みで説明しているとおり、Googleがトークン交換とサービスアカウントのなりすましの両方でBrazeのテストIDを受け入れたことを意味します。このエラーは通常、サービスアカウントがプール内のすべてのID、またはaws_roleでフィルタリングされたIDにアクセス権を付与している場合に発生します。

このエラーを修正するには、次の手順を実行します。

  1. Google Cloudコンソールでサービスアカウントを開き、権限タブを選択します。
  2. principalSet://で始まり、プールを参照している Workload Identity User ロールを持つプリンシパルをすべて探します。それぞれからロールを削除します。
  3. Braze プリンシパルをサービスアカウントにバインドするで説明しているとおり、完全なプリンシパルにロールが付与されていることを確認します。
  4. IAM と管理 > IAM に移動し、プールに対するプロジェクトレベルの Workload Identity User の付与がないか確認します。ある場合は削除します。
  5. 接続を再度テストします。

あるいは、プロバイダーをプリンシパルに制限する (オプション)で説明しているとおり、プロバイダーの属性条件を完全なプリンシパルに制限することもできます。これにより、Googleはトークン交換の時点で他のすべてのIDを拒否します。ただし、アクセス権は完全なプリンシパルにのみ付与することを引き続きお勧めします。

プールがこのワークスペースのみを信頼していることをBrazeが確認できなかった

Workload Identity Federationを使用している場合、接続テストが次のエラーで失敗することがあります。

Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.

Brazeによる接続テストの仕組みで説明しているBrazeのチェックが結果に到達しませんでした。たとえば、ネットワークエラーやGoogle Cloudの一時的なエラーによってチェックが中断された場合です。このエラーは、構成の範囲が広すぎることを意味するものではありません。接続を再度テストしてください。エラーが続く場合は、Braze サポートにお問い合わせください。

Brazeがサービスアカウントになりすます際に権限が拒否される

Workload Identity Federationを使用していて、接続テストがiam.serviceAccounts.getAccessTokenの権限エラーで失敗する場合は、次の点を確認してください。

  • サービスアカウントの権限タブに、完全な Braze プリンシパル ARNで終わるプリンシパルに対する Workload Identity User ロールが表示されていること。このARNは、同じワークスペース内の BigQuery または Google Cloud Storage の認証情報フォームからコピーしたものである必要があります。
  • IAM Service Account Credentials APIが有効になっていること。
  • アクセス権を付与してから数分間待ったこと。

トークン交換が拒否される

Workload Identity Federationを使用していて、接続テストが Google Security Token Service のトークン交換で失敗する場合は、次の点を確認してください。

  • Brazeに入力したプロジェクト番号、プール ID、プロバイダー IDがGoogle Cloudの構成と一致していること。
  • プロバイダーの AWS アカウント IDが Braze プリンシパル ARN 内のアカウント IDと一致していること。
  • 属性条件を設定している場合、コピーしたとおりの完全なプリンシパル ARNが含まれていること。
  • カスタムの許可されたオーディエンスを設定している場合、プロバイダーの完全なリソース名が含まれていること。
  • プールとプロバイダーが有効になっていること。

不正な統合オブジェクトエラー

このエラーは、2つ以上のワークスペースに、同じクラウドストレージのバケットまたはフォルダーを参照する統合がある場合に発生します。各クラウドストレージの場所は、一度に1つの統合でしか使用できません。解決手順については、FAQを参照してください。

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!