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

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

レイクハウスフェデレーションを使用して Salesforce Data cloud データベースに接続するには、 Databricks Unity Catalogメタストアに以下を作成する必要があります。

  • Salesforce Data クラウド データベースへの接続。

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

始める前に

ワークスペースの要件:

  • Unity Catalog でワークスペースが有効になりました。

コンピュートの要件:

  • コンピュート・リソースからターゲット・データベース・システムへのネットワーク接続。 「レイクハウスフェデレーションのネットワーキングに関する推奨事項」を参照してください。

  • Databricksコンピュートは、Databricks Runtime 15.2 以降と、共有またはシングル ユーザー アクセス モードを使用する必要があります。

  • SQLウェアハウスは Pro または サーバレスで、2024.30 以上を使用している必要があります。

必要な権限：

  • 接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされた Unity Catalog メタストアに対するCREATE CONNECTION権限を持つユーザーである必要があります。

  • フォーリンカタログを作成するには、メタストアに対する CREATE CATALOG 権限を持ち、接続の所有者であるか、接続に対する CREATE FOREIGN CATALOG 権限を持っている必要があります。

追加の権限要件は、後続の各タスクベースのセクションで指定されます。

Salesforce 接続アプリケーションの作成

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

注：

詳細な手順については、Salesforce Data クラウド ドキュメントの「接続アプリケーションの作成」を参照してください。

Salesforce 接続アプリケーションを作成するには、次の手順を実行します。

  1. Data クラウドの右上にある[セットアップ]をクリックします。

  2. [ プラットフォームツール] で、[ アプリケーション] > [アプリケーションマネージャ] をクリックします。

  3. [新しい接続アプリケーション] をクリックします。

  4. 名前と連絡先の電子メールアドレスを入力します。

  5. OAuth設定を有効にする:

    1. コールバック URL を次の形式で入力します: https://<databricks_instance_url>/login/oauth/salesforce.html。たとえば、 https://cust-success.cloud.databricks.com/login/oauth/salesforce.htmlです。

    2. (オプション) 次のステップでSQLを使用してDatabricks接続とフォーリンカタログを作成する予定の場合は、Salesforce 接続アプリケーションでもリダイレクト URI https://login.salesforce.com/services/oauth2/success をサポートする必要があります。 Catalog Explorer を使用してDatabricks接続とフォーリンカタログを作成する場合、これは必要ありません。 Databricks 、他の方法よりも手動のステップが少なくて済むため、カタログ エクスプローラーの使用を推奨しています。

    3. 次の スコープを追加します。

      • すべてのデータにアクセスする クラウドAPIリソース ( cdp_api )

      • APIs ( api ) 経由でユーザーデータを管理する

      • データ クラウド データに対して ANSI SQLクエリを実行する ( cdp_query_api )

      • いつでもリクエストを実行 (更新、オフラインアクセス)

    4. [保存]をクリックします。

    5. 「続行」をクリックします。

  6. [接続アプリケーションの概要] ページで、[コンシューマの詳細の管理] をクリックします。認証を求められます。

  7. 認証が成功すると、 コンシューマキー と コンシューマシークレット が表示されます。 これらの値を保存します。 これらは、Databricks 接続を作成するときに必要になります。

Databricks接続を作成する

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

注：

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

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

  1. Databricksワークスペースで、カタログアイコンカタログ。

  2. At the top of the Catalog pane, click the Add or plus icon Add icon and select Add a connection from the menu.

    Alternatively, from the Quick access page, click the External data > button, go to the Connections tab, and click Create connection.

  3. On the Connection basics page of the Set up connection wizard, enter a user-friendly Connection name.

  4. Salesforce データクラウドの接続タイプを選択します。

  5. (オプション)コメントを追加します。

  6. On the Authentication page, enter the following connection properties for your Salesforce Data Cloud:

    • (Optional) Select Is sandbox.

    • Client ID: Salesforce connected app consumer key.

    • Client secret: Salesforce connected app consumer secret.

    • Client scope: cdp_api api cdp_query_api refresh_token offline_access

  7. Click Sign in with Salesforce.

  8. (OAuth) SSO資格情報を使用して Salesforce Data クラウドにサインインするように求められます。

  9. Upon successful login you are directed back to the Databricks Set up connection wizard. The Sign in with Salesforce button has been replaced with a Successfully authorized message.

  10. [ 接続の作成] をクリックします。

  11. On the Catalog basics page, enter a name for the foreign catalog. A foreign catalog mirrors a database in an external data system so that you can query and manage access to data in that database using Databricks and Unity Catalog.

  12. (Optional) Click Test connection to confirm that it works.

  13. Click Create catalog.

  14. On the Access page, select the workspaces in which users can access the catalog you created. You can select All workspaces have access, or click Assign to workspaces, select the workspaces, and then click Assign.

  15. Change the Owner who will be able to manage access to all objects in the catalog. Start typing a principal in the text box, and then click the principal in the returned results.

  16. Grant Privileges on the catalog. Click Grant:

    1. Specify the Principals who will have access to objects in the catalog. Start typing a principal in the text box, and then click the principal in the returned results.

    2. Select the Privilege presets to grant to each principal. All account users are granted BROWSE by default.

      • Select Data Reader from the drop-down menu to grant read privileges on objects in the catalog.

      • Select Data Editor from the drop-down menu to grant read and modify privileges on objects in the catalog.

      • Manually select the privileges to grant.

    3. Click Grant.

  17. Click Next.

  18. On the Metadata page, specify governed tags key-value pairs.

  19. (オプション)コメントを追加します。

  20. [保存]をクリックします。

Databricks 、他の方法よりも手動のステップが少なくて済むため、接続とフォーリンカタログの作成に Catalog Explorer を使用することをお勧めします。

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

  1. 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}\"")

  2. 次の 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 に表示されます。

  3. ノートブックまたは 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 では、資格情報などの機密値にはプレーンテキスト文字列ではなく 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"
  );

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

フォーリンカタログの作成

フォーリンカタログは、外部データ システム内のデータベースをミラーリングするため、Databricks と Unity Catalogを使用して、そのデータベース内のデータへのアクセスを管理できます。 フォーリンカタログを作成するには、すでに定義されている DATA への接続を使用します。

To create a foreign catalog, you can use Catalog Explorer or the CREATE FOREIGN CATALOG SQL command in a Databricks notebook or the SQL query editor. If you use the UI to create a connection to the data source, foreign catalog creation is included and you can skip this step.

注：

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

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

  1. Databricks ワークスペースで、カタログアイコン[カタログ]をクリックしてカタログ・エクスプローラーを開きます。

  2. 右上の [ カタログの作成] をクリックします。

  3. Salesforce Data クラウド カタログの次のプロパティを入力します。

    • カタログ名: カタログのわかりやすい名前。

    • タイプ: Foreign。

    • 接続名: カタログが作成される接続の名前。

    • データスペース: Salesforce データスペース。

  4. [作成]をクリックします。

ノートブックまたは SQL クエリ エディターで次の SQL コマンドを実行します。 括弧内の項目はオプションです。

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

次の値を置き換えます。

  • <catalog-name>：

  • <connection-name>：

  • <dataspace>: Salesforce データスペース。 たとえば、 defaultです。

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

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

  • フィルター

  • 予測

  • 制限

  • 集計

  • offset

  • キャスト

  • 含む、開始、終了

データ型のマッピング

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

Salesforce データクラウドタイプ

Sparkタイプ

ブール値

BooleanType

Date

DateType

日時型

TimestampType

Eメール、電話、テキスト、URL

StringType

数値、パーセント

DecimalType(38, 18)

制限事項

  • Only one Salesforce data space per Databricks catalog is supported.