將 Salesforce 資料載入 BigQuery

如要安排從 Salesforce Sales Cloud 到 BigQuery 的週期性資料移轉作業，請建立移轉設定，指定要移轉的資料物件，以及安排資料移轉作業的頻率。您可以使用 Google Cloud 控制台、bq 指令列工具或 BigQuery 資料移轉服務 API，建立移轉設定。設定完移轉設定後，BigQuery 資料移轉服務就會按照指定時間表，將最新資料移轉至 BigQuery 資料表。

如要瞭解 Salesforce 轉移作業的運作方式，請參閱「Salesforce 轉移作業簡介」。

限制

Salesforce 資料移轉作業有下列限制：

  • Salesforce 連接器僅支援從 Salesforce Sales Cloud 轉移資料。
  • Salesforce 連接器僅支援 Salesforce Bulk API V1 64.0 版中包含的欄位。系統可能不支援舊版 Salesforce Bulk API 中的某些欄位。如要進一步瞭解 Salesforce 連接器的這些變更，請參閱「Salesforce Bulk API」。

  • Salesforce 連接器會使用 Salesforce Bulk API V1 連線至 Salesforce Sales Cloud 端點，以擷取資料。

    • Salesforce 連接器僅支援 Salesforce Bulk API V1，可連線至 Salesforce 執行個體，且僅支援轉移 Salesforce Bulk API 支援的實體。如要進一步瞭解支援的實體，請參閱「Bulk API 不支援實體」。

  • Salesforce 連接器不支援傳輸含有二進位欄位的下列物件。

    • Attachment
    • ContentVersion
    • Document
    • StaticResource
    • Scontrol
    • EmailCapture
    • MailMergeTemplate

  • 週期性資料轉移作業之間的最短時間間隔為 15 分鐘。重複轉移的預設間隔為 24 小時。

  • 由於 Salesforce 處理限制，一次排定過多資料轉移作業可能會導致延遲或失敗。建議您將 Salesforce 資料傳輸限制為下列項目：

    • 每個移轉設定最多只能有 10 項資產。
    • 在不同的轉移設定中，最多可同時執行 10 次轉移作業。

  • 單一移轉設定在特定時間只能支援一次資料移轉作業。如果排定在第一次資料轉移完成前執行第二次資料轉移，則系統只會完成第一次資料轉移，並略過任何與第一次轉移重疊的資料轉移。

    • 為避免在單一轉移設定中略過轉移作業，建議您設定「重複頻率」，增加大型資料轉移作業之間的時間間隔。

  • 如果透過網路連結進行資料移轉，請務必設定 Public NAT，並使用靜態 IP 位址。詳情請參閱「為 Salesforce 移轉作業設定 IP 許可清單」一文。

  • 如果設定的網路附件和虛擬機器 (VM) 執行個體位於不同區域，從 Salesforce 轉移資料時，可能會發生跨區域資料移動。

增量移轉限制

增量 Salesforce 轉移作業有下列限制：

  • 浮水印資料欄只能選擇 TIMESTAMP 個資料欄。
  • 只有含有有效浮水印欄的資產，才支援增量擷取。
  • 浮水印資料欄中的值必須單調遞增。
  • 增量轉移作業無法同步處理來源資料表中的刪除作業。
  • 單一轉移設定只能支援增量或完整擷取。
  • 第一次執行增量擷取後，就無法更新 asset 清單中的物件。
  • 首次執行增量擷取後，就無法在轉移設定中變更寫入模式。
  • 第一次執行遞增式擷取作業後，就無法變更時間戳記欄或主鍵。
  • 目的地 BigQuery 資料表會使用您提供的主鍵進行叢集，並受叢集資料表限制約束。
  • 首次將現有轉移設定更新為增量擷取模式時，更新後的第一次資料轉移會從資料來源轉移所有可用資料。後續的增量資料轉移作業只會轉移資料來源中的新資料列和更新資料列。

如要瞭解增量轉移的運作方式，請參閱「完整或增量轉移」。

事前準備

下列各節說明建立 Salesforce 資料轉移作業前必須採取的步驟。

建立 Salesforce 連結的應用程式

您必須建立 Salesforce 連線的應用程式，並完成下列必要設定：

  • 在連結的應用程式中設定基本資訊。連結的應用程式名稱和聯絡人電子郵件地址 欄位是 Salesforce 轉移作業的必要欄位。
  • 啟用 OAuth 設定 並進行下列設定：
    • 勾選「Enable OAuth Settings」核取方塊。
    • 在「Callback URL」(回呼網址) 欄位中，輸入下列內容：
      • 如果是正式環境，請輸入 https://login.salesforce.com/services/oauth2/token。
      • 如果是沙箱環境，請輸入 https://test.salesforce.com/services/oauth2/token。
    • 確認未選取「Issue JSON Web Token (JWT)-based access tokens for named users」(為具名使用者核發以 JSON Web Token 為基礎的存取權杖) 核取方塊。
  • 在「Selected OAuth Scopes」部分，選取「Manage user data via APIs (api)」。
  • 取消勾選「Required Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows」(支援的授權流程必須使用 Proof Key for Code Exchange (PKCE) 擴充功能) 核取方塊。
  • 選取「Enable Client Credentials Flow」，然後按一下顯示通知中的「OK」。

設定連結的應用程式並完成必要設定後，請按一下「儲存」。系統會將您重新導向至新建立的「已連結的應用程式」詳細資料頁面。

建立連結的應用程式後，您也必須設定用戶端憑證流程，方法如下：

  1. 點選 [設定]。
  2. 在搜尋列中搜尋「已連結的應用程式」。
  3. 依序點選「管理應用程式」>「已連結的應用程式」。如果您使用 Salesforce Lightning Experience，請按一下「管理連結的應用程式」。
  4. 在您建立的已連線應用程式上，按一下「編輯」。
  5. 「應用程式詳細資料」頁面隨即顯示。在「Client Credentials Flow」(用戶端憑證流程) 部分，於「Run As」(以使用者身分執行) 欄位中輸入使用者名稱。您可以使用這個欄位的尋找工具，確保選取的使用者正確無誤。
  6. 按一下 [儲存]。

必要的 Salesforce 資訊

建立 Salesforce 資料移轉作業時，您必須提供下列 Salesforce 資訊：

參數名稱 說明
myDomain Salesforce 中的「我的網域」。
clientId 與 Salesforce 連結的應用程式用戶端金鑰。
clientSecret

Salesforce 連結應用程式的 OAuth 用戶端密鑰或消費者密鑰。

如要取得 myDomain、clientID 和 clientSecret 值，請選取下列任一選項：

Salesforce Classic

擷取「myDomain」詳細資料

如要找出 myDomain，請按照下列步驟操作：

  1. 登入 Salesforce 平台。
  2. 點選 [設定]。
  3. 在搜尋列中搜尋「我的網域」。
  4. 在搜尋結果中，依序點選「網域管理」>「我的網域」。

在「我的網域詳細資料」部分中，myDomain 會顯示為「目前的我的網域 URL」的前置字元。舉例來說，如果「我的網域」網址為 example.my.salesforce.com，則要使用的 myDomain 值為 example。

擷取「ClientId」和「ClientSecret」詳細資料

如要找出 ClientId 和 ClientSecret 值，請按照下列步驟操作：

  1. 登入 Salesforce 平台。
  2. 點選 [設定]。
  3. 在搜尋列中搜尋「應用程式」。
  4. 在搜尋結果的「建構」部分，依序點選「建立」>「應用程式」。
  5. 按一下「已連結的應用程式名稱」。
  6. 在「連結的應用程式」詳細資料頁面，按一下「管理取用者詳細資料」。
  7. 使用其中一種已註冊的方法驗證身分。您最多可以查看消費者詳細資料頁面五分鐘，之後系統會提示您再次驗證身分。
  8. 在「消費者詳細資料」頁面中，「消費者金鑰」就是你的 ClientId 值。「Customer Secret」是你的 ClientSecret 值。

Salesforce Lightning Experience

擷取「myDomain」詳細資料

如要找出 myDomain，請按照下列步驟操作：

  1. 登入 Salesforce 平台。

  2. 點選 [設定]。

    在 Salesforce 平台中開啟「設定」頁面。

  3. 在搜尋列中搜尋「我的網域」。

  4. 在搜尋結果中，依序點選「公司設定」>「我的網域」。

在「我的網域詳細資料」部分中，myDomain 會顯示為「目前的我的網域 URL」的前置字元。舉例來說，如果「我的網域」網址為 example.my.salesforce.com，則要使用的 myDomain 值為 example。

擷取「ClientId」和「ClientSecret」詳細資料

  1. 登入 Salesforce 平台。
  2. 點選 [設定]。
  3. 在搜尋列中搜尋「應用程式」。
  4. 在搜尋結果中，依序點選「應用程式」>「應用程式管理工具」。
  5. 找出已連結的應用程式，然後按一下「查看」。
  6. 按一下「管理取用者詳細資料」。
  7. 使用其中一種已註冊的方法驗證身分。您最多可以查看消費者詳細資料頁面五分鐘，之後系統會提示您再次驗證身分。
  8. 在「消費者詳細資料」頁面中，「消費者金鑰」就是你的 ClientId 值。「Customer Secret」是你的 ClientSecret 值。

為 Salesforce 轉移作業設定 IP 許可清單

您必須設定 Google Cloud 環境和 Salesforce 帳戶，才能將特定 IP 位址加入資料傳輸許可清單。這樣可確保 Salesforce 只會接受來自可信任的靜態 IP 位址的連線。如果您在資料傳輸時使用網路附件，就必須執行這個步驟。

如要這麼做，您必須先設定 Google Cloud 網路，使其使用靜態 IP 位址：

  1. 設定公用網路位址轉譯 (NAT)，並在虛擬私有雲網路中指定靜態 IP 位址。Cloud NAT 必須在與資料移轉目的地資料集相同的區域內設定。
  2. 在同一個虛擬私有雲網路中設定網路連結。BigQuery 資料移轉服務會使用這項資源存取私人服務。

接著，您必須在 Salesforce 中設定信任的 IP 範圍。 新增 IP 位址範圍時，請使用Google Cloud 公開 NAT 的靜態 IP 位址，做為 IP 範圍的起始和結束 IP 位址。

設定 IP 範圍後，您現在可以在設定轉移設定時指定靜態 IP，方法是在「網路附件」欄位中選取網路附件。

BigQuery 必要條件

必要的 BigQuery 角色

如要取得建立 BigQuery 資料移轉服務資料移轉作業所需的權限，請要求管理員在專案中授予您 BigQuery 管理員 (roles/bigquery.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立 BigQuery 資料移轉服務資料移轉作業所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立 BigQuery 資料移轉服務資料移轉作業，您必須具備下列權限：

  • BigQuery 資料移轉服務權限：
    • bigquery.transfers.update
    • bigquery.transfers.get
  • BigQuery 權限：
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.datasets.setIamPolicy
    • bigquery.jobs.create

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

詳情請參閱「授予 bigquery.admin 存取權」。

設定 Salesforce 資料轉移作業

如要將 Salesforce 資料新增至 BigQuery，請使用下列任一方法設定移轉作業：

控制台

  1. 前往 Google Cloud 控制台的「資料移轉」頁面。

    前往「資料轉移」頁面

  2. 按一下 「建立轉移作業」。

  3. 在「Source type」(來源類型) 部分，「Source」(來源) 請選取「Salesforce」。

  4. 在「Data source details」(資料來源詳細資料) 部分執行下列操作：

    • 在「Network attachment」(網路連結) 部分，從清單中選取網路連結。您必須設定 Public NAT 並設定 IP 允許清單，才能使用網路附件進行這項資料轉移作業。
    • 在「My Domain」(我的網域)，輸入您的 Salesforce My Domain。
    • 在「Client ID」(用戶端 ID)，輸入與 Salesforce 連結的應用程式用戶端金鑰。
    • 在「Client secret」(用戶端密鑰)，輸入與 Salesforce 連結的應用程式用戶端密鑰。
    • 在「Ingestion type」(擷取類型) 部分，選取「Full」(完整) 或「Incremental」(增量)。
      • 如果為「Write mode」(寫入模式) 選取「Incremental」(增量)，請選取「Append」(附加) 或「Upsert」(新增或更新)。如要進一步瞭解不同的寫入模式，請參閱「完整或增量轉移」一節的說明。
    • 在「Salesforce objects to transfer」(要移轉的 Salesforce 物件) 部分點選「Browse」(瀏覽)：
      • 選取要轉移至 BigQuery 目的地資料集的所有物件。您也可以在這個欄位手動輸入要移轉資料的物件。
      • 如果選取「Append」(附加) 做為增量寫入模式，就必須選取一個欄做為浮水印欄。
      • 如果已選取「Upsert」(新增或更新) 做為增量寫入模式，則必須選取一個欄做為浮水印欄，然後選取一或多個欄做為主鍵。

  5. 在「Destination settings」(目的地設定) 部分，「Dataset」(資料集) 請選取您為了儲存資料而建立的資料集。

  6. 在「Transfer config name」(轉移設定名稱) 部分，「Display name」(顯示名稱) 請輸入資料移轉作業名稱。

  7. 在「Schedule options」(排程選項) 專區：

    • 在「Repeat frequency」(重複執行頻率) 清單中，選取選項，指定這項資料移轉作業的執行頻率。如要指定自訂重複頻率，請選取「Custom」(自訂)。如果選取「On-demand」(隨選)，這項移轉作業會在您手動觸發後執行。
    • 視情況選取「Start now」(立即開始) 或「Start at set time」(在所設時間開始執行)，並提供開始日期和執行時間。

  8. 選用：在「Notification options」(通知選項) 專區，執行下列操作：

    • 如要啟用電子郵件通知，請點選「Email notification」(電子郵件通知) 切換按鈕。啟用這個選項之後，若移轉失敗，移轉作業管理員就會收到電子郵件通知。
    • 如要針對這項移轉作業啟用 Pub/Sub 移轉作業執行通知，請點選「Pub/Sub notifications」(Pub/Sub 通知) 切換按鈕。您可以選取主題名稱，也可以點選「Create a topic」(建立主題) 來建立主題。

  9. 按一下「儲存」。

bq

輸入 bq mk 指令 並加上移轉建立作業旗標 --transfer_config：

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

其中：

  • PROJECT_ID (選用)：您的 Google Cloud 專案 ID。 如未提供 --project_id 指定特定專案，系統會使用預設專案。
  • DATA_SOURCE：資料來源 - salesforce。
  • NAME：資料移轉設定的顯示名稱。移轉作業名稱可以是任意值，日後需要修改移轉作業時，能夠據此識別即可。
  • DATASET：移轉設定的目標資料集。

  • PARAMETERS：已建立移轉設定的 JSON 格式參數。例如：--params='{"param":"param_value"}'。以下是 Salesforce 資料轉移的參數：

    • connector.authentication.oauth.clientId：Salesforce 連結應用程式的消費者金鑰。
    • connector.authentication.oauth.clientSecret：Salesforce 連線應用程式的 OAuth 用戶端密鑰或消費者密鑰。
    • connector.authentication.oauth.myDomain：Salesforce 我的網域。舉例來說，如果網域網址為 example.my.salesforce.com，則值為 example。
    • ingestionType：指定 full 或 incremental。詳情請參閱「完整或增量轉移」。
    • writeMode：指定 WRITE_MODE_APPEND 或 WRITE_MODE_UPSERT。
    • watermarkColumns：將資料表中的資料欄指定為浮水印資料欄。如要進行增量轉移，這個欄位為必填。
    • primaryKeys：將資料表中的資料欄指定為主鍵。 如要進行增量轉移，這個欄位為必填。
    • assets：要移轉至 BigQuery 的 Salesforce 物件路徑。

在增量轉移期間指定多項資產時，watermarkColumns 和 primaryKeys 欄位的值會對應至 assets 欄位中的值位置。在下列範例中，Id 對應於資料表 Account，而 master_label 和 type 則對應於資料表 CaseHistory。

      "primaryKeys":[['Id'], ['master_label','type']],
      "assets":["Account","CaseHistory"],

下列指令會在預設專案中建立 Salesforce 增量資料移轉作業，並使用 APPEND 寫入模式。

bq mk
    --transfer_config
    --target_dataset=mydataset
    --data_source=salesforce
    --display_name='My Transfer'
    --params='{"assets": ["Account", "CaseHistory"]
        "connector.authentication.oauth.clientId": "1234567890",
        "connector.authentication.oauth.clientSecret":"ABC12345",
        "connector.authentication.oauth.myDomain":"MyDomainName",
        "connector.authentication.username":"user1@force.com",
        "connector.authentication.password":"abcdef1234",
        "ingestionType":"incremental",
        "writeMode":"WRITE_MODE_UPSERT",
        "watermarkColumns":["SystemModstamp","CreatedDate"]
        "primaryKeys":[['Id'], ['master_label','type']]}'

API

請使用 projects.locations.transferConfigs.create 方法，並提供 TransferConfig 資源的執行個體。

儲存移轉設定後，Salesforce 連接器會根據排程選項自動觸發移轉作業。每次執行移轉作業時，Salesforce 連接器都會將 Salesforce 中的所有可用資料移轉至 BigQuery。

如要手動執行資料轉移 (不在排程內)，可以啟動回填作業。

排解轉移設定問題

如果您無法順利設定資料移轉作業，請參閱「Salesforce 移轉問題」。

後續步驟