このページはAIにより自動翻訳されており、不正確な内容が含まれている可能性があります。翻訳の誤りを報告するには、ページ右側の目次の下にあるフィードバックをご利用ください。

クラウドデータ取り込み: SQLエディター

このページでは、Brazeのクラウドデータ取り込み（CDI）SQLエディターを使用して、SQLクエリで同期を作成および検証する方法について説明します。

クラウドデータ取り込みのSQLエディターを使用すると、データウェアハウスに対してSQLクエリを直接記述して同期を作成できます。これにより、以前はデータウェアハウス統合のステップ1.1で必要だった専用のCDIテーブルを作成したり維持したりする必要がなくなります。

SQLエディターは、次のような場合に使用します。

アップストリームのテーブルを変更せずにデータを同期したい場合
データウェアハウス内の生データを扱いたい場合
PAYLOADカラムの構築を避けたい場合
SQLを使用してより複雑なデータのユースケースに対応したい場合

前提条件と制限事項

SQL エディターには次の制限事項があります。

データウェアハウスソースでのみ使用できます: Snowflake、Redshift、BigQuery、Databricks、Fabric。
単一ステートメントの読み取り専用クエリのみがサポートされています。

注

Braze はお客様のデータに対して読み取り専用クエリのみを実行し、基盤となるテーブルを変更することはありません。クエリの実行中に一時オブジェクトが作成される場合がありますが、それらは保持されません。

新しい SQL Editor 同期を作成する

以下の手順に従って、まずソースを作成し、次に SQL Editor で同期を作成します。CDI 用のソースをすでに設定している場合は、ステップ 3 に進んでください。

注

これらの手順では、Snowflake ソースを例として使用しています。他のデータウェアハウスソースの設定手順もほぼ同じです。詳しくは、データウェアハウス統合の設定ドキュメントのステップ 2: Braze ダッシュボードで新しいソースを作成するを参照してください。

ステップ 1: Snowflake のロール、権限、ウェアハウス、ユーザーを設定する

CDI で Snowflake ソースを作成する前に、Braze が使用する Snowflake ユーザーが、クエリ対象のデータと、クエリを実行するウェアハウスにアクセスできることを確認してください。

ステップ 1.1: (オプション) データベースとスキーマを作成する

必要に応じて、CDI データ専用のデータベースとスキーマを作成します。

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

ステップ 1.2: ロールとデータベースの権限を設定する

同期するテーブルへのアクセス権を付与します。

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.MY_USER_TABLE TO ROLE BRAZE_INGESTION_ROLE;

ユースケースに応じて、複数のテーブルや今後作成されるテーブルへのアクセス権を付与することもできます。たとえば、スキーマ内で今後作成されるすべてのテーブルへのアクセス権を付与するには、次のようにします。

GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

ステップ 1.3: ウェアハウスを設定し、Braze ロールにアクセス権を付与する

Braze がクエリを実行するためのウェアハウスを作成します。

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

注

ウェアハウスでは自動再開フラグを有効にしておく必要があります。有効にしない場合は、クエリ実行時に Braze がウェアハウスを起動できるよう、ウェアハウスに対する追加の OPERATE 権限を Braze に付与してください。

ステップ 1.4: Snowflake ユーザーを作成する

Braze は、Workload Identity Federation または RSA キーペアのいずれかを使用して Snowflake に認証します。既存の RSA キーペアの認証情報は引き続き使用でき、移行する必要はありません。いずれか一方の方法に従ってください。このユーザーは、Braze で Snowflake ソースを設定する際に使用します。

workload identity federation
key pair

ステップ 1.2 とステップ 1.3 のロールとウェアハウスの権限付与を使用します。Snowflake の認証情報フォームからサービスユーザーを作成し、そのステートメントを Snowflake ワークシートで実行します。このユーザーは TYPE = SERVICE で、パスワードも RSA キーもありません。Snowflake アカウントでネットワークポリシーを使用している場合は、ステップ 1.5: Snowflake ネットワークポリシーで Braze の IP を許可する (オプション) の説明に従って Braze の IP アドレスを許可してください。ステートメントの内容と実行場所については、Workload Identity Federation 用に Snowflake を設定するを参照してください。

Braze 用のユーザーを作成し、ロールを割り当てます。

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

ステップ 2: Braze ダッシュボードで新しいソースを作成する

このステップでは、Braze で Snowflake ソースを作成し、接続を検証します。

ステップ 2.1: Snowflake ソースを追加する

Braze ダッシュボードで、データ設定 > クラウドデータ取り込み > ソースに移動します。
データソースを追加を選択します。
Snowflake を選択します。

ステップ 2.2: 接続の詳細を入力する

ソースの名前を決め、Snowflake の認証情報と設定を入力します。

注

Snowflake アカウントロケーターフィールドには、Snowflake のアカウント識別子を入力します。これは通常 xy12345.us-east-1.aws のような形式です。データベース名やウェアハウス名とは異なります。

ステップ 2.3: 認証を完了する

ステップ 1.4 で作成したユーザーに合わせて、Workload Identity Federation またはキーペアを選択します。

workload identity federation
key pair

アカウントロケーター、ユーザー名、ロールを入力します。ステートメントをコピーが利用可能になったら選択し、そのステートメントを Snowflake ワークシートで実行してから、認証情報を保存を選択します。ステートメントについては、Workload Identity Federation 用に Snowflake を設定するを参照してください。

認証情報と設定を入力したら、認証情報を保存を選択して RSA キーを生成します。次に Snowflake に戻って設定を完了します。ダッシュボードに表示された公開キーを、Braze が Snowflake に接続するために作成したユーザーに追加します。

詳しくは、Snowflake key-pair authentication を参照してください。キーをローテーションしたい場合は、いつでも Braze で新しいキーペアを生成し、新しい公開キーを提供できます。

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

Braze に戻り、接続をテストを選択してソースへのアクセスを確認してから、ソースを作成します。

ステップ 3: 新しい同期を作成し、SQL クエリを記述する

データ設定 > クラウドデータ取り込み > 同期に移動します。
データ同期を作成を選択します。
データタイプで任意の同期を選択します。
ステップ 2 で作成したソースを参照します。
SQL を選択し、ウェアハウスからユーザーデータを返す SQL クエリを記述します。SQL クエリによって、Braze に同期されるデータが決まります。クエリ結果が同期のスキーマになります。

ソースエクスプローラーを使用して同期元として利用可能なテーブルやビューを参照したり、AI SQL ジェネレーターを使用して SQL クエリについて Braze Operator のサポートを受けたりできます。

注

サポートされるのは、JOIN 句を含む読み取り専用のクエリのみです。詳しくは、SQL の制約を参照してください。

ステップ 4: クエリをプレビューして検証する

プレビューして検証を選択してクエリを実行します。

プレビューでは次のようになります。

結果がテーブル形式で表示されます
最大 100 行が表示されます
最大 250 列が表示されます

検証に成功するには、SQL クエリが次の必須列を返す必要があります。

同期データタイプ	必須列
属性	- ユーザー識別子 (`external_id`、`braze_id`、`alias_name` と `alias_label`、メールアドレス、電話番号のいずれか)。 - `UPDATED_AT`。 - 同期する追加の列 (属性) を少なくとも 1 つ。
ユーザーの削除	- ユーザー識別子 (`external_id`、`braze_id`、`alias_name` と `alias_label`、メールアドレス、電話番号のいずれか)。 - `UPDATED_AT`。
キャンバストリガー	- ユーザー識別子 (`external_id`、`braze_id`、`alias_name` と `alias_label`、メールアドレス、電話番号のいずれか)。 - `UPDATED_AT`。
カスタムイベント	- ユーザー識別子 (`external_id`、`braze_id`、`alias_name` と `alias_label`、メールアドレス、電話番号のいずれか)。 - `UPDATED_AT`。 - イベント名を表す `NAME`。 - イベント時刻を表す `TIME`。利用できない場合、CDI は代わりに `UPDATED_AT` を使用します。
購入イベント	- ユーザー識別子 (`external_id`、`braze_id`、`alias_name` と `alias_label`、メールアドレス、電話番号のいずれか)。 - `UPDATED_AT`。 - `PRODUCT_ID`。 - `CURRENCY`。 - `PRICE`。 - 購入イベントの時刻を表す `TIME`。利用できない場合、CDI は代わりに `UPDATED_AT` を使用します。
カタログ	- カタログアイテムの識別子を表す `ID`。 - `UPDATED_AT`。 - 同期する追加の列 (カタログフィールド) を少なくとも 1 つ。
アカウント	- アカウント識別子を表す `ID`。 - アカウント名を表す `NAME`。 - `UPDATED_AT`。 - 同期する追加の列 (アカウントフィールド) を少なくとも 1 つ。

必須列以外の追加の列は、それぞれ属性、キャンバスコンテキストプロパティ、イベントプロパティ、カタログフィールド、アカウントフィールドとして同期されます。プレビューと検証のエラーとその修正方法に関するヒントについては、検証の動作とトラブルシューティングを参照してください。

ステップ 5: 属性マッピングを確認して同期を作成する

検証が成功したら、次へ: 通知に進み、同期を作成します。

重要

SQL の設定が不正確だと、データポイントの過剰消費やより広範な運用上のリスクなど、意図しない結果につながる可能性があります。クエリロジックが正しいことを確認する責任はお客様にあります。同期を有効にする前に、すべての結果を慎重にプレビューしてください。

SQLの制約

`SELECT`クエリのみを使用する

読み取り専用クエリのみがサポートされています。

使用できるもの：

SELECT
WITH（CTE）
JOIN

使用できないもの：

INSERT、UPDATE、またはDELETE
CREATEまたはDROP
;で区切られた複数のステートメント

単一のステートメントを使用する

クエリは単一の実行可能なステートメントである必要があります。

検証の動作

SQLエディターは、続行を許可する前にクエリを検証します。

SQLエラー

クエリに構文エラーが含まれている場合：

検証が失敗します
プレビューは表示されません
データウェアハウスからエラーメッセージが返されます

コンパイルエラー

クエリが無効なテーブル、カラム、または権限のないオブジェクトを参照している場合：

検証が失敗します
プレビューは表示されません
データウェアハウスからエラーメッセージが返されます

接続エラー

Brazeがデータウェアハウスに接続できない場合：

検証が失敗します
プレビューは表示されません
接続エラーメッセージが表示されます

クエリタイムアウト

クエリの実行時間が長すぎる場合：

Brazeがクエリを終了します
検証が失敗します
タイムアウトエラーが表示されます

テーブルスキーマエラー

クエリがコンパイルされても、以下の場合は検証が失敗する可能性があります。

識別子カラムが見つからない
UPDATED_ATが欠落している
その他の必須カラムが欠落している

この場合、検証の成功に向けて役立つよう、プレビューは引き続き表示されます。各同期データタイプの必須カラムの詳細については、前のセクションのステップ4を参照してください。

ゼロ行の結果

クエリがゼロ行を返す場合：

検証は合格します
同期を作成できます
行が返されるまでユーザーは更新されません

PAYLOAD のサポート（レガシー）

SQL エディターは、PAYLOAD 列が存在するレガシー CDI テーブルをサポートしています。

クエリに以下が含まれている場合:

有効な識別子
UPDATED_AT
PAYLOAD 列
追加の列

次のように処理されます:

Braze は PAYLOAD 列のみを同期します
Braze は追加の列を無視します

SQL 同期を編集する

既存の同期を編集する場合:

SQL を変更した場合は、必ず再検証が必要です
無効な変更は保存できません
有効な変更は保存後に反映されます

同期の実行がすでに進行中の場合、変更は次回の実行から反映されます。

トラブルシューティング

このセクションでは、一般的なエラーとそのトラブルシューティング方法について説明します。

「プレビューを利用できません」

「プレビューを利用できません」と表示された場合、以下のいずれかのエラータイプが原因である可能性があります。

エラータイプ	解決手順
「プレビューを利用できません」	エラーバナーのヒントを確認してください。
「ソースに接続できません」	設定されたユーザー名、アカウントロケーター、認証方法を確認してください。キーペアの場合は、RSA公開キーがSnowflakeユーザーに設定されていることを確認してください。 Workload Identity Federationの場合は、認証情報フォームのステートメントを実行したことを確認してください。ウェアハウスが実行中であることを確認してください。ネットワークアクセスを確認してください。
「SQL構文エラー」	SQL構文を確認してください。
「オブジェクトが存在しないか、権限がありません」	ロールがテーブルに対する`SELECT`アクセス権を持っていることを確認してください。データベースとスキーマの権限を確認してください。テーブル名のタイプミスを確認してください。

「識別子カラムが必要です」

クエリにexternal_idなどの有効な識別子が含まれていることを確認してください。

「`UPDATED_AT`カラムがありません」

増分同期用のタイムスタンプカラムを追加してください。

「カラムを追加してください…同期する属性/カタログフィールド/アカウントフィールドがありません」

識別子とUPDATED_AT以外に、少なくとも1つの追加カラムを追加してください。

「クエリの実行がタイムアウトしました」

クエリを最適化するか、より大きなウェアハウスを使用してください。

New Stuff!