設定目的地

IngestAudienceMembersRequest 或 IngestEventsRequest 中的每個 Destination 定義：

1. 接收資料的帳戶。例如 Google Ads 帳戶或 Google Analytics 資源。
2. 帳戶中資料的目的地實體，例如 Google Ads 轉換動作或 Google Analytics 資料串流。
3. 要求憑證的存取路徑，該憑證可存取接收資料的帳戶。

如果您是廣告主或代理商，請參閱「廣告主情境」一節，瞭解如何建構Destination：

• Google Ads
• Display & Video 360
• Google Analytics

如果您是資料合作夥伴，請參閱資料合作夥伴情境，瞭解如何建構 Destination，將資料傳送至已連結產品的帳戶，並連結至您的資料合作夥伴帳戶：

• Google Ads
• Display & Video 360
• Google Analytics

「詳細規定」一節深入說明相關規定和驗證規則。

廣告主情境

以下說明如何為廣告主和代理商的常見情境設定 Destination。這張圖表說明 Data Manager API 如何使用憑證和 Destination 欄位存取廣告主帳戶。

Google Ads

下圖顯示一組 Google Ads 帳戶和使用者的範例。

管理員帳戶 M1

M1 有兩個直接子帳戶：

1. 管理員帳戶 M2
2. 客戶帳戶 C1

Google 帳戶「cloudysanfrancisco@gmail.com」是 M1 的使用者。

管理員帳戶 M2

M2 有兩個直接子帳戶：

1. 客戶帳戶 C1
2. 客戶帳戶 C2

Google 帳戶 baklavainthebalkans@gmail.com 是 M2 的使用者。

客戶帳戶 C1

C1 有兩個直接上層管理員帳戶：

1. 管理員帳戶 M1
2. 管理員帳戶 M2

Google 帳戶 jeffersonloveshiking@gmail.com 是 C1 的使用者。

客戶帳戶 C2

管理員帳戶 M2 是 C2 的唯一直接上層。

列出的 Google 帳戶都不是 C2 的使用者。

「直接存取情境」和「管理員存取情境」說明如何設定目的地，將資料傳送至這些帳戶。

直接存取情境

如要將資料傳送至 Google Ads 帳戶，且您的憑證適用於 Google Ads 帳戶的使用者 Google 帳戶：

以下是直接存取情境的範例，使用圖表中的帳戶和 Google 帳戶 jeffersonloveshiking@gmail.com 的憑證。

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"

      },
      "loginAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"

      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

管理員存取權情境

如要將資料傳送至 Google Ads 帳戶，而您的憑證適用於 Google Ads 管理員帳戶中的使用者 Google 帳戶，且廣告主帳戶是子帳戶：

以下是 Google Ads 客戶帳戶 C2 的管理員存取權情境範例 (請參閱圖表)，以及 Google 帳戶 baklavainthebalkans@gmail.com 的憑證：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "M2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

以下是另一個範例，說明 Google Ads 管理員帳戶 M1 的使用者 (Google 帳戶 cloudysanfrancisco@gmail.com) 如何存取 Google Ads 客戶帳戶 C2：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "M1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

Display & Video 360

您可以透過兩種方式將資料傳送至 Display & Video 360：

1. 直接存取：憑證適用於 Display & Video 360 廣告主或合作夥伴帳戶中的使用者 Google 帳戶。
2. Display & Video 360 夥伴存取權，其中憑證適用於 Google 帳戶，該帳戶是 Display & Video 360 夥伴帳戶中的使用者，而作業帳戶是夥伴帳戶下的 Display & Video 360 廣告主帳戶。

直接存取情境

如要將資料傳送至 Display & Video 360 廣告主帳戶，且您的憑證適用於廣告主帳戶中的使用者 Google 帳戶：

以下是Destination的範例，說明如何直接存取資料，並將資料傳送至 Display & Video 360 廣告主：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

同樣地，如要將資料傳送至 Display & Video 360 合作夥伴帳戶，且您的憑證適用於合作夥伴帳戶中的使用者 Google 帳戶：

以下是Destination的範例，說明如何直接存取資料，並將資料傳送至 Display & Video 360 合作夥伴：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "loginAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Display & Video 360 合作夥伴存取權情境

如要將資料傳送至 Display & Video 360 廣告主，且您的憑證適用於廣告主上層 Display & Video 360 合作夥伴帳戶中的使用者 Google 帳戶：

以下是夥伴存取情境的 Destination 範例，可將資料傳送至 Display & Video 360 廣告主。在這種情況下，憑證必須是 Google 帳戶的憑證，且該帳戶是 Display & Video 360 合作夥伴帳戶 PARTNER_ID 的使用者，而 Display & Video 360 廣告主帳戶 ADVERTISER_ID 必須是合作夥伴帳戶 PARTNER_ID 的子項。

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Google Analytics

注意：如果目的地是 Google Analytics 帳戶，operating_account 和 login_account 必須相同。否則要求會失敗，並顯示 OPERATING_ACCOUNT_LOGIN_ACCOUNT_MISMATCH 錯誤。

以下是Destination的範例，說明如何將事件傳送至 Google Analytics：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "PROPERTY_ID",
        "accountType": "GOOGLE_ANALYTICS_PROPERTY"
      },
      "loginAccount": {
        "accountId": "PROPERTY_ID",
        "accountType": "GOOGLE_ANALYTICS_PROPERTY"
      },
      "productDestinationId": "MEASUREMENT_ID"
    }
  ]
}

資料合作夥伴情境

以下說明如何為資料合作夥伴設定 Destination，以便將資料傳送至已建立產品連結的廣告主帳戶。

這張圖表說明資料管理工具 API 如何使用憑證和 Destination 欄位，透過產品連結存取廣告主帳戶。

Google Ads

下圖顯示一組 Google Ads 和資料合作夥伴帳戶的範例。這張圖表也會顯示每個 Google Ads 或資料合作夥伴帳戶中的使用者所用的 Google 帳戶，以及帳戶之間的產品連結。

資料合作夥伴 D1

D1 和 Google Ads 管理員帳戶 M2 之間存在產品連結。

Google 帳戶 222larabrown@gmail.com 是 D1 的使用者。

資料合作夥伴 D2

D2 與 Google Ads 客戶帳戶 C1 之間存在產品連結。

Google 帳戶 jeffersonloveshiking@gmail.com 是 D2 的使用者。

管理員帳戶 M1

M1 有兩個直接子帳戶：

1. 管理員帳戶 M2
2. 客戶帳戶 C1

管理員帳戶 M2

M2 有兩個直接子帳戶：

1. 客戶帳戶 C1
2. 客戶帳戶 C2

客戶帳戶 C1

C1 有兩個直接上層管理員帳戶：

1. 管理員帳戶 M1
2. 管理員帳戶 M2

客戶帳戶 C2

管理員帳戶 M2 是 C2 的唯一直接上層。

這組帳戶的用途如下：

以資料合作夥伴 D1 身分執行作業

如要擔任資料合作夥伴 D1，請使用 Google 帳戶 222larabrown@gmail.com 的憑證，透過目的地將資料傳送至管理員帳戶 M2、客戶帳戶 C1 或客戶帳戶 C2，並將 login_account 設為資料合作夥伴帳戶 D1，linked_account 設為管理員帳戶 M2。

資料合作夥伴 D1 無法將資料傳送至管理員帳戶 M1，因為 D1 和 M1 之間沒有產品連結。

以資料合作夥伴 D2 身分執行作業

如要擔任資料合作夥伴 D2，請使用 Google 帳戶的憑證 jeffersonloveshiking@gmail.com，透過目的地將資料傳送至客戶帳戶 C1，並將 login_account 設為資料合作夥伴帳戶 D2，以及將 linked_account 設為客戶帳戶 C1。

資料合作夥伴 D2 無法將資料傳送至管理員帳戶 M1、管理員帳戶 M2 或客戶帳戶 C2，因為 D2 與這些帳戶或其上層管理員帳戶之間沒有產品連結。

資料合作夥伴 D1 和 D2 的主要差異在於資料合作夥伴與 Google Ads 帳戶的連結方式。

• 資料合作夥伴 D1 已連結至 Google Ads 管理員帳戶。這是管理員產品連結情境的範例。
• 資料合作夥伴 D2 已連結至 Google Ads 客戶帳戶。這是直接產品連結情境的範例。

直接產品連結情境

如要將資料傳送至 Google Ads 帳戶，且產品連結位於 Google Ads 帳戶和資料合作夥伴帳戶之間：

以下是使用圖表中帳戶的直接產品連結情境範例。在這個情境中，資料合作夥伴 D2 會使用 D2 和 C1 之間的產品連結，以及 Google 帳戶 jeffersonloveshiking@gmail.com 的憑證，將目標對象成員資料傳送給 Google Ads 客戶 C1：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C1_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "D2_CUSTOMER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

管理員產品連結情境

如要將資料傳送至 Google Ads 帳戶，且產品連結位於父項 Google Ads 管理員帳戶和資料合作夥伴帳戶之間，請按照下列步驟操作：

以下是使用圖表中帳戶的管理員產品連結情境範例。在這種情況下，資料合作夥伴 D1 會使用 D1 和 M2 之間的產品連結，以及 Google 帳戶 222larabrown@gmail.com 的憑證，將目標對象成員資料傳送給 Google Ads 客戶 C2：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "C2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "loginAccount": {
        "accountId": "D1_CUSTOMER_ID",
        "accountType": "DATA_PARTNER"
      },
      "linkedAccount": {
        "accountId": "M2_CUSTOMER_ID",
        "accountType": "GOOGLE_ADS"
      },
      "productDestinationId": "USER_LIST_ID"
    }
  ]
}

Display & Video 360

資料合作夥伴可以透過兩種方式，將資料傳送至 Display & Video 360 帳戶：

1. 在資料合作夥伴帳戶與 Display & Video 360 合作夥伴或廣告主帳戶之間使用直接產品連結。
2. 透過資料夥伴帳戶與廣告主上層 Display & Video 360 夥伴帳戶之間的產品連結，將資料傳送給 Display & Video 360 廣告主。

直接產品連結情境

如要將資料傳送至 Display & Video 360 廣告主，且產品連結位於 Display & Video 360 廣告主帳戶和資料合作夥伴帳戶之間：

以下是直接產品連結情境的 Destination 範例，可將資料傳送給 Display & Video 360 廣告主：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

如要將資料傳送至 Display & Video 360 合作夥伴帳戶，您必須在 Display & Video 360 合作夥伴帳戶和資料合作夥伴帳戶之間建立產品連結。

以下是Destination的範例，適用於直接產品連結情境，可將資料傳送給 Display & Video 360 合作夥伴：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "DISPLAY_VIDEO_PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Display & Video 360 合作夥伴產品連結情境

如要將資料傳送至 Display & Video 360 廣告主，且產品連結至資料合作夥伴帳戶時，是透過廣告主帳戶為子帳戶的 Display & Video 360 合作夥伴帳戶，請按照下列步驟操作：

以下是Destination的範例，說明如何透過資料合作夥伴與廣告主上層 Display & Video 360 合作夥伴之間的產品連結，將資料傳送給 Display & Video 360 廣告主：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountId": "DISPLAY_VIDEO_ADVERTISER_ID",
        "accountType": "DISPLAY_VIDEO_ADVERTISER"
      },
      "loginAccount": {
        "accountId": "DATA_PARTNER_ID",
        "accountType": "DATA_PARTNER"
      },
      "linkedAccount": {
        "accountId": "DISPLAY_VIDEO_PARTNER_ID",
        "accountType": "DISPLAY_VIDEO_PARTNER"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ]
}

Google Analytics

Data Manager API 不支援使用產品連結將資料傳送至 Google Analytics 帳戶。請改用 Google Analytics 的廣告主情境方法。

詳細規定

本節詳細說明 Destination 的帳戶欄位規定、設定 product_destination_id 的訣竅，以及如何判斷憑證的存取權範圍。

帳戶欄位

一個 Destination 最多可有 3 個不同帳戶：

operating_account

operating_account為必填欄位。

operating_account 會指出要求中的資料接收帳戶。operating_account 可以是下列任一值：

• Google Ads 帳戶
• Display & Video 360 廣告主帳戶
• Display & Video 360 合作夥伴帳戶
• Google Analytics 資源
• 如要將資料傳送至資料合作夥伴帳戶擁有的目標對象，則需要資料合作夥伴帳戶。

login_account

login_account 並非一律必填，預設為 operating_account。

Data Manager API 會驗證下列事項：

1. 憑證的 Google 帳戶是 login_account 中的使用者。

2. login_account 是下列其中一項：

   • 與 operating_account 相同。如果未設定 login_account，系統會預設為這個值。

   • Google Ads 管理員或 Display & Video 360 合作夥伴帳戶，是 operating_account 的上層帳戶。

   • 資料合作夥伴帳戶，且產品連結至 linked_account。

linked_account

linked_account 表示哪個帳戶有產品連結至 login_account。

產品目的地 ID

Destination 的 product_destination_id 會識別 operating_account 中接收資料的物件。例如 Google Ads 或 Display & Video 360 的目標對象 ID、Google Ads 的轉換動作 ID，或是 Google Analytics 資料串流的評估 ID。

以下說明如何找出各類型產品目的地的 ID。

Google Ads 目標對象

如要匯入目標對象成員，產品目的地 ID 就是目標對象 ID。

如要透過 Google Ads 使用者介面取得目標對象 ID，請按照下列步驟操作：

1. 前往 Google Ads 使用者介面中的目標對象管理工具。
2. 按一下目標對象名稱即可查看詳細資料。
3. 目標對象 ID 會列在「名單 ID」旁邊。

如要透過 Google Ads API 取得目標對象 ID，請按照下列步驟操作：

1. 向 GoogleAdsService 傳送 Search 或 SearchStream 要求，並附上下列查詢：

   SELECT
     user_list.id,
     user_list.name
   FROM user_list
   WHERE user_list.name = 'USER_LIST_NAME'
   

2. 從回應中 user_list 的 id 欄位取得目標對象 ID。

   [
     {
       "results": [
         {
           "userList": {
             "resourceName": "customers/CUSTOMER_ID/userLists/USER_LIST_ID",
             "id": "USER_LIST_ID",
             "name": "USER_LIST_NAME"
           }
         }
       ]
     }
   ]
   

Google Ads 事件

如要匯入事件，產品目的地 ID 就是轉換動作 ID。

如要透過 Google Ads 使用者介面取得轉換動作 ID，請按照下列步驟操作：

1. 前往 Google Ads 使用者介面的「轉換」。
2. 按一下轉換動作名稱即可查看詳細資料。

3. 轉換動作 ID 是名為 ctId 的網址查詢參數值。

   https://ads.google.com/aw/conversions/detail?ocid=...&ctId=CONVERSION_ACTION_ID&...
   

如要透過 Google Ads API 取得轉換動作 ID，請按照下列步驟操作：

1. 向 GoogleAdsService 傳送 Search 或 SearchStream 要求，並附上下列查詢：

   SELECT
     conversion_action.id,
     conversion_action.name
   FROM conversion_action
   WHERE conversion_action.name = 'CONVERSION_ACTION_NAME'
   

2. 從回應中 conversion_action 的 id 欄位取得轉換動作 ID。

   [
     {
       "results": [
         {
           "conversionAction": {
             "resourceName": "customers/CUSTOMER_ID/conversionActions/CONVERSION_ACTION_ID",
             "id": "CONVERSION_ACTION_ID",
             "name": "CONVERSION_ACTION_NAME"
           }
         }
       ]
     }
   ]
   

Display & Video 360 目標對象

如要匯入目標對象成員，產品目的地 ID 就是目標對象 ID。

如要透過 Display & Video 360 使用者介面取得目標對象 ID，請按照下列步驟操作：

1. 前往 https://displayvideo.google.com 登入 Display & Video 360 使用者介面。
2. 前往您用於operating_account的 Display & Video 360 合作夥伴或廣告主。
3. 前往左選單中的「目標對象」，然後選取「所有目標對象」。
4. 在清單中找出目標對象。目標對象 ID 是「名稱」欄中名稱旁邊的數字。

Google Analytics 事件

如要擷取事件，產品目的地 ID 是資料串流的評估 ID。

判斷憑證的存取權

您用來授權 Data Manager API 要求的憑證會與特定 Google 帳戶建立關聯。

• 如果您使用使用者憑證，系統會將要求授權為使用者 Google 帳戶，而該使用者在您產生憑證時，已授權您代表他們執行動作。
• 如果您使用服務帳戶憑證，系統會將要求授權為服務帳戶的 Google 帳戶。

請按照下列步驟，確認您用來登入的 Google 帳戶是否具有 Google Ads、Display & Video 360 或 Google Analytics 帳戶的存取權。

Google Ads 或資料合作夥伴

1. 在 Google Ads 使用者介面中，前往 login_account 的「存取權和安全性」。
2. 選取 [Users] (使用者) 分頁標籤。
3. 如果 login_account 是 Google Ads 管理員帳戶，請關閉「以完整階層顯示使用者」切換按鈕，隱藏子帳戶的使用者。
4. 確認憑證的 Google 帳戶位於「使用者」分頁中顯示的帳戶清單。

Display & Video 360

1. 在 Display & Video 360 使用者介面中，前往「使用者管理和電子郵件接收設定」。
2. 確認「使用者管理」顯示憑證的 Google 帳戶是 login_account 的使用者。

Google Analytics

1. 前往 Google Analytics 使用者介面的「資源存取管理」。
2. 確認已選取 login_account 中指定的 Google Analytics 資源。
3. 確認您用來建立憑證的 Google 帳戶是否具備資源的「編輯者」或「管理員」角色。