本頁面由 Cloud Translation API 翻譯而成。

傳送事件

您可以完成本快速入門導覽課程，熟悉如何傳送事件資料。

在下列任一情境中，使用資料管理工具 API：

將 Google Ads 代碼轉換或 Google Analytics 重要事件做為代碼轉換的額外資料來源，提升廣告互動信號、強化資料和整體成效。

這項功能僅適用於許可清單中的帳戶。如有意新增 Google Ads 帳戶或 Google Analytics 資源，請填寫表單。

注意： 在 14 天試用期內，您連結的其他資料來源資料不會流向轉換出價。此限制不適用於現有的 Google 代碼資料來源。
傳送 Google Ads 離線轉換或待開發客戶強化轉換的事件資料。

選擇要查看的指南版本：

在本快速入門導覽課程中，您將完成下列步驟：

準備 Destination 接收事件資料。
準備要傳送的事件資料。
為事件建立 IngestionService 要求。
使用 Google APIs Explorer 傳送要求。
瞭解成功和失敗的回應。

準備目的地

您必須先準備至少一個Destination，才能傳送資料。以下是可供使用的 Destination 範例：

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

Destination 的欄位如下：

operatingAccount

接收事件的帳戶。

如果是以額外資料來源傳送的事件，作業帳戶可以是 Google Ads 帳戶或 Google Analytics 資源。將 accountType 設為 GOOGLE_ADS 或 GOOGLE_ANALYTICS_PROPERTY，並將 accountId 設為 Google Ads 客戶 ID 或 Google Analytics 資源 ID。如果 accountType 是 GOOGLE_ANALYTICS_PROPERTY，則要求憑證必須是 Google Analytics 使用者，且該使用者具備資源的編輯者或管理員角色。

如果是離線轉換和待開發客戶強化轉換，作業帳戶必須是 Google Ads 帳戶，因此請將 accountType 設為 GOOGLE_ADS，並將 accountId 設為 Google Ads 客戶 ID。

loginAccount

使用者可存取憑證的帳戶。

如果 OAuth 憑證適用於可存取Google Ads 管理員帳戶的使用者，且該帳戶將 operatingAccount 設為子帳戶，則必須提供 loginAccount。將 loginAccount 的 accountId 設為管理員帳戶的 ID，並將 loginAccount 的 accountType 設為 GOOGLE_ADS。

如果 OAuth 憑證適用於可直接存取 operatingAccount 的使用者，則不需要設定 loginAccount，系統會預設為 operatingAccount。不過，建議您將 loginAccount 設為與 operatingAccount 相同的 accountId 和 accountType。如果使用者可存取的帳戶組合有所變更，這樣做有助於避免發生問題。

productDestinationId

接收事件的 operatingAccount 中實體的 ID。

如果是以額外資料來源傳送的事件，productDestinationId必須是 Google Ads 轉換 ID，且type設為 WEBPAGE，或是 Google Analytics 網站資料串流的評估 ID。您無法將事件做為額外資料來源，傳送至 Google Analytics iOS 應用程式或 Android 應用程式串流。

如果是離線轉換或待開發客戶強化轉換，則 productDestinationId 必須是 Google Ads 轉換動作的 ID，且 type 設為 UPLOAD_CLICKS。

本指南中的範例說明如何建構要求，將所有事件傳送至相同目的地。如要在同一個要求中傳送多個目的地的事件，請參閱「傳送多個目的地的事件」。

準備事件資料

請參考下列事件資料。每個表格都對應一個轉換事件。每個轉換事件都有事件的時間戳記、轉換動作和轉換價值。

每個事件可能都有廣告 ID (例如 gclid) 或使用者 ID (例如電子郵件地址、電話號碼和地址資訊)。事件也可以包含：

在事件發生時評估使用者相關資訊，例如顧客價值，或是新顧客、回訪顧客或重新參與的顧客。
購物車資料。
目的地適用的其他事件參數或使用者屬性，例如 Google Analytics 的 client_id 或 user_id。

以下是活動資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`family_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

設定資料格式

按照格式設定指南的規定設定欄位格式。以下是格式化後的事件資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`family_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`family_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

雜湊並編碼資料

此外，格式化的電子郵件地址、名字和姓氏必須使用 SHA-256 演算法進行雜湊處理，並使用十六進位或 Base64 編碼。以下是經過格式化、雜湊處理和編碼 (使用十六進位編碼) 的事件資料：

事件 1

活動 #1
`conversion_time`	`2025-06-10T15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`30.03`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`family_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`
`customer_type`	`NEW`
`customer_value_bucket`	`HIGH`
`client_id`	`1234567890.1761581763`
`user_id`	`user_ABC12345`
`ad_unit_name`	`Banner_01`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12345`
`item_name`	`Stan and Friends Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`2.22`
`item_index`	`0`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`10.01`
`item_quantity`	`3`

事件 2

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`42.02`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`family_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`
`customer_type`	`RETURNING`
`client_id`	`9876543210.1761582117`
`user_id`	`user_DEF9876`
`ad_unit_name`	`Banner_02`
`event_name`	`purchase`
購物車商品
`item_id`	`SKU_12346`
`item_name`	`Google Grey Women's Tee`
`item_affiliation`	`Google Merchandise Store`
`item_coupon`	`SUMMER_FUN`
`item_discount`	`3.33`
`item_index`	`1`
`item_brand`	`Google`
`item_category`	`Apparel`
`item_category2`	`Adult`
`item_category3`	`Shirts`
`item_category4`	`Crew`
`item_category5`	`Short sleeve`
`item_list_id`	`related_products`
`item_list_name`	`Related Products`
`item_price`	`21.01`
`item_quantity`	`2`

將資料轉換為 `Event` 物件

將每個事件的格式化和雜湊處理資料轉換為 Event。按照指示填入下列欄位：

將 eventTimestamp 設為事件發生的時間。

Google Analytics 事件的 eventTimestamp 必須在過去 72 小時內。

根據用途設定必填欄位。

用途	ID	`transactionId`	`eventSource`
離線轉換或待開發客戶強化轉換	必填。設定至少下列其中一項： `adIdentifiers` 至少設為 `gclid`、`gbraid`、`wbraid` 或 `sessionAttributes` `userData`	選用	必填。設為 `EventSource` 的其中一個列舉值。
傳送至 Google Ads 目的地做為額外資料來源的事件	必填。設定至少下列其中一項： `adIdentifiers` 至少設為 `gclid`、`gbraid` 或 `wbraid` `userData`	必要	(選用步驟) 如要設定，必須為 `WEB`。
傳送至 Google Analytics 目的地的事件，做為額外資料來源	必填。設定至少下列其中一項： `clientId` `adIdentifiers` 已設定 `gclid` `userData`	必要	(選用步驟) 如要設定，必須為 `WEB`。

填入您有事件值的任何其他欄位。如需可用欄位的完整清單，請參閱 Event 參考說明文件。

新增 Google Analytics 資訊

如果以額外資料來源傳送的事件目的地包含 Google Analytics 資源，請按照指示填寫下列欄位：

eventName

必填。Google Analytics 事件的名稱。

transactionId

必要。事件的專屬 ID。

至少一個 ID

必須設定下列至少一個欄位：

clientId：網頁用戶端使用者執行個體的專屬 ID。請參閱「將事件傳送至 Measurement Protocol」。
adIdentifiers.gclid：Google 點擊 ID。
userData：使用者的 ID，例如電子郵件地址、電話號碼或地址資訊。

destinationReferences

如果要求層級的 destinations 清單包含多個 Google Analytics Destination，則為必填。在 destinationReferences 中新增項目，指定應接收事件的 Google Analytics 目的地。如要進一步瞭解目的地參照，請參閱「將事件傳送至多個目的地」。

如果未設定 destinationReferences，或有多個參照 Google Analytics 目的地的項目，Data Manager API 會拒絕事件，並傳回 MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT 錯誤。

userId

(選用步驟) 使用者的 User-ID。

additionalEventParameters

(選填，但建議使用) 填入這份清單時，請使用其他 Event 欄位未擷取的任何 Google Analytics 事件參數。參數可包含purchase事件中的其他建議參數，或您想擷取的其他參數。使用 EventParameter 的 parameterName 的 Google Analytics 參數名稱。

舉例來說，如果交易有相關稅金，請在 additionalEventParameters 中新增項目，並將 parameterName 設為 tax，以及將 value 設為稅金費用。

我們不建議為 transactionId、currency 或 value Google Analytics 事件參數新增項目。請改為填入 Event 的 transactionId、currency 和 conversionValue，這些屬性的優先順序高於 additionalEventParameters 中的任何項目。

為購買事件新增購物車資料

在 Event 的 cartData 欄位中，填入購買的商品資訊。為每項購買的商品，在 CartData 的 items 清單中新增 Item 物件，並填入下列欄位：

itemId

必要。商品的專屬 ID。

unitPrice

必填。此為單位價格，不含稅金、運費和事件範圍 (交易層級) 折扣。

如果商品有商品範圍折扣，請使用折扣單價。舉例來說，如果商品的單價為 27.67，單價折扣為 6.66，則請將 unitPrice 設為 21.01。

quantity

必填。這項商品購買的單位數。

additionalItemParameters

請使用其他 Item 欄位未擷取的任何項目範圍參數填入這份清單。使用 ItemParameter 的 Google Analytics 項目參數名稱。parameterName

舉例來說，如果項目有品牌和類別，請在項目的 additionalItemParameters 中新增項目，並將 parameterName 設為 item_brand，將 value 設為品牌名稱；另一個項目則將 parameterName 設為 item_category，將 value 設為項目的類別。

我們不建議為 quantity、price 或 item_id Google Analytics 項目參數新增項目。請改為填入 Item 的 itemId、unitPrice 和 quantity，這些屬性的優先順序高於 additionalItemParameters 中的任何項目。

以下是第二個事件中，經過格式化、雜湊處理和編碼的資料範例 Event，以及 Google Analytics 的額外資料：

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

建立要求主體

將 Destination 和 Events 合併為要求主體：

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

更新主體中的預留位置，例如 OPERATING_ACCOUNT_ID 和 PRODUCT_DESTINATION_ID，並填入帳戶和目的地的相關值。
將 validateOnly 設為 true，即可驗證要求，但不會套用變更。準備好套用變更時，請將 validateOnly 設為 false。
請注意，這個範例並未使用加密。

傳送要求

使用範本右上角的複製按鈕，複製要求主體。
按一下工具列中的「API」按鈕。
將複製的要求主體貼到「要求主體」方塊。
按一下「執行」按鈕，完成授權提示，然後查看回覆。

成功回應

如果要求成功，回應會傳回包含 requestId 的物件。

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

記錄傳回的 requestId，以便在處理要求中的每個目的地時，擷取診斷資訊。

失敗回應

如果要求失敗，系統會傳回錯誤回應狀態碼 (例如 400 Bad Request)，以及含有錯誤詳細資料的回應。

舉例來說，如果 emailAddress 包含純文字字串，而非十六進位編碼值，則會產生下列回應：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

未經過雜湊處理且僅經過十六進位編碼的 emailAddress 會產生下列回應：

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

將事件傳送至多個目的地

如果資料包含不同目的地的事件，您可以使用目的地參照，在同一個要求中傳送這些事件。

舉例來說，如果您有轉換動作 ID 123456789 的事件，以及轉換動作 ID 777111122 的另一個事件，請設定每個 Destination 的 reference，在單一要求中傳送這兩個事件。reference 是由使用者定義。唯一規定是每個 Destination 都有專屬的 reference。以下是要求的修改後 destinations 清單：

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

設定每個 Event 的 destinationReferences，將其傳送至一或多個特定目的地。舉例來說，以下 Event 只適用於第一個 Destination，因此其 destinationReferences 清單只包含第一個 Destination 的 reference：

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

destinationReferences 欄位是清單，因此您可以為事件指定多個目的地。如果未設定 Event 的 destinationReferences，Data Manager API 會將事件傳送至要求中的所有目的地。

如果事件有多個目的地，Data Manager API 會將相關欄位傳送至每個目的地。舉例來說，如果事件有 Google Ads 目的地和 Google Analytics 目的地，當 API 將事件傳送至 Google Analytics 目的地時，會加入 Google Analytics 欄位，例如 clientId 或 eventName；當 API 將事件傳送至 Google Ads 目的地時，則會加入 Google Ads 欄位，例如 customVariables。

後續步驟

設定驗證，並透過用戶端程式庫設定環境。
瞭解各類型資料的格式、雜湊和編碼規定。
瞭解如何加密使用者資料。
瞭解如何擷取要求診斷資訊。
瞭解最佳做法。
瞭解限制和配額。

事件總覽

傳送事件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

準備目的地

準備事件資料

事件 1

事件 2

設定資料格式

事件 1

事件 2

雜湊並編碼資料

事件 1

事件 2

將資料轉換為 Event 物件

新增 Google Analytics 資訊

為購買事件新增購物車資料

建立要求主體

傳送要求

成功回應

失敗回應

將事件傳送至多個目的地

後續步驟

傳送事件

將資料轉換為 `Event` 物件