Google BigQueryのクラウドデータ取り込み
このページでは、クラウドデータ取り込み (CDI) を使用して Google BigQuery から Braze にデータを同期するために必要なすべての情報を説明します。Google Cloud で作成するリソース、Braze でソースを接続して同期を作成する方法、データタイプごとのソーステーブル、BigQuery 固有のトラブルシューティングを取り上げます。
設定の概要
- BigQuery アカウントで、Braze に同期するテーブルまたはビューを設定します。
- サービスアカウントを作成し、同期するデータを含む BigQuery プロジェクトとデータセットへのアクセスを許可します。
- サポートされている認証方法のいずれかを使用して、Brazeがサービスアカウントにアクセスする方法を設定します。
- Braze ダッシュボードで新しいソースと同期を作成します。
- 統合を検証し、同期を開始します。
ステップ1: ソーステーブルを設定する
このセクションの手順では、PAYLOAD 列を持つテーブルを作成します。データ定義ステップでビジュアルを使用して列をマッピングする場合、またはSQL でクエリを記述する場合は、代わりに既存のテーブルまたはビューを使用できます。その場合はテーブル作成ステップをスキップし、同期するテーブルまたはビューへの読み取りアクセス権を Braze に付与してください。各オプションの比較については、データ定義オプションの選択を参照してください。
プロジェクト、データセット、テーブルには任意の名前を付けることができますが、列名は以下のタブの定義と一致させる必要があります。テーブルの代わりにビューまたはマテリアライズドビューを使用することもできます。
必要に応じて、ソーステーブルを格納する新しいプロジェクトまたはデータセットを設定します。
CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;
PAYLOAD 列を使用する場合、ソーステーブルまたはビューには、以下のタブに記載されていない列 (監査用やハッシュ用など) を含めることができます。Brazeはこれらのタブで説明されている列のみを読み取り、その他の列はクラウドデータ取り込みの同期では使用されません。
同期するデータタイプのタブを選択してください。
ユーザー属性、カスタムイベント、購入イベントはすべて同じ形式のソーステーブルを使用します。異なるのは PAYLOAD の内容のみです。
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id, alias_name and alias_label, or braze_id is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
--braze_id can only be used to update existing users created through the Braze SDK
braze_id STRING,
--If you include both email and phone, email is used as the primary identifier
email STRING,
phone STRING,
payload JSON
);
| フィールド名 | タイプ | モード |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
EMAIL |
STRING | NULLABLE |
PHONE |
STRING | NULLABLE |
UPDATED_AT- この行がテーブルで更新または追加された時刻です。Brazeは、UPDATED_ATが最後に同期された値より後の行を同期します。境界となるタイムスタンプとまったく同じ時刻の行は、新しい行が同じタイムスタンプを共有している場合、再同期されることがあります。- ユーザー識別子列 - テーブルには、1つ以上のユーザー識別子列を含めることができます。各行には識別子を1つだけ含めてください (
external_id、alias_nameとalias_labelの組み合わせ、braze_id、email、phoneのいずれか)。ソーステーブルには、1つ、2つ、3つ、4つ、または5つすべての識別子タイプの列を含めることができます。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- ユーザーのメールアドレスです。同じメールアドレスを持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。メールと電話番号の両方を含める場合は、メールがプライマリ識別子として使用されます。PHONE- ユーザーの電話番号です。同じ電話番号を持つプロファイルが複数存在する場合、最後に更新されたプロファイルが優先的に更新されます。
PAYLOAD- Brazeのユーザーに同期するフィールドの JSON 文字列です。
属性の同期では、PAYLOAD はユーザー属性オブジェクトの形式に従います。階層化カスタム属性、オブジェクトの配列、購読グループのステータスを含めることができます。ペイロードの例については、テーブルの設定を参照してください。
BigQueryのパーティショニング
CDIはBigQueryのパーティションをサポートしています。UPDATED_AT の関数でパーティション分割すると (データセットのサイズに応じて、日、週、時間などの粒度で)、BigQueryはスキャンする必要のあるデータを削減できます。これにより、非常に大きなテーブルのパフォーマンスと効率が向上します。
その他のフィールドではパーティション分割しないでください。さまざまな構成をテストして、データに最適な設定を見つけてください。
すべての CDI クエリは UPDATED_AT でフィルタリングしますが、この動作は変更される可能性があります。クエリにこの句を含めることを必要としないようにテーブルスキーマを設計してください。
詳細については、BigQueryのパーティショニングに関するドキュメントを参照してください。
カスタムイベントはユーザー属性と同じソーステーブルを使用します。User attributes タブに示されているテーブルを作成し、PAYLOAD にイベントオブジェクトを入力します。
イベントを同期するには、イベント名が必須です。time フィールドは ISO 8601 文字列、または yyyy-MM-dd'T'HH:mm:ss:SSSZ 形式で指定します。time フィールドがない場合、Brazeは UPDATED_AT 列の値をイベント時刻として使用します。app_id や properties などのその他のフィールドは任意です。
1行につき1つのイベントを同期できます。
{
"app_id" : "your-app-id",
"name" : "rented_movie",
"time" : "2013-07-16T19:20:45+01:00",
"properties": {
"movie": "The Sad Egg",
"director": "Alex Smith"
}
}
購入イベントはユーザー属性と同じソーステーブルを使用します。User attributes タブに示されているテーブルを作成し、PAYLOAD に購入オブジェクトを入力します。
購入イベントを同期するには、product_id、currency、price が必須です。任意の time フィールドは ISO 8601 文字列、または yyyy-MM-dd'T'HH:mm:ss:SSSZ 形式で指定します。time フィールドがない場合、Brazeは UPDATED_AT 列の値をイベント時刻として使用します。app_id、quantity、properties などのその他のフィールドは任意です。
1行につき1つの購入イベントを同期できます。
{
"app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
"product_id" : "Completed Order",
"currency" : "USD",
"price" : 219.98,
"time" : "2013-07-16T19:20:30+01:00",
"properties" : {
"products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
{ "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
]
}
}
カタログの同期を作成する前に、Braze で対象のカタログを作成してください。カタログのワークフロー全体については、カタログデータの同期と削除を参照してください。
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
id STRING,
payload JSON,
deleted BOOLEAN
);
| フィールド名 | タイプ | モード |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
ID |
STRING | REQUIRED |
DELETED |
BOOLEAN | OPTIONAL |
統合の名前は、Braze で作成したカタログの名前と完全に一致している必要があります。
同期が実行されるたびにソーステーブルが完全に更新されるように、カタログデータからビューを作成することをお勧めします。たとえば、product_id と3つの追加属性を含む商品データのテーブル (product_catalog_1) がある場合、次のビューを同期できます。
CREATE view IF NOT EXISTS BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS (SELECT
last_updated as UPDATED_AT,
product_id as ID,
TO_JSON(
STRUCT(
attribute_1,
attribute_2,
attribute_3,
)
) as PAYLOAD
FROM `BRAZE_CLOUD_PRODUCTION.INGESTION.product_catalog_1`);
キャンバストリガーはゼロコピーパーソナライゼーションを実現します。送信先キャンバスの設定と考慮事項については、ゼロコピーパーソナライゼーションを参照してください。
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id or alias_name and alias_label is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
properties JSON
);
| フィールド名 | タイプ | 必須 |
|---|---|---|
UPDATED_AT |
TIMESTAMP | はい |
PROPERTIES |
JSON | はい |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
キャンバストリガーの同期は、他のユーザーデータの同期と次の3点で異なります。
- external ID またはユーザーエイリアスの識別子のみがサポートされています。メールアドレスと電話番号は識別子としてサポートされていません。
- 同期できるのは既存の Braze ユーザーのみです。新しいユーザーを作成することはできません。
PAYLOAD列の代わりにPROPERTIES列を使用します。これは、パーソナライゼーション用のキャンバスエントリプロパティとして使用するフィールドの JSON 文字列です。
キャンバストリガーテーブルには、次の列が必要です。
UPDATED_AT- この行がテーブルで更新または追加された時刻です。Brazeは、UPDATED_ATが最後に同期された値よりも後の行を同期します。境界となるタイムスタンプとまったく同じタイムスタンプを持つ行は、新しい行が同じタイムスタンプを持つ場合に再同期されることがあります。- ユーザー識別子の列として、
EXTERNAL_ID、またはALIAS_NAMEとALIAS_LABELのいずれか。これらの列は、キャンバスメッセージングをトリガーする対象のユーザーを識別します。EXTERNAL_ID- キャンバスにエントリさせるユーザーを識別します。この値は、Brazeで使用されるexternal_idの値と一致する必要があります。ALIAS_NAMEとALIAS_LABEL- これらの列はユーザーエイリアスオブジェクトを作成します。alias_nameは一意の識別子である必要があり、alias_labelはエイリアスのタイプを指定します。ユーザーは異なるラベルを持つ複数のエイリアスを持つことができますが、1つのalias_labelにつきalias_nameは1つのみです。
PROPERTIES- キャンバスでパーソナライゼーションプロパティとして使用できるようにするフィールドの JSON 文字列です。ユーザー固有の情報を含める必要があります。
プロパティは、すべての行やユーザーに必須というわけではありません。ただし、プロパティの値は有効な JSON 文字列である必要があります。行にプロパティがない場合は、空の {} 文字列を入力してください。
開始するには、新しい同期を作成するときにキャンバストリガーデータタイプを選択します。
ユーザー削除用のソーステーブルには、1つ以上のユーザー識別子タイプと UPDATED_AT タイムスタンプを含める必要があります。ユーザー削除データでは、ペイロード列はサポートされていません。
UPDATED_AT- この行がテーブルで更新または追加された時刻です。Braze は、UPDATED_ATが最後に同期された値よりも後の行を同期します。新しい行が境界のタイムスタンプとまったく同じタイムスタンプを持つ場合、その境界タイムスタンプの行が再同期されることがあります。- ユーザー識別子列 - 各行には識別子を1つだけ含める必要があります。
external_id、alias_nameとalias_labelの組み合わせ、またはbraze_idのいずれかです。ソーステーブルには、1つ、2つ、または3つすべての識別子タイプの列を含めることができます。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 またはユーザーエイリアスを指定してください。
ユーザー削除用のテーブルには PAYLOAD 列を含めないでください。ユーザーが誤って完全に削除されるのを防ぐため、ソーステーブルにペイロード列が含まれている場合、同期は失敗します。その他の列は含めてもかまいませんが、Braze では無視されます。
次のフィールドを含むテーブルを作成します。
| フィールド名 | タイプ | モード |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
統合の実行時に適切なアクションが実行されるように、インポート同期を作成ページでデータタイプをユーザーを削除に設定します。詳細については、クラウドデータ取り込みでユーザーを削除するを参照してください。
ユーザープロファイルの削除は元に戻せません。削除アクションはユーザーを完全に削除するため、データに不一致が生じる可能性があります。詳細については、ユーザープロファイル削除の影響を参照してください。
ステップ2: サービスアカウントを作成して権限を付与する
Brazeがテーブルに接続してデータを読み取るために使用するサービスアカウントを GCP で作成します。サービスアカウントには次の権限が必要です。
- BigQuery Connection User: Brazeが接続を行えるようにします
- BigQuery User: クエリの実行、データセットのメタデータの読み取り、テーブルの一覧表示を行うためのアクセス権を Braze に付与します。
- BigQuery Data Viewer: データセットとその内容を表示するためのアクセス権を Braze に付与します。
- BigQuery Job User: ジョブを実行するためのアクセス権を Braze に付与します
ステップ3: 認証を設定する
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認証情報がBigQueryとGoogle Cloud Storageの両方のソースに使用できます。Google Cloud Storageソースですでにこれらのステップを完了している場合は、既存のサービスアカウントにこのソースの権限を付与し、このセクションの残りはスキップしてください。
前提条件
Google Cloudコンソールでこれらのステップを完了するには、Workload Identity Poolを作成し、サービスアカウントおよびデータに対するIdentity and Access Management（IAM）ポリシーを管理する権限が必要です。たとえば、Workload Identity Pool Admin（roles/iam.workloadIdentityPoolAdmin）およびService Account Admin（roles/iam.serviceAccountAdmin）ロールを使用できます。
ワークスペースのプリンシパルのみを信頼する
認証情報フォームに表示されるBrazeプリンシパルのAmazon Resource Name（ARN）全体に対してアクセス権を付与してください。BrazeのAWSロールやAWSアカウントにはアクセス権を付与しないでください。ロールレベルまたはアカウントレベルで付与すると、他のBraze顧客があなたのデータを読み取れるようになります。
同じ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でBigQueryソースの作成を開始し、認証方法として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とプロバイダーを作成する
- IAM & Admin > Workload Identity Federationに移動し、Create poolを選択します。
- プールの名前（例: 「Braze CDI」）を入力します。Pool IDを控えてから、Continueを選択します。
- Select a providerでAWSを選択します。
- プロバイダー名（例: 「Braze AWS」）を入力し、Provider IDを控えます。
- AWS account IDに、BrazeプリンシパルARNの
arn:aws:sts::に続く12桁の数字を入力し、Continueを選択します。 - Configure provider attributesで、
google.subject=assertion.arnを含むデフォルトのマッピングをそのままにします。 - Saveを選択します。
プールIDとプロバイダーIDは4～32文字で、小文字、数字、ハイフンを使用する必要があります。
プロバイダーをプリンシパルに制限する（オプション）
多層防御のため、属性条件を追加して、プロバイダーがあなたのワークスペースのプリンシパルのみを受け入れるようにします。これにより、Googleはサービスアカウントの権限を確認する前に、トークン交換の段階で他のすべてのIDを拒否します。
- プール内でプロバイダーを選択し、Editを選択します。
- Attribute conditionsでAdd conditionを選択します。
-
次の条件を入力し、
BRAZE_PRINCIPAL_ARNを認証情報フォームからコピーした値全体に置き換えます。assertion.arn == 'BRAZE_PRINCIPAL_ARN'
- Saveを選択します。
この条件により、プロバイダーは1つのBrazeワークスペース専用になります。別のワークスペースを接続するには、そのワークスペース用に別のプロバイダーを作成するか、assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN']のように両方のプリンシパルを列挙します。
Brazeプリンシパルをサービスアカウントにバインドする
ワークスペースのプリンシパルに、サービスアカウントになりすます権限を付与します。
- IAM & Admin > Workload Identity Federationに移動し、プールを選択します。
- Grant accessを選択し、Grant access using service account impersonationを選択します。
- Service accountで、Braze用に作成したサービスアカウントを選択します。
- Select principalsで、Only identities matching the filterを選択します。
- Attribute nameでsubjectを選択します。Attribute valueに、認証情報フォームからコピーしたBrazeプリンシパルARN全体を貼り付けます。
- 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全体で終わるこのプリンシパルが表示されているはずです。
All identities in the poolは選択せず、aws_roleでもフィルタリングしないでください。どちらも、同じAWSロールを共有するBrazeインスタンス上のすべてのBrazeワークスペースに一致します。詳細については、ワークスペースのプリンシパルのみを信頼するを参照してください。
このロールはサービスアカウントに対してのみ付与してください。プロジェクトレベルで付与すると、プリンシパルがプロジェクト内のすべてのサービスアカウントになりすませるようになります。
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 を参照してください。
ステップ4: BrazeのIPへのアクセスを許可する
ネットワークポリシーを設定している場合は、BigQuery インスタンスへのネットワークアクセスを Braze に許可する必要があります。Braze ダッシュボードのリージョンに対応する次の IP からのアクセスを許可してください。
インスタンスUS-01、US-02、US-03、US-04、US-05、US-06、US-07の場合、関連するIPアドレスは次のとおりです。
23.21.118.19134.206.23.17350.16.249.952.4.160.21454.87.8.3454.156.35.25152.54.89.23818.205.178.15
インスタンスUS-08の場合、関連するIPアドレスは次のとおりです。
52.151.246.5152.170.163.18240.76.166.15740.76.166.17040.76.166.16740.76.166.16140.76.166.15640.76.166.16640.76.166.16040.88.51.7452.154.67.1740.76.166.8040.76.166.8440.76.166.8540.76.166.8140.76.166.7140.76.166.14440.76.166.145
インスタンスUS-10の場合、関連するIPアドレスは次のとおりです。
100.25.232.16435.168.86.17952.7.44.1173.92.153.1835.172.3.12950.19.162.19
インスタンスEU-01とEU-02の場合、関連するIPアドレスは次のとおりです。
52.58.142.24252.29.193.12135.158.29.22818.157.135.973.123.166.463.64.27.363.65.88.253.68.144.1883.70.107.88
インスタンスAU-01の場合、関連するIPアドレスは次のとおりです。
13.210.1.14513.211.70.15913.238.45.5452.65.73.16754.153.242.23954.206.45.213
インスタンスID-01の場合、関連するIPアドレスは次のとおりです。
108.136.157.246108.137.30.20716.78.128.7116.78.14.13416.78.162.20843.218.73.35
インスタンスJP-01の場合、関連するIPアドレスは次のとおりです。
13.159.155.21254.199.221.24113.192.23.1654.250.120.13918.181.114.2323.114.38.100
インスタンスKR-01の場合、関連するIPアドレスは次のとおりです。
43.200.215.452.79.67.17552.79.113.603.34.212.9254.116.134.2313.37.197.225
ステップ5: Braze ダッシュボードで新しいソースを作成する
Braze ダッシュボードで、データ設定 > クラウドデータ取り込み > ソースに移動し、データソースを追加を選択してから、Google BigQueryを選択します。
ステップ5.1: BigQueryの接続情報とソーステーブルを追加する
ソースの名前を入力し、BigQueryの認証情報と構成を入力します。
- 認証情報名には、Braze でこの認証情報を識別しやすいラベルを入力します。
- 認証方法には、ステップ3で設定した方法を選択し、その認証情報を入力します。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を入力します。
次に、残りの構成フィールドを入力します。
ステップ5.2: 接続をテストしてソースに接続する
次に、接続をテストを選択します。成功したら、残りの設定を完了し、ソースに接続をクリックします。接続に失敗した場合は、問題のトラブルシューティングに役立つエラーメッセージが表示されます。
ステップ6: Braze ダッシュボードで新しい同期を作成する
データ設定 > クラウドデータ取り込み > 同期に移動し、データ同期を作成を選択します。
同期の詳細を構成してデータを定義する
同期の名前を入力します。次に、アクティブなソースと同期データタイプを選択します。続いて、ビジュアルまたはテーブルを選択してソーステーブルを入力するか、SQLを選択してカスタム SQL クエリを記述します。最後に、プレビューと検証を選択します。
検証が成功すると、データのプレビューが表示されます。次へ: 通知を選択して続行します。検証に失敗した場合は、問題のトラブルシューティングに役立つエラーメッセージが表示されます。
次のステップに進むには、同期の検証が成功している必要があります。同期の作成ページを閉じる必要がある場合は、下書きとして保存を選択して作業内容を保存してください。
通知設定を追加する
同期エラー通知を受け取る連絡先メールアドレスを入力します。Brazeはこの連絡先情報を使用して、テーブルアクセスの予期しない喪失などの統合エラーに関する通知を送信します。
連絡先メールアドレスには、テーブルの欠落や権限の問題など、グローバルエラーまたは同期レベルのエラーの通知のみが送信されます。行レベルの問題は通知されません。グローバルエラーは、同期の実行を妨げる接続上の重大な問題を示しています。
このような問題には、次のようなものがあります。
- 接続の問題
- リソースの不足
- 権限の問題
- カタログ階層の容量不足 (カタログ同期のみ)
スケジュールを設定する
最後に、同期を非定期または定期として設定します。
非定期の同期は、ダッシュボードで 今すぐ同期 を選択するか、同期をトリガーするエンドポイントを呼び出したときにのみ実行されます。
定期的な同期は、最短で5分ごと、最長で月1回の間隔で実行できます。デフォルトでは、ダッシュボードで設定できる最短の間隔は15分です。これにより、ウェアハウスのコンピューティングコストとリクエスト量を管理しやすくなります。最短5分ごとに同期するには、Brazeサポートまたはカスタマーサクセスマネージャーにお問い合わせください。Brazeは定期的な同期をUTCでスケジュールします。
統合を下書きからアクティブ状態に移行するには、統合の検証が成功している必要があります。作成ページを閉じても統合は保存されるため、詳細ページに戻って変更を加え、検証することができます。
同期を実行する
アクティブ化されると、同期は設定時に構成したスケジュールで実行されます。スケジュール外で同期を実行したい場合や、最新のデータを取得したい場合は、今すぐ同期を選択します。この実行は、今後の定期的なスケジュールされた同期には影響しません。データの更新時に同期を自動的に開始するには、パイプラインから同期のトリガーエンドポイントを呼び出します。
追加の統合またはユーザーを設定する (任意)
Braze では複数の統合を設定できます。追加の同期を作成する際、同じ BigQuery アカウントに接続する場合は既存の認証情報を再利用できます。
複数の統合で同じユーザーを再利用する場合、すべてのアクティブな同期からそのユーザーが削除されるまで、Braze ダッシュボードでユーザーを削除することはできません。
BigQueryを接続されたソースとして使用する
接続されたソースは、Braze にデータを同期する代わりとなるゼロコピーの手段です。Brazeは基盤となるデータをコピーせずに、BigQuery インスタンスに直接クエリを実行して CDI セグメントを構築します。概念、制限事項、コストへの影響については、接続されたソースを参照してください。
ステップ1: サービスアカウントを作成して権限を付与する
Brazeがテーブルに接続してデータを読み取るために使用するサービスアカウントを GCP で作成します。サービスアカウントには次の権限が必要です。
- BigQuery Connection User: Brazeが接続を行えるようにします。
- BigQuery User: クエリの実行、データセットのメタデータの読み取り、テーブルの一覧表示を行うためのアクセス権を Braze に付与します。
- BigQuery Data Viewer: データセットとその内容を表示するためのアクセス権を Braze に付与します。
- BigQuery Job User: ジョブを実行するためのアクセス権を Braze に付与します。
- bigquery.tables.create: セグメントの更新中に一時テーブルを作成するためのアクセス権を Braze に付与します。
このサービスアカウントは、CDI セグメントエクステンションで使用可能なテーブルの一覧を生成するため、およびソーステーブルにクエリを実行して新しいセグメントを作成するために使用されます。接続されたソースが作成されると、Brazeはソーススキーマ内でユーザーが使用できるすべてのテーブルの名前と説明を検出します。
データセット内のすべてのテーブルへのアクセス権を付与することも、特定のテーブルにのみ権限を付与することもできます。Brazeのロールがアクセスできるテーブルはすべて、CDI セグメントエクステンションでクエリを実行できます。
create table 権限は、Braze でセグメントを更新する前に、BrazeがCDI セグメントエクステンションのクエリ結果を含むテーブルを作成するために必要です。Brazeはセグメントごとに一時テーブルを作成し、そのテーブルはBrazeがセグメントを更新している間のみ保持されます。
サービスアカウントを作成して権限を付与したら、ステップ3: 認証を設定するのいずれかの方法で、Brazeがサービスアカウントにアクセスする方法を設定します。このプロジェクトで Workload Identity Federationをすでに設定している場合は、それを再利用できます。既存のサービスアカウントに、このステップの権限を付与してください。
ネットワークアクセスの設定はステップ4と同じです。
ステップ2: Braze で接続されたソースを作成する
データ設定 > クラウドデータ取り込み > 接続されたソースに移動し、データソースを追加を選択してから、Google BigQueryを選択します。
ソースを設定で、次の情報を入力します。
- 認証情報: 認証情報名と、使用する認証方法のフィールド。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を入力します。
- 構成: プロジェクトとデータセット
接続されたソースの名前を選択します。この名前は、新しい CDI セグメントエクステンションを作成するときに、使用可能なソースの一覧で使用されます。
このソースの最大実行時間を構成します。Brazeは、最大実行時間を超えたクエリを自動的に中止します。許可される最大実行時間は60分です。実行時間を短くすると、BigQuery アカウントで発生するコストを削減できます。この設定は、このソースを使用する同期や CDI セグメントエクステンションなど、このソースを通じて実行されるクエリに適用されます。
接続をテストを選択して、ユーザーに表示されるテーブルの一覧が想定どおりであることを確認し、完了を選択します。これで接続されたソースが作成され、CDI セグメントエクステンションで使用できるようになります。
Braze では複数の接続されたソースを設定できますが、各ソースはそれぞれ異なるデータセットに接続するように構成する必要があります。追加のソースを作成する際、同じ BigQuery アカウントに接続する場合は既存の認証情報を再利用できます。
既存の列からペイロードをフォーマットする
内部で各属性をそれぞれ独自の列に保存したい場合は、Braze との同期にデータを入力するために、それらの列を JSON 文字列に変換する必要があります。BigQuery で次のクエリを使用して、ソース列を CDI フィールドにフォーマットします。
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
attribute_2 STRING,
attribute_3 NUMERIC,
my_user_id STRING);
SELECT
CURRENT_TIMESTAMP as UPDATED_AT,
my_user_id as EXTERNAL_ID,
TO_JSON(
STRUCT(
'attribute_1' AS attribute_1,
'attribute_2'AS attribute_2,
'yet_another_attribute'AS attribute_3
)
) as PAYLOAD
FROM BRAZE.EXAMPLE_USER_DATA;
最適化に関するその他のガイダンスについては、クラウドデータ取り込みのベストプラクティスを参照してください。
トラブルシューティング
接続テストの実行が遅い
接続テストはデータウェアハウス上で実行されるため、ウェアハウスの容量を増やすと速度が向上する場合があります。サーバーレス SQL インスタンスを使用すると、ウォームアップ時間が最小限に抑えられ、クエリのスループットが向上しますが、統合のコストがわずかに高くなる可能性があります。
ユーザーにテーブルへのクエリ権限がない
このエラーが表示された場合は、テーブルにクエリを実行するためのユーザー権限を追加してください。
使用量がカスタム割り当てを超えた
このエラーが表示された場合、現在のペースで同期を続行できるように割り当てを更新する必要があります。
テーブルがロケーション {region} で見つからない
このエラーが表示された場合は、テーブルが正しいプロジェクトとデータセットにあることを確認してください。
無効な JWT 署名
このエラーが表示された場合は、アカウントで BigQuery API サービスが有効になっていることを確認してください。
構成がワークスペース以外の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にアクセス権を付与している場合に発生します。
このエラーを修正するには、次の手順を実行します。
- Google Cloudコンソールでサービスアカウントを開き、権限タブを選択します。
principalSet://で始まり、プールを参照している Workload Identity User ロールを持つプリンシパルをすべて探します。それぞれからロールを削除します。- Braze プリンシパルをサービスアカウントにバインドするで説明しているとおり、完全なプリンシパルにロールが付与されていることを確認します。
- IAM と管理 > IAM に移動し、プールに対するプロジェクトレベルの Workload Identity User の付与がないか確認します。ある場合は削除します。
- 接続を再度テストします。
あるいは、プロバイダーをプリンシパルに制限する (オプション)で説明しているとおり、プロバイダーの属性条件を完全なプリンシパルに制限することもできます。これにより、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が含まれていること。
- カスタムの許可されたオーディエンスを設定している場合、プロバイダーの完全なリソース名が含まれていること。
- プールとプロバイダーが有効になっていること。
SQL チェックの実行場所
検証チェックは、CDI 統合で使用しているのと同じテーブルまたはビューに対して、BigQuery StudioのSQL ワークスペースで直接実行してください。詳細については、BigQuery Studio introductionを参照してください。
関連ページ
- 必須の列とペイロードの形式については、テーブルの設定を参照してください。
- 同期のスケジュール設定とデータポイントの効率化については、ベストプラクティスを参照してください。
- 同期実行のモニタリングについては、同期ログとオブザーバビリティを参照してください。
- すべてのソースに共通する質問については、よくある質問を参照してください。