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

將 operatingAccount 的 accountId 設為將接收事件資料的 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，將其傳送至一或多個特定目的地。舉例來說，以下是只適用於第一個 Destination 的 Event，因此其 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 的 destination_references，Data Manager API 會將事件傳送至要求中的所有目的地。

後續步驟

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

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