與 Salesforce (SFDC) 整合

本頁說明如何將 Salesforce (SFDC) 作業工作負載整合至 Cortex Framework 資料基礎。Cortex Framework 會透過 Dataflow 管道將 Salesforce 的資料整合至 BigQuery，而 Cloud Composer 則會排定及監控這些 Dataflow 管道，從資料中取得洞察資訊。

注意： 為工作負載設定整合功能前，請先按照部署 Cortex Framework Data Foundation 的步驟操作。

設定檔

config.json Cortex Framework Data Foundation 存放區中的檔案會設定從任何資料來源 (包括 Salesforce) 移轉資料所需的設定。這個檔案包含下列參數，適用於運作中的 Salesforce 工作負載：

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

下表說明每個 SFDC 運作參數的值：

參數	意義	預設值	說明
SFDC.deployCDC	部署 CDC	true	產生 CDC 處理指令碼，在 Cloud Composer 中以 DAG 形式執行。如要瞭解 Salesforce Sales Cloud 的不同擷取選項，請參閱說明文件。
SFDC.createMappingViews	建立對應檢視區塊	true	系統會使用您提供的 DAG 從 Salesforce API 擷取新記錄，並更新到達網頁上的記錄。如果將這個值設為 true，系統會在 CDC 處理的資料集中產生檢視區塊，從原始資料集公開「最新版本的事實」資料表。如果為 false 且 SFDC.deployCDC 為 true，系統會根據 SystemModstamp 產生 DAG，並以變更資料擷取 (CDC) 處理。請參閱 Salesforce 的 CDC 處理程序，瞭解詳情。
SFDC.createPlaceholders	建立預留位置	true	如果擷取程序未產生預留位置表格，請建立空白預留位置表格，讓下游報表部署作業順利執行。
SFDC.datasets.raw	原始登陸資料集	-	這是 CDC 程序使用的位置，複製工具會將 Salesforce 中的資料放在這裡。如要使用測試資料，請建立空白資料集。
SFDC.datasets.cdc	CDC 處理的資料集	-	這個資料集會做為報表檢視區塊的來源，以及記錄處理 DAG 的目標。如要使用測試資料，請建立空白資料集。
SFDC.datasets.reporting	報表資料集 SFDC	"REPORTING_SFDC"	使用者可存取並用於報表的資料集名稱，其中部署了檢視區塊和面向使用者的資料表。
SFDC.currencies	篩選幣別	[ "USD" ]	如果未使用測試資料，請輸入與貴商家相關的單一貨幣 (例如 [ "USD" ]) 或多種貨幣 (例如 [ "USD", "CAD" ])。這些值可用於取代分析模型中 SQL 的預留位置 (如有)。

資料模型

本節將使用實體關係圖 (ERD) 說明 Salesforce (SFDC) 資料模型。

圖 2：Salesforce (SFDC)：實體關係圖。

基本檢視畫面

這些是 ERD 中的藍色物件，也是 CDC 資料表上的檢視畫面，除了部分資料欄名稱別名外，沒有任何轉換。請參閱src/SFDC/src/reporting/ddls中的指令碼。

報表資料檢視

這些是 ERD 中的綠色物件，包含報表資料表使用的相關維度屬性。請參閱src/SFDC/src/reporting/ddls中的指令碼。

Salesforce 資料需求

本節將具體說明如何建構 Salesforce 資料，以便搭配 Cortex Framework 使用。

• 表格結構：
  • 命名：資料表名稱使用 snake_case (以底線分隔的小寫字詞)，且為複數形式。例如：some_objects。
  • 資料類型：資料欄會保留與 Salesforce 中相同的資料類型。
  • 易讀性：為了讓報表層的資訊更清楚，部分欄位名稱可能會稍做調整。
• 空資料表和部署：部署程序會自動建立原始資料集中缺少的必要資料表，並將其設為空資料表。確保順利執行 CDC 部署步驟。
• CDC 規定：Id 和 SystemModstamp 欄位對於 CDC 指令碼追蹤資料變更至關重要。這些名稱可以完全相同，也可以不同。提供的原始處理指令碼會自動從 API 擷取這些欄位，並更新目標複製資料表。
  • Id：做為每筆記錄的專屬 ID。
  • SystemModstamp：這個欄位會儲存時間戳記，指出上次修改記錄的時間。
• 原始處理指令碼：提供的原始處理指令碼不需要額外的 CDC 處理。這項行為預設會在部署期間設定。

貨幣換算的來源資料表

Salesforce 提供兩種貨幣管理方式：

• 基本：這是預設選項，所有資料都會使用單一幣別。
• 進階：根據匯率在多種貨幣之間換算 (需要啟用進階貨幣管理)。

如果您使用進階貨幣管理，Salesforce 會使用兩個特殊資料表：

• CurrencyTypes：這個表格會儲存您使用的不同貨幣相關資訊 (例如美元、歐元等)。
• DatedConversionRates：這個表格會記錄一段時間內的貨幣匯率。

如果您使用進階幣別管理功能，Cortex Framework 會預期這些資料表存在。如果您未使用進階幣別管理功能，可以從設定檔 (src/SFDC/config/ingestion_settings.yaml) 中移除與這些資料表相關的項目。這個步驟可避免系統嘗試從不存在的資料表擷取資料。

將 SFDC 資料載入 BigQuery

Cortex Framework 提供以 Python 指令碼為基礎的複製解決方案，並在 Apache Airflow 和 Salesforce Bulk API 2.0 中排定時間。您可以調整這些 Python 指令碼，並在選擇的工具中排定執行時間。詳情請參閱 SFDC 擷取模組。

Cortex Framework 也提供三種不同的資料整合方法，視資料來源和管理方式而定：

1. API 呼叫：這個選項適用於可透過 API 直接存取的資料。Cortex Framework 可以呼叫 API、擷取資料，並將資料儲存在 BigQuery 的「原始」資料集中。如果資料集中有現有記錄，Cortex Framework 可以使用新資料更新這些記錄。
2. 結構對應檢視畫面：如果您已透過其他工具將資料載入 BigQuery，但資料結構與 Cortex Framework 的需求不符，這個方法就非常實用。Cortex Framework 會使用「檢視區塊」(類似虛擬資料表)，將現有資料結構轉換為 Cortex Framework 報表功能預期的格式。

3. CDC (變更資料擷取) 處理指令碼：這個選項專為不斷變更的資料設計。CDC 指令碼會追蹤這些變更，並據此更新 BigQuery 中的資料。這些指令碼會用到資料中的兩個特殊欄位：

   • Id：每筆記錄的專屬 ID。
   • SystemModstamp：時間戳記，表示記錄變更的時間。

   如果您的資料沒有這些確切名稱，可以調整指令碼，讓指令碼辨識不同名稱。您也可以在這個程序中，將自訂欄位新增至資料結構定義。舉例來說，含有帳戶物件資料的來源資料表應有原始的 Id 和 SystemModstamp 欄位。如果這些欄位的名稱不同，則必須更新 src/SFDC/src/table_schema/accounts.csv 檔案，並將 Id 欄位的名稱對應至 AccountId，以及將任何系統修改時間戳記欄位對應至 SystemModstamp。詳情請參閱 SystemModStamp 說明文件。

如果您已透過其他工具載入資料 (且資料會持續更新)，Cortex 仍可使用這些資料。CDC 指令碼隨附對應檔案，可將現有資料結構轉換為 Cortex Framework 要求的格式。您甚至可以在這個程序中將自訂欄位新增至資料。

設定 API 整合和 CDC

如要將 Salesforce 資料匯入 BigQuery，可以使用下列方法：

1. API 呼叫的 Cortex 指令碼：提供 Salesforce 或您選擇的資料複製工具的複製指令碼。重點是，匯入的資料應與來自 Salesforce API 的資料相同。
2. 複製工具和一律附加：如果您使用複製工具，這個方法適用於可新增資料記錄 (_appendalways_pattern) 或更新現有記錄的工具。
3. 複製工具並新增記錄：如果工具未更新記錄，且將任何變更複製到目標 (原始) 表格做為新記錄，Cortex Data Foundation 會提供建立 CDC 處理指令碼的選項。詳情請參閱 CDC 程序。

圖 1：Salesforce 工作負載：資料整合選項。

為確保資料符合 Cortex Framework 的預期，您可以調整對應設定，對應您的複製工具或現有結構定義。這會產生與 Cortex Framework Data Foundation 預期結構相容的對應檢視畫面。

使用 ingestion_settings.yaml 檔案設定指令碼的產生作業，以便呼叫 Salesforce API 並將資料複製到原始資料集 (第 salesforce_to_raw_tables 節)，以及產生指令碼來處理原始資料集和 CDC 處理資料集 (第 raw_to_cdc_tables 節) 中傳入的變更。

根據預設，用於從 API 讀取資料的指令碼會將變更更新至原始資料集，因此不需要 CDC 處理指令碼，而是建立對應檢視區塊，將來源結構定義與預期結構定義對齊。

如果 SFDC.createMappingViews=true 位於 config.json 中 (預設行為)，系統就不會執行 CDC 處理指令碼的生成作業。如需 CDC 指令碼，請設定 SFDC.createMappingViews=false。第二個步驟也允許在來源結構定義與 Cortex Framework Data Foundation 要求的結構定義之間進行對應。

以下 setting.yaml 設定檔範例說明，當複製工具直接將資料更新至複製的資料集時，如何產生對應檢視區塊，如 option 3 所示 (即不需要 CDC，只需要重新對應資料表和欄位名稱)。由於不需要 CDC，只要 config.json 檔案中的 SFDC.createMappingViews 參數維持 true，這個選項就會執行。

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

在本例中，從區段中移除基本資料表或所有資料表的設定，會略過該基本資料表或整個區段的 DAG 生成作業，如 salesforce_to_raw_tables 所示。在此情境中，設定 deployCDC : False 參數的效果相同，因為不需要產生 CDC 處理指令碼。

資料對應

您需要將傳入的資料欄位對應至 Cortex Data Foundation 預期的格式。舉例來說，來源資料系統中名為 unicornId 的欄位應重新命名，並在 Cortex Data Foundation 中識別為 AccountId (具有字串資料類型)：

• 來源欄位：unicornId (來源系統中使用的名稱)
• Cortex 欄位：AccountId (Cortex 預期的名稱)
• 資料類型：String (Cortex 預期的資料類型)

對應多型欄位

Cortex Framework Data Foundation 支援對應多型欄位，這類欄位的名稱可能不同，但結構保持一致。多型欄位 型別名稱 (例如 Who.Type) 可透過在對應的 CSV 檔案中新增 [Field Name]_Type 項目來複製： src/SFDC/src/table_schema/tasks.csv。舉例來說，如要複製 Task 物件的 Who.Type 欄位，請新增 Who_Type,Who_Type,STRING 行。這會定義名為 Who.Type 的新欄位，該欄位會對應至自身 (保留相同名稱)，且具有字串資料類型。

修改 DAG 範本

您可能需要根據 Airflow 或 Cloud Composer 執行個體調整 CDC 的 DAG 範本或原始資料處理的 DAG 範本。詳情請參閱「收集 Cloud Composer 設定」。

如果您不需要透過 API 呼叫產生 CDC 或原始資料，請設定 deployCDC=false。或者，您也可以移除 ingestion_settings.yaml 中各節的內容。如果資料結構與 Cortex Framework Data Foundation 預期的結構一致，您可以略過產生對應檢視區塊的步驟，並設定 SFDC.createMappingViews=false。

設定擷取模組

本節將說明如何使用 Data Foundation 提供的 Salesforce 至 BigQuery 擷取模組。您的需求和流程可能會因系統和現有設定而異。你也可以使用其他可用工具。

設定憑證並連結應用程式

以管理員身分登入 Salesforce 執行個體，完成下列步驟：

1. 在 Salesforce 中建立或找出符合下列需求的設定檔：
   1. Permission for Apex REST Services and API Enabled 系統權限。
   2. 您要複製的所有物件都已授予 View All 權限。例如「帳戶」和「案件」。向安全管理員確認是否有任何限制或問題。
   3. 未授予與使用者介面登入相關的任何權限，例如 Lightning Experience 中的 Salesforce Anywhere、Salesforce Anywhere 行動版、Lightning Experience 使用者和 Lightning 登入使用者。向安全管理員確認是否有任何限制或問題。
2. 在 Salesforce 中建立或識別現有使用者。您必須知道使用者的使用者名稱、密碼和安全權杖。請考量下列要點：
   • 最好是專門執行這項複製作業的使用者。
   • 使用者應指派給您在步驟 1 建立或識別的設定檔。
   • 您可以在這裡查看「使用者名稱」並重設「密碼」。
   • 如果沒有安全權杖，且權杖未用於其他程序，可以重設安全權杖。
3. 建立已連線應用程式。這是唯一通訊管道，可透過設定檔、Salesforce API、標準使用者憑證和安全性權杖，從外部世界建立與 Salesforce 的連線。
   1. 按照操作說明啟用 API 整合的 OAuth 設定。
   2. 確認 Require Secret for Web Server Flow 和 Require Secretfor Refresh Token Flow 已在「API (已啟用 OAuth 設定)」專區中啟用。
   3. 請參閱說明文件，瞭解如何取得消費者金鑰 (稍後會做為用戶端 ID 使用)。如有問題或限制，請洽詢安全管理員。
4. 將連結的應用程式指派給建立的設定檔。
   1. 在 Salesforce 主畫面的右上角選取「設定」。
   2. 在「快速尋找」方塊中輸入 profile，然後選取「設定檔」。搜尋在步驟 1 中建立的設定檔。
   3. 開啟個人資料。
   4. 按一下「已指派的連結應用程式」連結。
   5. 按一下 [編輯]。
   6. 新增剛建立的已連結應用程式。
   7. 按一下「儲存」按鈕。

設定 Secret Manager

設定 Secret Manager 來儲存連線詳細資料。Salesforce-to-BigQuery 模組會使用 Secret Manager 安全地儲存連線至 Salesforce 和 BigQuery 時所需的憑證。這個方法可避免在程式碼或設定檔中直接公開密碼等機密資訊，進而提升安全性。

請使用下列規格建立密鑰。如需詳細操作說明，請參閱「建立密鑰」。

• 密鑰名稱：airflow-connections-salesforce-conn

• 密鑰值：

  http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`
  

  更改下列內容：

  • USERNAME 改為您的使用者名稱。
  • PASSWORD 密碼。
  • 將 INSTANCE_NAME 替換為執行個體名稱。
  • 將 CLIENT_ID 改成您的用戶端 ID。
  • 將 SECRET_TOKEN 替換為密鑰權杖。

詳情請參閱如何找出執行個體名稱。

用於複製的 Cloud Composer 程式庫

如要在 Cortex Framework Data Foundation 提供的 DAG 中執行 Python 指令碼，您需要安裝一些依附元件。如果是 Airflow 1.10 版，請按照「為 Cloud Composer 1 安裝 Python 依附元件」一文的說明，依序安裝下列套件：

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

如果是 Airflow 2.x 版，請參閱「為 Cloud Composer 2 安裝 Python 依附元件」說明文件，瞭解如何安裝 apache-airflow-providers-salesforce~=5.2.0。

使用下列指令安裝各個必要套件：

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

更改下列內容：

• 將 ENVIRONMENT_NAME 替換為指派的環境名稱。
• LOCATION。
• 將 PACKAGE_NAME 替換為所選套件名稱。
• EXTRAS_AND_VERSION，並提供額外項目和版本的規格。

以下是安裝必要套件的指令範例：

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

啟用 Secret Manager 做為後端

啟用 Google Secret Manager 做為安全後端。這個步驟會引導您啟用 Secret Manager，做為 Cloud Composer 環境所用密碼和 API 金鑰等機密資訊的主要儲存位置。這項服務可集中管理憑證，有助於提升安全性。詳情請參閱 Secret Manager。

允許 Composer 服務帳戶存取密鑰

這個步驟可確保與 Cloud Composer 相關聯的服務帳戶，具備存取 Secret Manager 中所儲存密鑰的必要權限。根據預設，Cloud Composer 會使用 Compute Engine 服務帳戶。必要權限為 Secret Manager Secret Accessor。 這項權限可讓服務帳戶擷取及使用儲存在 Secret Manager 中的密鑰。如需在 Secret Manager 中設定存取權控管的完整指南，請參閱存取權控管說明文件。

Airflow 中的 BigQuery 連線

請務必按照「收集 Cloud Composer 設定」一文的說明建立連線 sfdc_cdc_bq。Salesforce-to-BigQuery 模組可能使用這個連線，與 BigQuery 建立通訊。

後續步驟

• 如要進一步瞭解其他資料來源和工作負載，請參閱「資料來源和工作負載」一文。
• 如要進一步瞭解在正式環境中部署的步驟，請參閱 Cortex Framework Data Foundation 部署作業的必要條件。