在 Salesforce Data Cloud 上執行聯合查詢

發行項
01/13/2025

本文說明如何 set Up Lakehouse Federation，對 Azure Databricks 未管理的 Salesforce Data Cloud 數據執行同盟查詢。若要深入了解 Lakehouse Federation，請參閱什麼是 Lakehouse Federation？。

若要使用 Lakehouse Federation 連線到 Salesforce Data Cloud 資料庫，您必須在 Azure Databricks Unity Catalog metastore 中建立下列項目：

與 Salesforce Data Cloud 資料庫的連線。
外部 catalog，可鏡像 Unity Catalog 中的 Salesforce Data Cloud 資料庫，讓您可以使用 Unity Catalog 查詢語法和數據控管工具來管理 Azure Databricks 使用者對資料庫的存取權。

開始之前

工作區需求：

針對 Unity Catalog啟用工作區。

計算需求：

您的計算資源與目標資料庫系統之間的網路連接能力。請參閱 Lakehouse Federation 的網路建議。
Azure Databricks 計算必須使用 Databricks Runtime 15.2 或更新版本，並且採用 共用（Shared） 或 單一使用者（Single user） 存取模式（access mode）。
SQL 倉儲必須是專業或無伺服器，且必須使用 2024.30 或更新版本。

所需的權限：

若要建立連線，您必須是中繼存放區系統管理員或具有附加至工作區之 Unity CREATE CONNECTION 中繼存放區 Catalog 許可權的使用者。
若要建立外部 catalog，您必須擁有中繼存放區的 CREATE CATALOG 權限，而且必須是連線的擁有者，或者具備連線的 CREATE FOREIGN CATALOG 權限。

後續每個以任務為基礎的區段會指定其他權限需求。

建立 Salesforce 連線應用程式

Salesforce 連線應用程式可讓外部應用程式使用 API 和標準通訊協定與 Salesforce 整合。本節說明如何使用 SSO 建立連線應用程式，以允許 Databricks 向 Salesforce 進行驗證。

注意

如需更詳細的說明，請參閱 Salesforce Data Cloud 文件中的建立連線應用程式。

若要建立 Salesforce 連線應用程式，請執行下列動作：

在 Data Cloud 右上角，按一下 [設定]。
在 [平台工具] 底下，按一下 [應用程式應用程式管理員]。>
按一下 [新增連線應用程式]。
輸入 [名稱] 和 [連絡人] 電子郵件地址。
啟用 [OAuth 設定]：
1. 以下列格式輸入 [回撥 URL]：。https://<databricks_instance_url>/login/oauth/salesforce.html 例如： https://cust-success.cloud.databricks.com/login/oauth/salesforce.html 。
2. （選擇性）如果您打算在下一個步驟中使用 SQL 來建立 Azure Databricks 連線和外部 catalog，您的 Salesforce 連線應用程式也需要支援重新導向 URI https://login.salesforce.com/services/oauth2/success。如果您打算使用 Catalog Explorer 來建立 Azure Databricks 連線以及與外部 catalog的連接，那麼這一項是不需要的。 Databricks 建議使用 Catalog Explorer，因為它需要比其他方法更少的手動步驟。
3. 新增下列 [範圍]：
  - 存取所有 Data Cloud API 資源 (cdp_api)
  - 透過 API 管理使用者資料 (api)
  - 對 Data Cloud 資料執行 ANSI SQL 查詢 (cdp_query_api)
  - 隨時執行要求 (refresh_token、offline_access)
4. 按一下 [檔案] 。
5. 按一下繼續。
在 [連線應用程式概觀] 頁面上，按一下 [管理取用者詳細資料]。系統會提示您進行驗證。
成功驗證之後，就會顯示 [取用者金鑰] 和 [取用者祕密]。儲存這些 values。建立 Azure Databricks 連線時，將需要它們。

建立 Azure Databricks 連線

連線會指定存取外部資料庫系統的路徑和 credentials。若要建立連線，您可以在 Azure Databricks 筆記本或 Databricks SQL 查詢編輯器中使用 Catalog Explorer 或 CREATE CONNECTION SQL 命令。

注意

您也可使用 Databricks REST API 或 Databricks CLI 來建立連線。請參閱 POST /api/2.1/unity-catalog/connections 和 Unity Catalog 命令。

需要的權限：具有 CREATE CONNECTION 權限的中繼存放區系統管理員或使用者。

Catalog 探索者

在 Azure Databricks 工作區中，按兩下 Catalog。
在 [Catalog] 窗格頂端，按兩下 [新增] 圖示，然後 select從功能表新增連線。

或者，從 [快速存取] 頁面，按兩下 [外部數據 >] 按鈕，移至 [Connections] 索引標籤，然後按兩下 [建立連線。
在 [連線基本概念] 頁面上的 [Set 連線向導] 中，輸入使用者易記的 連線名稱。
salesforce Data Cloud 連線類型。
(選用) 新增註解。
在 [驗證] 頁面上，輸入 Salesforce Data Cloud 的下列連線屬性：
- （選擇性） Select是沙箱。
- 用戶端識別碼：Salesforce 連線的應用程式取用者密鑰。
- 客戶端密碼：Salesforce 連線的應用程式取用者密碼。
- 用戶端範圍： cdp_api api cdp_query_api refresh_token offline_access
點擊 [使用 Salesforce登入]。
（OAuth）系統會提示您使用 SSO credentials登入 Salesforce Data Cloud。
在成功登入後，您會被導回 Databricks Set 連線 精靈程式。 Salesforce 登入按鈕 已被 Successfully authorized 訊息取代。
按一下 [建立連線]。
在 [Catalog 基本 頁面上，輸入外國 catalog的名稱。外部 catalog 會鏡像外部數據系統中的資料庫，讓您可以使用 Azure Databricks 和 Unity Catalog查詢和管理該資料庫中數據的存取權。
（選擇性）點擊 [測試連線] 以確認其是否正常運作。
按一下 建立 catalog。
在 [Access] 頁面上，select 使用者可以存取您所建立 catalog 的工作區。您可以 select所有工作區都有存取權，或點擊 [] 指派至工作區 []、select 工作區，然後點擊 [] 指派 []。
變更可以管理 catalog中所有物件存取權的 擁有者。開始在文字框中輸入對象，然後點擊傳回結果中的對象。
Grant 的許可權在 catalog上。按一下 Grant：
1. 指定主體誰可以存取 catalog中的物件。開始在文字框中輸入主體，然後在傳回的結果中單擊主體。
2. Select 權限預設grant 給每個主體。根據預設，所有帳戶用戶都會被授與 BROWSE。
  - 在下拉功能表中選擇 Select數據讀取器，以便在 catalog上的物件分配 grantread 權限。
  - 從下拉選單中選擇 Select數據編輯器，以獲得 grantread 和 modify 權限，應用到 catalog中的對象。
  - 手動設定 select 到 grant的許可權。
3. 按一下 Grant。
點選 [下一步]。
在 [元數據] 頁面上，指定受控標記索引鍵/值組。
(選用) 新增註解。
按一下 [檔案] 。

SQL

Databricks 建議使用 Catalog Explorer 來建立連線和外鍵 catalog，因為這樣比其他方法需要更少的手動步驟。

如果您打算使用 SQL 來建立 Azure Databricks 連線和外部 catalog，您的 Salesforce 連線應用程式必須支援重新導向 URI https://login.salesforce.com/services/oauth2/success。如果您使用 Catalog Explorer，就不需要這個。

Generate 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 credentials 進行驗證，以 getauthorization_code（以您的 <client_id>取代 <code_challenge> 和 parameters）。
```
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 秘密，而不是純文本字串，例如 values等敏感性 credentials。例如：

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"
  );

如需設定祕密的相關資訊，請參閱祕密管理。

建立外部 catalog

外部 catalog 會鏡像外部數據系統中的資料庫，讓您可以使用 Azure Databricks 和 Unity Catalog查詢和管理該資料庫中數據的存取權。若要建立外部 catalog，您可以使用已定義的數據源連線。

若要建立外部 catalog，您可以在 Azure Databricks 筆記本或 SQL 查詢編輯器中使用 Catalog Explorer 或 CREATE FOREIGN CATALOG SQL 命令。如果您透過使用者介面 (UI) 來建立與資料來源的連線，則包括建立外部 catalog，您可以略過此步驟。

注意

您也可以使用 Databricks REST API 或 Databricks CLI 來建立 catalog。請參閱 POST /api/2.1/unity-catalog/catalogs 和 Unity Catalog 命令。

必要權限：中繼存放區的 CREATE CATALOG 權限，以及連線的所有權或連線的 CREATE FOREIGN CATALOG 權限。

Catalog 探索者

在 Azure Databricks 工作區中，按兩下 [Catalog 以開啟 Catalog Explorer。
在右上方，按一下 [建立] Catalog。
輸入 Salesforce Data Cloud catalog的下列屬性。
- Catalog 名稱：供 catalog使用者易於記憶的名稱。
- 類型：Foreign。
- 連接名稱：將會建立 catalog 的連接名稱。
- 資料空間：Salesforce 資料空間。
按一下 [建立]。

SQL

在筆記本或 SQL 查詢編輯器中執行下列 SQL 命令。括弧中的項目是可選內容。

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

取代下列 values：

<catalog-name>：
<connection-name>：
<dataspace>：Salesforce 資料空間。例如： default 。

支援下推

支援下列下推：

篩選
投影
Limit
彙總
Offset
Cast
Contains、Startswith、Endswith

資料類型對應

當您從 Salesforce Data Cloud 讀取至 Spark 時，資料類型會對應如下：

Salesforce Data Cloud 類型	Spark 類型
布林值	BooleanType
Date	DateType
Datetime	TimestampType
電子郵件、電話、文字、URL	StringType
Number、Percent	DecimalType(38, 18)

限制

每個 Databricks catalog 僅支援一個 Salesforce 資料空間。

其他資源

Lakehouse 同盟不會不支援 Salesforce Sales Cloud 的只讀 connections，但 LakeFlow Connect 可讓您將數據從 Salesforce Sales Cloud 擷取到 Databricks Lakehouse。查看從 Salesforce 匯入數據。

共用方式為

在 Salesforce Data Cloud 上執行聯合查詢

開始之前

建立 Salesforce 連線應用程式

建立 Azure Databricks 連線

Catalog 探索者

SQL

建立外部 catalog

Catalog 探索者

SQL

支援下推

資料類型對應

限制

其他資源

意見反應

其他資源