Mapowanie pól

Użyj mapowań w tabelach, aby zmapować metody i pola interfejsu Google Ads API na ich odpowiedniki w IngestEventsRequest w interfejsie Data Manager API.

Uwierzytelnianie

Interfejs Data Manager API wymaga danych logowania o innym zakresie niż interfejs Google Ads API. Aby wygenerować nowe dane logowania, które obejmują zakres interfejsu Data Manager API, wykonaj czynności opisane w artykule Konfigurowanie dostępu do interfejsu API.

Metody interfejsu API

Interfejs Data Manager API umożliwia przesyłanie każdej partii zdarzeń sprzedaży w sklepie w jednym pliku IngestEventsRequest.

W interfejsie Google Ads API wymagało to natomiast wykonania 3 czynności za pomocą metody OfflineUserDataJobService:

  1. Utwórz zadanie za pomocą CreateOfflineUserDataJob
  2. Dodaj operacje do zadania za pomocą AddOfflineUserDataJobOperations.
  3. Uruchom zadanie za pomocą RunOfflineUserDataJob.

Pola żądania

Każdy IngestEventsRequest podlega limitom żądań. Jeśli liczba operacji w żądaniu AddOfflineUserDataJobOperations przekracza te limity, musisz podzielić je na kilka żądań pozyskiwania danych przez interfejs Data Manager API.

Oto jak pola żądań interfejsu Google Ads API są mapowane na interfejs Data Manager API.

CreateOfflineUserDataJobRequest

Tabela poniżej pokazuje, jak pola CreateOfflineUserDataJobRequest są mapowane na IngestEventsRequest.

CreateOfflineUserDataJobRequest (interfejs Google Ads API) IngestEventsRequest (interfejs Data Manager API) Uwagi
customer_id destinations.operating_account Zobacz Pola klienta i działania powodującego konwersję.
  • Nagłówek żądania developer-token
  • Nagłówek żądania login-customer_id
  • Nagłówek żądania linked-customer-id
 destinations Zobacz Pola klienta i działania powodującego konwersję.
  • job.status
  • job.failure_reason
 Diagnostyka Użyj parametru request_id zwróconego w IngestEventsResponse, aby pobrać informacje diagnostyczne dotyczące przesłanych konwersji.
job.id request_id Użyj parametru request_id zwróconego w IngestEventsResponse, aby pobrać informacje diagnostyczne dotyczące przesłanych konwersji.
job.external_id Brak odpowiednika
job.type Brak odpowiednika
job.store_sales_metadata.third_party_metadata.partner_id destinations.login_account Dostawca danych, który przesyła konwersje polegające na sprzedaży w sklepie stacjonarnym, będzie identyfikowany przez login_account miejsca docelowego. Więcej informacji znajdziesz w artykule Konfigurowanie miejsc docelowych.
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time Brak odpowiednika
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction Brak odpowiednika
job.store_sales_metadata.third_party_metadata.partner_match_fraction Brak odpowiednika
job.store_sales_metadata.third_party_metadata.partner_upload_fraction Brak odpowiednika
job.store_sales_metadata.third_party_metadata.bridge_map_version_id Brak odpowiednika
job.store_sales_metadata.loyalty_fraction Brak odpowiednika
job.store_sales_metadata.transaction_upload_fraction Brak odpowiednika
job.store_sales_metadata.custom_key
  • events[].custom_variables[].variable
  • events[].cart_data.items[].custom_variables[].variable
 Mapuj na pole variable obiektu CustomVariable na poziomie zdarzenia lub obiektu ItemCustomVariable na poziomie produktu.
enable_match_rate_range_preview Brak odpowiednika
validate_only validate_only
Brak odpowiednika consent Interfejs Google Ads API obsługuje tylko określanie parametru consent na poziomie zdarzenia w obiekcie UserData. W przypadku interfejsu Data Manager API możesz określić zgodę na wszystkie zdarzenia w żądaniu, ustawiając pole consent w IngestEventsRequest. Możesz zastąpić tę wartość w przypadku pojedynczego zdarzenia, ustawiając pole consent w Event.
Brak odpowiednika encoding Wymagany w przypadku przesyłania UserData. Ustaw Encoding używany dla wartości UserIdentifier.
Brak odpowiednika encryption_info Ustaw, jeśli żądanie zawiera zaszyfrowane identyfikatory użytkowników UserData. Szczegółowe informacje znajdziesz w artykule Szyfrowanie.

AddOfflineUserDataJobOperationsRequest

Tabela poniżej pokazuje, jak pola AddOfflineUserDataJobOperationsRequest są mapowane na IngestEventsRequest.

AddOfflineUserDataJobOperationsRequest (interfejs Google Ads API) IngestEventsRequest (interfejs Data Manager API) Uwagi
  • Nagłówek żądania developer-token
  • Nagłówek żądania login-customer_id
  • Nagłówek żądania linked-customer-id
 destinations Zobacz Pola klienta i działania powodującego konwersję.
resource_name Brak odpowiednika Interfejs Data Manager API nie wymaga aktualizowania zasobu zadania.
enable_partial_failure Brak odpowiednika Jeśli IngestEventsRequest zakończy się powodzeniem, wszelkie błędy, które wystąpią podczas przetwarzania na dalszych etapach, są obsługiwane na poziomie zdarzenia, co może skutkować częściowym powodzeniem. Użyj Diagnostyki, aby sprawdzić stan przesyłania oraz błędy i ostrzeżenia dotyczące poszczególnych zdarzeń. Jeśli IngestEventsRequest nie powiedzie się (np. z powodu BadRequest), żadne zdarzenia nie zostaną przetworzone. Musisz rozwiązać problem i ponownie wysłać żądanie. Więcej informacji znajdziesz w artykule Informacje o błędach interfejsu API.
enable_warnings Brak odpowiednika Aby uzyskać ostrzeżenia dotyczące żądania do interfejsu Data Manager API, użyj narzędzia Diagnostyka. Nie musisz tego włączać.
operations events Operacja OfflineUserDataJobOperation.create jest równoważna wysłaniu IngestEventsRequest. Interfejs Data Manager API nie obsługuje usuwania zdarzeń.
validate_only validate_only
Brak odpowiednika consent Interfejs Google Ads API obsługuje tylko określanie parametru consent na poziomie zdarzenia w obiekcie UserData. W przypadku interfejsu Data Manager API możesz określić zgodę na wszystkie zdarzenia w żądaniu, ustawiając pole consent w IngestEventsRequest. Możesz zastąpić tę wartość w przypadku pojedynczego zdarzenia, ustawiając pole consent w Event.
Brak odpowiednika encoding Wymagany w przypadku przesyłania UserData. Ustaw Encoding używany dla wartości UserIdentifier.
Brak odpowiednika encryption_info Ustaw, jeśli żądanie zawiera zaszyfrowane identyfikatory użytkowników UserData. Szczegółowe informacje znajdziesz w artykule Szyfrowanie.

Pola klienta i działania powodującego konwersję

Interfejs Google Ads API wymaga nagłówka żądania developer-token, a nagłówki żądania login-customer-id i linked-customer-id ustawiasz w przypadku różnych scenariuszy uwierzytelniania.

Interfejs Data Manager API nie wymaga tokena programisty, a informacje o logowaniu i połączonym kliencie podajesz za pomocą pól Destination, a nie nagłówków żądań. Więcej informacji o miejscach docelowych znajdziesz w artykule Konfigurowanie miejsc docelowych.

Interfejs Google Ads API Destination (interfejs Data Manager API) Uwagi
customer_id prośby operating_account Ustaw account_id na identyfikator klienta konta konwersji Google Ads. Ustaw wartość account_type zasobu operating_account na GOOGLE_ADS.
Nagłówek żądania developer-token Brak odpowiednika Token programisty nie jest wymagany w przypadku interfejsu Data Manager API.
Nagłówek żądania login-customer-id login_account Ustaw account_id na identyfikator klienta konta logowania. Ustaw parametr account_type na GOOGLE_ADS, jeśli konto logowania jest kontem Google Ads, lub na DATA_PARTNER, jeśli konto logowania jest kontem dostawcy danych.
Nagłówek żądania linked-customer-id linked_account Jeśli uzyskujesz dostęp do operating_account za pomocą linku partnera, ustaw account_id na identyfikator klienta połączonego konta, a account_type na DATA_PARTNER. W przeciwnym razie nie ustawiaj pola linked_account.
conversion_action product_destination_id Ustaw identyfikator numeryczny działania powodującego konwersję. Nie używaj nazwy zasobu.

Pola zdarzeń

Tabela poniżej pokazuje, jak pola konwersji polegającej na sprzedaży w sklepie stacjonarnym są mapowane między tymi 2 interfejsami API.

W przeciwieństwie do interfejsu Google Ads API, który obsługuje uwzględnianie tylko jednego produktu na transakcję za pomocą ItemAttribute, interfejs Data Manager API obsługuje uwzględnianie wielu produktów na zdarzenie w CartData.

OfflineUserDataJobOperation.create (interfejs Google Ads API) Event (interfejs Data Manager API) Uwagi
Brak odpowiednika event_source Wymagany. W przypadku konwersji polegających na sprzedaży w sklepie stacjonarnym ustaw wartość IN_STORE.
transaction_attribute.conversion_action destinations.product_destination_id Zobacz Pola klienta i działania powodującego konwersję. Zamiast nazwy zasobu użyj identyfikatora numerycznego działania powodującego konwersję.
transaction_attribute.transaction_date_time event_timestamp
Szczegółowe informacje znajdziesz w sekcji Formaty sygnatury czasowej.
transaction_attribute.transaction_amount_micros
  • conversion_value (Wymagane)
  • cart_data.items[].conversion_value
 Ustaw wartość waluty, a nie wartość w mikrowalucie. Jeśli na przykład wartość konwersji wynosi 5, 23 zł, użyj wartości 5.23.
transaction_attribute.currency_code currency Parametr wymagany.
transaction_attribute.order_id transaction_id Parametr wymagany.
transaction_attribute.store_attribute.store_code event_location.store_id Wymagany Ustaw kod sklepu w polu store_id w obiekcie EventLocation.
transaction_attribute.custom_value
  • custom_variables[].value
  • cart_data.items[].custom_variables[].value
 Mapuj na pole value obiektu CustomVariable na poziomie zdarzenia lub obiektu ItemCustomVariable na poziomie produktu.
transaction_attribute.item_attribute.item_id cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id
  • cart_data.merchant_id
  • cart_data.items[].merchant_id
 Jeśli ustawisz cart_data.merchant_id, będzie on działać jako domyślny dla wszystkich produktów, ale możesz go zastąpić w przypadku poszczególnych produktów.
transaction_attribute.item_attribute.country_code
  • cart_data.merchant_feed_label
  • cart_data.items[].merchant_feed_label
 Jeśli ustawisz cart_data.merchant_feed_label, będzie on działać jako domyślny dla wszystkich produktów, ale możesz go zastąpić w przypadku poszczególnych produktów.
transaction_attribute.item_attribute.language_code
  • cart_data.merchant_feed_language_code
  • cart_data.items[].merchant_feed_language_code
 Jeśli ustawisz cart_data.merchant_feed_language_code, będzie on działać jako domyślny dla wszystkich produktów, ale możesz go zastąpić w przypadku poszczególnych produktów.
transaction_attribute.item_attribute.quantity cart_data.items[].quantity
Brak odpowiednika cart_data.items[].unit_price Ustaw cenę jednostkową bez podatku, dostawy i rabatów na poziomie transakcji (zdarzenia) dla tego produktu.
user_identifiers
  • user_data.user_identifiers
  • third_party_user_data.user_identifiers
 Wymagany.

third_party_user_data ma taką samą strukturę jak user_data, ale wskazuje, że identyfikatory użytkowników pochodzą ze źródła zewnętrznego, a nie z danych własnych reklamodawcy.

Wypełnianie pola third_party_user_data jest dozwolone tylko wtedy, gdy konto logowania jest dostawcą danych (login_account.account_type to DATA_PARTNER).

Szczegółowe informacje znajdziesz w artykule Pola identyfikatora użytkownika.

consent consent Oba interfejsy API używają podobnego obiektu Consent (ad_user_data, ad_personalization). W przypadku interfejsu Data Manager API możesz też ustawić zgodę na wszystkie zdarzenia w żądaniu, ustawiając pole consent w IngestEventsRequest.

Pola identyfikatorów użytkownika

UserIdentifier (interfejs Google Ads API) UserIdentifier (interfejs Data Manager API) Uwagi
user_identifier_source

Źródło określa, które pole należy wypełnić w interfejsie Data Manager API Event:

  • user_data
  • third_party_user_data

third_party_user_data ma taką samą strukturę jak user_data, ale wskazuje, że identyfikatory użytkowników pochodzą ze źródła zewnętrznego, a nie z danych własnych reklamodawcy.

Wypełnianie pola third_party_user_data jest dozwolone tylko wtedy, gdy konto logowania jest dostawcą danych (login_account.account_type to DATA_PARTNER).

Szczegółowe informacje znajdziesz w artykule Pola identyfikatora użytkownika.

hashed_email email_address Ustaw sformatowany i zaszyfrowany adres e-mail. Możesz też zaszyfrować zaszyfrowany adres e-mail.
hashed_phone_number phone_number Ustaw sformatowany i zahaszowany numer telefonu. Możesz też zaszyfrować zahaszowany numer telefonu.
address_info address Ustaw na obiekt AddressInfo. Postępuj zgodnie z wytycznymi dotyczącymi formatowania i szyfrowania. Możesz też zaszyfrować zaszyfrowane atrybuty adresu.
address_info.hashed_first_name address.given_name
address_info.hashed_last_name address.family_name
address_info.country_code address.region_code
address_info.postal_code address.postal_code
address_info.city Brak odpowiednika Nieobsługiwane w przypadku miejsc docelowych Google Ads.
address_info.state Brak odpowiednika Nieobsługiwane w przypadku miejsc docelowych Google Ads.
address_info.hashed_street_address Brak odpowiednika Nieobsługiwane w przypadku miejsc docelowych Google Ads.
Wstecz
Przejście na nową wersję