The Data Manager API is in closed beta. To express interest in joining the closed beta, fill out this form.

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

傳送事件

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

事件資料是代碼轉換的額外資料來源，可盡量爭取廣告互動信號，並強化資料和整體成效。

選擇要查看的指南版本：

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

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

準備目的地

傳送資料前，請先準備好資料傳送目的地。以下是可供使用的 Destination 範例：

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }

將 accountId 的 operatingAccount 設為接收事件資料的 Google Ads 帳戶 ID。operatingAccount 的 product 必須是 GOOGLE_ADS。
將 productDestinationId 設為事件的轉換動作 ID。轉換動作必須是 Google Ads 轉換動作，且type設為 WEBPAGE。

本指南說明如何建構要求，將每個事件傳送至相同的轉換動作。如要在同一個要求中傳送多個轉換動作的事件，請參閱多個目的地。

準備活動資料

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

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

以下是第一個事件的資料：

活動 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`John`
`last_name`	`Smith-Jones`
`region_code`	`us`
`postal_code`	`94045`

以下是第二個事件的資料：

活動 2
`conversion_time`	`June 10, 2025 11:42:33PM America/New_York`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`eur`
`gclid`	`GCLID_2`
`emails`	`zoe@EXAMPLE.COM` `cloudy.sanfrancisco@gmail.com`
`given_name`	`zoë`
`last_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

設定資料格式

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

活動 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`john`
`last_name`	`smith-jones`
`region_code`	`US`
`postal_code`	`94045`

以下是格式化後的第二個事件資料：

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`zoe@example.com` `cloudysanfrancisco@gmail.com`
`given_name`	`zoë`
`last_name`	`pérez`
`region_code`	`PT`
`postal_code`	`1229-076`

雜湊並編碼資料

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

活動 #1
`conversion_time`	`2025-06-10 15:07:01-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`ABC798654321`
`conversion_value`	`1.99`
`currency`	`USD`
`gclid`	`GCLID_1`
`emails`
`given_name`	`96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A`
`last_name`	`DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081`
`region_code`	`US`
`postal_code`	`94045`

以下是第二個事件的資料，經過格式化、雜湊處理，並使用十六進位編碼編碼：

活動 2
`conversion_time`	`2025-06-10T23:42:33-05:00`
`conversion_action_id`	`123456789`
`transaction_id`	`DEF999911111`
`conversion_value`	`3.25`
`currency`	`EUR`
`gclid`	`GCLID_2`
`emails`	`3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250` `223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4`
`given_name`	`2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450`
`last_name`	`6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F`
`region_code`	`PT`
`postal_code`	`1229-076`

將資料轉換為 `Event`

將每個事件的格式化和雜湊處理資料轉換為 Event。填寫下列必填欄位：

timestamp：事件發生時間。
transaction_id：事件的專屬 ID。
event_source：事件來源。如要指定，必須為 EVENT_SOURCE_WEB。
ad_identifiers 或 user_data：事件必須包含廣告 ID 或使用者資料。如果活動同時有這兩項資料，請一併傳送。

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

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

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "currency": "EUR",
   "timestamp": "2025-06-10T23:42:33-05:00",
   "transactionId": "DEF999911111",
   "eventSource": "EVENT_SOURCE_WEB",
   "userData": {
      "userIdentifiers": [
         {
            "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
         },
         {
            "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
         },
         {
            "address": {
              "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
              "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
              "regionCode": "PT",
              "postalCode": "1229-076"
            }
         }
      ]
   }
}

建構要求主體

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

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "timestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "lastName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "currency": "EUR",
       "timestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "EVENT_SOURCE_WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "lastName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}

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

傳送要求

使用範本右上角的複製按鈕，複製要求主體。
前往events.ingest頁面。
按一下右側的「API」按鈕，然後按一下展開部分中的「立即試用！」按鈕。
將複製的要求主體貼到「Request body」方塊。
按一下「執行」按鈕，完成授權提示，然後查看回覆。

成功回應

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

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

失敗回應

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

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

{
  "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"
          }
        ]
      }
    ]
  }
}

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

{
  "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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

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

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

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

後續步驟

設定驗證，並透過用戶端程式庫設定環境。
瞭解各類型資料的格式、雜湊和編碼規定。
瞭解如何加密使用者資料。

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