Salesforce Data Cloud でフェデレーションクエリを実行する

[アーティクル]
09/17/2024

この記事では、Azure Databricks で管理されていない Salesforce Data Cloud データに対してフェデレーションクエリを実行するように、Lakehouse フェデレーションを設定する方法について説明します。 Lakehouse フェデレーションの詳細については、「Lakehouse フェデレーションとは?」を参照してください。

Lakehouse フェデレーションを使用して Salesforce Data Cloud データベースに接続するには、Azure Databricks の Unity Catalog メタストアに次のものを作成する必要があります。

Salesforce Data Cloud データベースへの "接続"。
Unity Catalog に Salesforce Data Cloud データベースをミラーリングする "外部カタログ"。これにより、Unity Catalog のクエリ構文とデータガバナンスツールを使用して、Azure Databricks ユーザーによるデータベースへのアクセスを管理できるようになります。

開始する前に

ワークスペースの要件:

Unity Catalog を使用できるワークスペース。

コンピューティングの要件:

Databricks Runtime クラスターまたは SQL ウェアハウスから対象となるデータベースシステムに接続するためのネットワーク接続。「レイクハウスフェデレーションのためのネットワークに関する推奨事項」を参照してください。
Azure Databricks クラスターでは、Databricks Runtime 15.2 以降と、共有またはシングルユーザーアクセスモードを使用する必要があります。
SQL ウェアハウスは Pro またはサーバーレスである必要があり、2024.30 以降を使用する必要があります。

必要なアクセス許可:

接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされている Unity Catalog メタストアに対する CREATE CONNECTION 特権を持つユーザーである必要があります。
外部カタログを作成するには、メタストアに対する CREATE CATALOG 権限を持ち、接続の所有者であるか、接続に対する CREATE FOREIGN CATALOG 特権を持っている必要があります。

追加の権限要件は、以下の各タスクベースのセクションで規定されています。

Salesforce 接続アプリを作成する

Salesforce 接続アプリを使用すると、API と標準プロトコルを使用して外部アプリを Salesforce と統合できます。このセクションでは、SSO を使用して接続アプリを作成し、Databricks が Salesforce で認証できるようにする方法について説明します。

Note

詳細な手順については、Salesforce Data Cloud のドキュメントの「接続アプリを作成する」を参照してください。

Salesforce 接続アプリを作成するには、次の手順を行います。

Data Cloud の右上にある [セットアップ] をクリックします。
[プラットフォームツール] で、[アプリケーション] > [アプリケーションマネージャー] の順にクリックします。
[新しい接続アプリ] をクリックします。
名前と連絡先のメールアドレスを入力します。
OAuth の設定 を有効にします。
1. https://<databricks_instance_url>/login/oauth/salesforce.html の形式で [コールバック URL] を入力します。 (例: https://cust-success.cloud.databricks.com/login/oauth/salesforce.html)。
2. (省略可能) 次の手順で SQL を使用して Azure Databricks 接続と外部カタログを作成する予定の場合は、Salesforce 接続アプリでもリダイレクト URI https://login.salesforce.com/services/oauth2/success をサポートする必要があります。カタログエクスプローラーを使用して Azure Databricks 接続と外部カタログを作成する場合、これは必要ありません。 Databricks では、手動の手順が他の方法よりも少なくて済むため、カタログエクスプローラーを使用することを推奨しています。
3. 次のスコープを追加します。
  - すべての Data Cloud API リソースにアクセスする (cdp_api)
  - API を使用してユーザーデータを管理する (api)
  - Data Cloud データで ANSI SQL クエリを実行する (cdp_query_api)
  - いつでも要求を実行する (refresh_token, offline_access)
4. [保存] をクリックします。
5. [続行] をクリックします。
[接続アプリの概要] ページで、[コンシューマーの詳細の管理] をクリックします。認証を求められます。
認証が成功すると、コンシューマーキーとコンシューマーシークレットが表示されます。これらの値を保存します。これらは、Azure Databricks 接続を作成するときに必要になります。

Azure Databricks 接続を作成する

接続では、外部データベースシステムにアクセスするためのパスと資格情報を指定します。接続を作成するには、Catalog Explorer を使用するか、Azure Databricks ノートブックまたは Databricks SQL クエリエディターで CREATE CONNECTION SQL コマンドを使用します。

Note

Databricks REST API または Databricks CLI を使用して接続を作成することもできます。 POST /api/2.1/unity-catalog/connections および Unity Catalog コマンドを参照してください。

必要な権限: メタストア管理者、または CREATE CONNECTION 特権を持つユーザー。

カタログエクスプローラー

Azure Databricks ワークスペースで、 [カタログ] をクリックします。
左側のペインで [外部データ] メニューを展開し、[接続] を選択します。
[接続の作成] をクリックします。
わかりやすい接続名を入力します。
接続の種類として Salesforce Data Cloud を選択します。
Salesforce Data Cloud の接続プロパティを次のように入力します。
- 認証の種類: OAuth
- サンドボックスである false
- (OAuth) クライアントシークレット: Salesforce 接続アプリのコンシューマーシークレット
- (OAuth) クライアント ID: Salesforce 接続アプリのコンシューマーキー
- (OAuth) クライアントスコープ: cdp_api api cdp_query_api refresh_token offline_access
[Salesforce でログイン] をクリックします。
(OAuth) SSO 資格情報を使用して Salesforce Data Cloud にサインインするように求められます。
ログインに成功すると、Databricks の [接続の作成] ページに戻ります。 [Salesforce でログイン] ボタンがメッセージ Successfully authorized に置き換わりました。
(省略可能) コメントを追加します。
Create をクリックしてください。

SQL

Databricks では、手動の手順が他の方法よりも少なくて済むため、接続と外部カタログの作成に Catalog Explorer を使用することを推奨しています。

SQL を使用して Azure Databricks 接続と外部カタログを作成する予定の場合は、Salesforce 接続アプリでリダイレクト URI https://login.salesforce.com/services/oauth2/success をサポートする必要があります。これは、カタログエクスプローラーを使用する場合、これは必要ありません。

PKCE コード検証コードとコードチャレンジコードを生成します。生成するには、https://tonyxu-io.github.io/pkce-generator/ などのオンラインツールを使用するか、次の Python スクリプトを実行します。

%python

import base64
import re
import os
import hashlib

code_verifier = base64.urlsafe_b64encode(os.urandom(40)).decode('utf-8')
code_verifier = re.sub('[^a-zA-Z0-9]+', '', code_verifier)

code_challenge = hashlib.sha256(code_verifier.encode('utf-8')).digest()
code_challenge = base64.urlsafe_b64encode(code_challenge).decode('utf-8')
code_challenge = code_challenge.replace('=', '')
print(f"pkce_verifier  = \"{code_verifier}\"")
print(f"code_challenge = \"{code_challenge}\"")

次の URL にアクセスし、Salesforce の資格情報を使用して認証を行い、authorization_code を取得します (<client_id> と <code_challenge> を実際のパラメーターに置き換えます)。
```
https://login.salesforce.com/services/oauth2/authorize
?client_id=<client_id>
&redirect_uri=https://login.salesforce.com/services/oauth2/success
&response_type=code
&code_challenge=<code_challenge>
```
URL でエンコードされた認証コードが、リダイレクトされた URL に表示されます。

ノートブックまたは Databricks SQL クエリエディターで次のコマンドを実行します。

CREATE CONNECTION '<Connection name>' TYPE salesforce_data_cloud
OPTIONS (
  client_id '<Consumer key from Salesforce Connected App>',
  client_secret '<Consumer secret from Salesforce Connected App>',
  pkce_verifier '<pkce_verifier from the last step>',
  authorization_code '<URL decoded `authorization_code`, should end with == instead of %3D%3D>',
  oauth_redirect_uri "https://login.salesforce.com/services/oauth2/success",
  oauth_scope "cdp_api api cdp_query_api refresh_token offline access",
  is_sandbox "false"
  );

Databricks では、資格情報などの機密性の高い値にはプレーンテキスト文字列ではなく Azure Databricks のシークレットを使用することを推奨しています。次に例を示します。

CREATE CONNECTION '<Connection name>' TYPE salesforce_data_cloud
OPTIONS (
  client_id secret ('<Secret scope>','<Secret key client id>'),
  client_secret secret ('<Secret scope>','<Secret key client secret>'),
  pkce_verifier '<pkce_verifier from the last step>',
  authorization_code '<URL decoded `authorization_code`, should end with == instead of %3D%3D>',
  oauth_redirect_uri "https://login.salesforce.com/services/oauth2/success",
  oauth_scope "cdp_api api cdp_query_api refresh_token offline access",
  is_sandbox "false"
  );

シークレットの設定については、「シークレットの管理」を参照してください。

外部カタログを作成する

外部カタログは、外部データシステム内のデータベースをミラーリングし、Azure Databricks と Unity Catalog を使ってそのデータベース内のデータに対するクエリの実行とアクセス管理ができるようにします。外部カタログを作成するには、定義済みのデータソースへの接続を使用します。

外部カタログを作成するには、Catalog Explorer を使用するか、Azure Databricks ノートブックまたは SQL クエリエディターで CREATE FOREIGN CATALOG SQL コマンドを使用します。

Note

Databricks REST API または Databricks CLI を使用してカタログを作成することもできます。 POST /api/2.1/unity-catalog/catalogs および Unity Catalog コマンドを参照してください。

必要なアクセス許可: メタストアに対する CREATE CATALOG アクセス許可と、接続の所有権または接続に対する CREATE FOREIGN CATALOG 特権。

カタログエクスプローラー

Azure Databricks ワークスペースで、 [カタログ] をクリックしてカタログエクスプローラーを開きます。
右上にある [カタログを作成] をクリックします。
Salesforce Data Cloud カタログのプロパティを次のように入力します。
- カタログ名: カタログのわかりやすい名前。
- 種類: Foreign。
- 接続名: カタログを作成する接続の名前。
- データスペース: Salesforce のデータスペース。
Create をクリックしてください。

SQL

ノートブックまたは SQL クエリエディターで次の SQL コマンドを実行します。角かっこ内の項目は省略可能です。

CREATE FOREIGN CATALOG [IF NOT EXISTS] '<catalog-name>' USING CONNECTION '<connection-name>'
OPTIONS (dataspace '<dataspace>');

次の値を置き換えます。

<catalog-name>=
<connection-name>=
<dataspace>: Salesforce のデータスペース。たとえば、default のようにします。

サポートされているプッシュダウン

以下のプッシュダウンがサポートされています。

フィルター
プロジェクション
なし
集計
オフセット
キャスト
Contains、Startswith、Endswith

データ型マッピング

Salesforce Data Cloud から Spark に読み取る場合、データ型は次のようにマップされます。

Salesforce Data Cloud の型	Spark の型
Boolean	BooleanType
日	DateType
日時	TimestampType
メール、電話、テキスト、URL	StringType
数値、パーセント	DecimalType(38, 18)

制限事項

1 つの Databricks カタログでサポートされる Salesforce データスペースは 1 つのみです。

次の方法で共有

Salesforce Data Cloud でフェデレーションクエリを実行する

開始する前に

Salesforce 接続アプリを作成する

Azure Databricks 接続を作成する

カタログエクスプローラー

SQL

外部カタログを作成する

カタログエクスプローラー

SQL

サポートされているプッシュダウン

データ型マッピング

制限事項

フィードバック

その他のリソース

次の方法で共有

Salesforce Data Cloud でフェデレーション クエリを実行する

開始する前に

Salesforce 接続アプリを作成する

Azure Databricks 接続を作成する

カタログ エクスプローラー

SQL

外部カタログを作成する

カタログ エクスプローラー

SQL

サポートされているプッシュダウン

データ型マッピング

制限事項

フィードバック

その他のリソース

Salesforce Data Cloud でフェデレーションクエリを実行する

カタログエクスプローラー

カタログエクスプローラー