Mapowanie pól

Użyj mapowań pól, aby uaktualnić każdy etap procesu kierowania na listę klientów z interfejsu Google Ads API do interfejsu Data Manager API:

Uwierzytelnianie

Interfejs Data Manager API wymaga danych logowania o zakresie innym 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.

Mapowania pól zarządzania odbiorcami

Użyj mapowań w tabelach, aby zmapować UserList w interfejsie Google Ads API na jego odpowiednik UserList w interfejsie Data Manager API.

UserList (Google Ads API) UserList (Data Manager API) Uwagi
resource_name name Więcej informacji znajdziesz w sekcji Nazwy zasobów.
id id
read_only read_only
name display_name Wymagany
description description Wymagany
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

Czas, przez jaki odbiorca pozostaje na liście po dodaniu. Wartość musi odpowiadać pełnym dniom. Jeśli nie jest ustawiona, domyślnie przyjmuje się wartość maksymalną.

Sformatuj wartość, używając formatu sygnatury czasowej.
size_for_display size_info.display_network_members_count
size_range_for_display Brak odpowiednika. Informacje o rozmiarze podawaj w size_info.display_network_members_count.
size_for_search size_info.search_network_members_count
size_range_for_search Brak odpowiednika. Informacje o rozmiarze podawaj w size_info.search_network_members_count.
type Brak odpowiednika.
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info Nie jest używany w przypadku kierowania na listę klientów.
crm_based_user_list ingested_user_list_info Parametr wymagany. Zobacz informacje o odbiorcach kierowania na listę klientów.
Brak odpowiednika. ingested_user_list_info.pair_id_info Nie jest używany w przypadku kierowania na listę klientów.
Brak odpowiednika. ingested_user_list_info.partner_audience_info Nie jest używany w przypadku kierowania na listę klientów.
logical_user_list Brak odpowiednika. Nie jest używany w przypadku kierowania na listę klientów.
logical_user_list Brak odpowiednika. Nie jest używany w przypadku kierowania na listę klientów.
lookalike_user_list Brak odpowiednika. Nie jest używany w przypadku kierowania na listę klientów.
rule_based_user_list Brak odpowiednika. Nie jest używany w przypadku kierowania na listę klientów.
similar_user_list Brak odpowiednika. Nie jest używany w przypadku kierowania na listę klientów.

Informacje o odbiorcach kierowania na listę klientów

Podczas tworzenia odbiorców kierowania na listę klientów w interfejsie Google Ads API musisz ustawić pole crm_based_user_list na wartość CrmBasedUserListInfo.

W interfejsie Data Manager API ustaw odpowiednie atrybuty, ustawiając pole ingested_user_list_info na wartość IngestedUserListInfo, a następnie ustaw wymagane pola dla kierowania na listę klientów i rodzaj danych użytkowników.

Informacje kontaktowe

upload_key_types
Ustaw na listę zawierającą CONTACT_ID. Jest to równoznaczne z ustawieniem wartości upload_key_type na CONTACT_INFO w interfejsie Google Ads API.
contact_id_info

Ustaw na ContactIdInfo.

Ustaw data_source_type na DATA_SOURCE_TYPE_FIRST_PARTY. Jest to równoznaczne z ustawieniem wartości data_source_type na FIRST_PARTY w interfejsie Google Ads API.

Identyfikatory mobilne

upload_key_types
Ustaw na listę zawierającą MOBILE_ID. Jest to równoznaczne z ustawieniem wartości upload_key_type na MOBILE_ADVERTISING_ID w interfejsie Google Ads API.
mobile_id_info

Ustaw na MobileIdInfo.

  • Ustaw data_source_type na DATA_SOURCE_TYPE_FIRST_PARTY. Jest to równoznaczne z ustawieniem wartości data_source_type na FIRST_PARTY w interfejsie Google Ads API.
  • Ustaw key_space na IOS lub ANDROID. Interfejs Data Manager API wymaga tej wartości. Różni się to od interfejsu Google Ads API, w którym przestrzeń kluczy jest wywnioskowana z app_id.
  • Ustaw wartość app_id na ciąg znaków, który jednoznacznie identyfikuje aplikację mobilną, z której zebrano dane. Użyj tego samego formatu, którego używasz w przypadku parametru app_id w interfejsie Google Ads API.

Identyfikatory użytkowników

upload_key_types
Ustaw na listę zawierającą USER_ID. Jest to równoznaczne z ustawieniem wartości upload_key_type na CRM_ID w interfejsie Google Ads API.
user_id_info

Ustaw na UserIdInfo.

Ustaw data_source_type na DATA_SOURCE_TYPE_FIRST_PARTY. Jest to równoznaczne z ustawieniem wartości data_source_type na FIRST_PARTY w interfejsie Google Ads API.

Nazwy zasobów

Interfejs Data Manager API używa innego formatu nazw zasobów niż interfejs Google Ads API.

Interfejs Google Ads API

W interfejsie Google Ads API nazwa zasobu UserList ma format:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

W interfejsie Data Manager API UserList nazwa zasobu ma format:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

Przesyłanie mapowań pól

Użyj mapowań w tabelach, aby zmapować AddOfflineUserDataJobOperationsRequest w interfejsie Google Ads API na odpowiednie żądanie IngestionService w interfejsie Data Manager API.

Pola żądania

Te mapowania używają IngestAudienceMembersRequest w interfejsie Data Manager API jako odniesienia, ale możesz ich używać również wtedy, gdy konwertujesz żądanie interfejsu Google Ads API na RemoveAudienceMembersRequest lub RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) Uwagi
  • customer_id pole
  • customer_match_user_list_metadata z OfflineUserDataJob
  • Nagłówek żądania developer-token
  • Nagłówek żądania login-customer_id
  • Nagłówek żądania linked-customer-id
 destinations Zobacz Pola dotyczące klientów i odbiorców.
consent z customer_match_user_list_metadata OfflineUserDataJob consent Opcjonalne domyślne ustawienia dotyczące zgody użytkowników w żądaniu. Możesz zastąpić tę wartość w przypadku poszczególnych odbiorców, ustawiając pole consent w AudienceMember.
Brak odpowiednika encoding Wymagane: ustaw na Encoding używany w przypadku wartości UserIdentifier.
Brak odpowiednika encryption_info Określ, czy żądanie zawiera zaszyfrowane wartości. Więcej informacji znajdziesz w sekcji Szyfrowanie.
job_id Brak odpowiednika Użyj wartości request_id zwróconej w odpowiedzi, aby pobrać diagnostykę.
enable_partial_failure Brak odpowiednika Interfejs Data Manager API korzysta z modelu błędów szybkiego wykrywania. Jeśli w przypadku dowolnego pola w IngestAudienceMembersRequest nie uda się weryfikacja, interfejs Data Manager API odrzuci całe żądanie. Pobieranie błędów przetwarzania za pomocą diagnostyki.
enable_warnings Brak odpowiednika Interfejs Data Manager API nie zgłasza ostrzeżeń w odpowiedzi. Pobierz ostrzeżenia dotyczące przetwarzania za pomocą diagnostyki.
validate_only validate_only
operations audience_members Lista członków grupy odbiorców do dodania lub usunięcia. Szczegółowe informacje znajdziesz w sekcji dotyczącej pól operacji.
Brak odpowiednika terms_of_service Parametr wymagany. Ustaw, aby wskazać, że użytkownik zaakceptował lub odrzucił Warunki korzystania z usługi kierowania na listę klientów.

Pola klienta i odbiorców

Interfejs Google Ads API obsługuje przesyłanie członków list odbiorców tylko na jedną listę odbiorców w ramach jednego zadania. Wymagany jest też nagłówek żądania developer-token. W przypadku różnych scenariuszy uwierzytelniania ustawiasz nagłówki żądań login-customer-id i linked-customer-id.

Interfejs Data Manager API obsługuje wysyłanie członków wielu list odbiorców w ramach jednego żądania. Interfejs Data Manager API nie wymaga tokena programisty, a informacje o logowaniu i połączonych klientach podajesz w polach Destination zamiast w nagłówkach żądań. Więcej informacji o miejscach docelowych znajdziesz w artykule Konfigurowanie miejsc docelowych.

W interfejsie Google Ads API możesz usunąć wszystkich członków listy odbiorców, ustawiając pole remove_all w obiekcie OfflineUserDataJobOperation na wartość true.

W interfejsie Data Manager API możesz to zrobić, wysyłając RemoveAllAudienceMembersRequest. Szczegółowe informacje znajdziesz w przewodniku Usuwanie wszystkich członków.

Poniżej znajdziesz sposób mapowania pól interfejsu Google Ads API dla pojedynczej listy odbiorców na odpowiednie pola w Destination:

Interfejs Google Ads API Destination (interfejs Data Manager API) Uwagi
customer_id żądania operating_account Ustaw account_id na identyfikator klienta odbiorców. Ustaw wartość account_type w zasobie 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 wartość account_id na identyfikator klienta konta logowania. Ustaw wartość account_type na GOOGLE_ADS, jeśli konto logowania to konto Google Ads, lub DATA_PARTNER, jeśli konto logowania to konto 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.
user_list z customer_match_user_list_metadata OfflineUserDataJob product_destination_id Parametr wymagany. Ustaw na liczbowy identyfikator listy odbiorców. Nie używaj nazwy zasobu UserList.
Brak odpowiednika reference Identyfikator Destination zdefiniowany przez użytkownika. Ustaw to pole, jeśli wysyłasz w jednym żądaniu dane członków wielu grup odbiorców.

Pola operacji

Interfejs Data Manager API zawiera oddzielne metody dodawania i usuwania użytkowników z list odbiorców. Z kolei w AddOfflineUserDataJobOperationsRequest w interfejsie Google Ads API znajduje się lista operations, z których każdy dodaje lub usuwa członka albo usuwa wszystkich członków w zależności od typu operacji. Poniżej znajdziesz mapowanie każdego typu operacji na odpowiednią metodę w interfejsie Data Manager API:

OfflineUserDataJobOperation(interfejs Google Ads API) IngestionService (interfejs Data Manager API) Uwagi
create IngestAudienceMembers Więcej informacji znajdziesz w sekcji dotyczącej pól członków listy odbiorców.
remove RemoveAudienceMembers Więcej informacji znajdziesz w sekcji dotyczącej pól członków listy odbiorców.
remove_all RemoveAllAudienceMembers Szczegółowe informacje znajdziesz w artykule Usuwanie wszystkich członków grupy odbiorców.

Pola odbiorców

UserData(interfejs Google Ads API) AudienceMember (interfejs Data Manager API) Uwagi
consent consent

Ustaw, aby określić zgodę odbiorcy.

Oba interfejsy API używają podobnego Consent obiektu (ad_user_data, ad_personalization).

W przypadku interfejsu Data Manager API możesz też ustawić zgodę dla wszystkich członków listy odbiorców w żądaniu, ustawiając pole consent na poziomie żądania.
transaction_attribute Brak odpowiednika. Nie dotyczy kierowania na listę klientów.
user_attribute Brak odpowiednika. Nie dotyczy kierowania na listę klientów.
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

Wypełnij pole odpowiadające typowi danych, które wysyłasz w przypadku członków listy odbiorców. Więcej informacji znajdziesz w sekcji Pola identyfikatorów użytkownika.

Pola identyfikatorów użytkownika

W interfejsie Google Ads API do wysyłania danych kontaktowych, identyfikatorów urządzeń mobilnych lub identyfikatorów użytkowników używasz parametru UserIdentifier. Interfejs Data Manager API korzysta z innego podejścia i ma różne pola dla każdego typu danych.

W interfejsie Data Manager API wypełnij pole odpowiadające typowi przesyłanych danych:

Informacje kontaktowe

Jeśli używasz informacji kontaktowych, takich jak adres e-mail, numer telefonu lub adres, ustaw wartość composite_data na CompositeData z osobnym wpisem w user_data.user_identifiers dla każdego elementu informacji kontaktowych.

Chociaż znacznik user_data jest nadal obsługiwany, zalecamy używanie znacznika composite_data, aby mieć pewność, że integracja jest przygotowana na przyszłe ulepszenia. Więcej informacji znajdziesz w sekcji Dane złożone.

UserIdentifier (Google Ads API) UserIdentifier (interfejs Data Manager API) Uwagi
address_info address Więcej informacji znajdziesz w sekcji Pola adresu.
hashed_email email_address Ustaw na sformatowany i zahaszowany adres e-mail. Możesz też zaszyfrować zahaszowany adres e-mail.
hashed_phone_number phone_number Ustaw na sformatowany i zaszyfrowany numer telefonu. Możesz też zaszyfrować zahaszowany numer telefonu.
user_identifier_source Brak odpowiednika.

Pola adresu

Poniżej znajdziesz mapowania pól między OfflineUserAddressInfo w interfejsie Google Ads API a AddressInfo w interfejsie Data Manager API. Używaj tych mapowań, jeśli do wypełniania listy odbiorców kierowania na listę klientów używasz informacji kontaktowych.

OfflineUserAddressInfo (Google Ads API) AddressInfo (interfejs Data Manager API) Uwagi
city Brak odpowiednika.
country_code region_code Wymagany
hashed_first_name given_name

Parametr wymagany. Ustawia sformatowane i zaszyfrowane imię. Możesz też zaszyfrować zahaszowane imię.
hashed_last_name family_name

Parametr wymagany. Ustaw na sformatowane i zahaszowane nazwisko. Możesz też zaszyfrować zahaszowaną nazwę grupy rodzinnej.
hashed_street_address Brak odpowiednika.
postal_code postal_code Wymagany
state Brak odpowiednika.

Adres IP

Interfejs Data Manager API obsługuje uwzględnianie adresów IP w przypadku przesyłania danych na potrzeby kierowania na listę klientów oprócz identyfikatorów użytkowników. Są one dostępne w CompositeData, która zawiera UserData i IpData. Podanie tych pól razem może zwiększyć odsetek dopasowań.

Więcej informacji znajdziesz w artykule Przetwarzanie adresów IP na potrzeby kierowania na listę klientów.

Interfejs Google Ads API CompositeData (interfejs Data Manager API) Uwagi
Brak odpowiednika. ip_data.ip_address Ustaw na nieprzetworzony adres IPv4 lub IPv6. Zapoznaj się z wytycznymi dotyczącymi formatu adresu IP.
Brak odpowiednika. ip_data.observe_start_time Ustawiona na sygnaturę czasową w formacie RFC 3339, gdy adres IP został zaobserwowany po raz pierwszy.
Brak odpowiednika. ip_data.observe_end_time Ustawiona na sygnaturę czasową w formacie RFC 3339, gdy adres IP był ostatnio obserwowany.
user_identifiers user_data Ustaw na obiekt UserData.

Identyfikatory mobilne

Jeśli używasz identyfikatorów mobilnych, ustaw wartość mobile_data na MobileData z wpisem w mobile_ids dla każdego identyfikatora.

UserIdentifier (Google Ads API) MobileData (interfejs Data Manager API) Uwagi
mobile_id mobile_ids Ustaw na listę identyfikatorów mobilnych dla członka grupy odbiorców.

W interfejsie Google Ads API dodajesz osobny UserIdentifier z parametrem mobile_id dla każdego identyfikatora urządzenia mobilnego odbiorcy. W interfejsie Data Manager API dodaj pojedynczy element MobileData z parametrem mobile_ids ustawionym na listę wszystkich identyfikatorów mobilnych odbiorcy.

user_identifier_source Brak odpowiednika.

Identyfikatory użytkowników

Jeśli używasz identyfikatorów użytkowników, ustaw wartość parametru user_id_data na UserIdData, a wartość parametru user_id na identyfikator użytkownika należącego do grupy odbiorców.

UserIdentifier (Google Ads API) UserIdData (interfejs Data Manager API) Uwagi
third_party_user_id user_id

W interfejsie Google Ads API dodajesz osobny UserIdentifier z parametrem third_party_user_id dla każdego identyfikatora użytkownika należącego do listy odbiorców.

W interfejsie Data Manager API ustaw pole user_id_data na UserIdData, a pole user_id na identyfikator użytkownika należącego do segmentu odbiorców. Nie możesz wysyłać wielu identyfikatorów użytkowników dla tego samego odbiorcy.

user_identifier_source Brak odpowiednika.
Wstecz
Przejście na nową wersję