Mapowanie pól

Aby przejść z interfejsu Google Ads API na interfejs Data Manager API, użyj mapowania pól na każdym etapie procesu kierowania na listę klientów:

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.

Mapowania pól zarządzania odbiorcami

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

UserList (interfejs 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. Użyj atrybutu size_info.display_network_members_count, aby podać informacje o rozmiarze.
size_for_search size_info.search_network_members_count
size_range_for_search Brak odpowiednika. Użyj atrybutu size_info.search_network_members_count, aby podać informacje o rozmiarze.
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 są używane do 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 są używane do kierowania na listę klientów.
Brak odpowiednika. ingested_user_list_info.partner_audience_info Nie są używane do kierowania na listę klientów.
logical_user_list Brak odpowiednika. Nie są używane do kierowania na listę klientów.
logical_user_list Brak odpowiednika. Nie są używane do kierowania na listę klientów.
lookalike_user_list Brak odpowiednika. Nie są używane do kierowania na listę klientów.
rule_based_user_list Brak odpowiednika. Nie są używane do kierowania na listę klientów.
similar_user_list Brak odpowiednika. Nie są używane do kierowania na listę klientów.

Informacje o odbiorcach kierowania na listę klientów

Podczas tworzenia listy 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 IngestedUserListInfo, a następnie ustaw wymagane pola kierowania na listę klientów i typ danych użytkownika.

Informacje kontaktowe

upload_key_types
Ustaw listę zawierającą CONTACT_ID. Odpowiada to ustawieniu 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. Odpowiada to ustawieniu data_source_type na FIRST_PARTY w interfejsie Google Ads API.

Dokumenty Mobile ID

upload_key_types
Ustaw listę zawierającą MOBILE_ID. Odpowiada to ustawieniu 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. Odpowiada to ustawieniu 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 określana na podstawie app_id.
  • Ustaw 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 pola app_id w interfejsie Google Ads API.

Identyfikatory użytkowników

upload_key_types
Ustaw listę zawierającą USER_ID. Odpowiada to ustawieniu 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. Odpowiada to ustawieniu data_source_type na FIRST_PARTY w interfejsie Google Ads API.

Nazwy zasobów

Interfejs Data Manager API używa innego formatu nazwy zasobu niż interfejs Google Ads API.

Interfejs Google Ads API

W interfejsie Google Ads API nazwa zasobu UserList ma taki format:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

W interfejsie Data Manager API nazwa zasobu UserList ma taki 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ą jako odniesienia IngestAudienceMembersRequest w interfejsie Data Manager API, ale możesz ich też używać, jeśli konwertujesz żądanie do interfejsu Google Ads API na RemoveAudienceMembersRequest lub RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (interfejs Google Ads API) IngestAudienceMembersRequest (Data Manager API) Uwagi
  • customer_id pole
  • customer_match_user_list_metadata pole z OfflineUserDataJob
  • Nagłówek żądania developer-token
  • Nagłówek żądania login-customer_id
  • Nagłówek żądania linked-customer-id
 destinations Patrz Pola dotyczące klientów i odbiorców.
consent z  customer_match_user_list_metadata OfflineUserDataJob consent Opcjonalne domyślne ustawienia dotyczące zgody na zbieranie danych dla odbiorców w żądaniu. Możesz zastąpić tę wartość dla poszczególnych odbiorców, ustawiając pole consent w AudienceMember.
Brak odpowiednika encoding Wymagane: ustaw na Encoding używane dla wartości UserIdentifier.
Brak odpowiednika encryption_info Ustaw, jeśli żądanie zawiera zaszyfrowane wartości. Więcej informacji znajdziesz w artykule na temat szyfrowania.
job_id Brak odpowiednika Użyj parametru request_id zwróconego w odpowiedzi, aby pobrać informacje diagnostyczne.
enable_partial_failure Brak odpowiednika Interfejs Data Manager API korzysta z modelu błędów typu fast-fail. Jeśli którekolwiek pole obiektu IngestAudienceMembersRequest nie przejdzie weryfikacji, interfejs Data Manager API odrzuci całe żądanie. Pobierz błędy 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 odbiorców, których chcesz dodać lub usunąć. 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 dotyczące klientów i odbiorców

Interfejs Google Ads API obsługuje przesyłanie odbiorców tylko do jednej listy odbiorców na zadanie.Dodatkowo wymagany jest nagłówek żą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 obsługuje przesyłanie odbiorców z wielu list odbiorców w jednym żądaniu. 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.

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

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

Oto jak zmapować pola interfejsu Google Ads API dla pojedynczej grupy odbiorców na odpowiednie pola w Destination:

Interfejs Google Ads API Destination (interfejs Data Manager API) Uwagi
customer_id prośby operating_account Ustaw account_id na identyfikator klienta listy odbiorców. Ustaw 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 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.
user_list z customer_match_user_list_metadata OfflineUserDataJob product_destination_id Parametr wymagany. Ustaw liczbowy identyfikator listy odbiorców. Nie używaj nazwy zasobu UserList.
Brak odpowiednika reference Zdefiniowany przez użytkownika identyfikator elementu Destination. Ustaw to pole, jeśli wysyłasz odbiorców z wielu list w jednym żądaniu.

Pola operacji

Interfejs Data Manager API zawiera osobne metody dodawania i usuwania odbiorców. Z kolei AddOfflineUserDataJobOperationsRequest w interfejsie Google Ads API zawiera listę operations, z których każdy dodaje użytkownika, usuwa użytkownika lub usuwa wszystkich użytkowników w zależności od typu operacji. Oto mapowanie każdego typu operacji na odpowiadającą mu 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 Pola odbiorców.
remove RemoveAudienceMembers Więcej informacji znajdziesz w sekcji Pola odbiorców.
remove_all RemoveAllAudienceMembers Więcej informacji znajdziesz w sekcji Usuwanie wszystkich 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 obiektu Consent (ad_user_data, ad_personalization).

W przypadku interfejsu Data Manager API możesz też ustawić zgodę dla wszystkich 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 odbiorców. Więcej informacji znajdziesz w sekcji Pola identyfikatorów użytkownika.

Pola identyfikatorów użytkownika

W interfejsie Google Ads API, niezależnie od tego, czy wysyłasz dane kontaktowe, identyfikatory urządzeń mobilnych czy identyfikatory użytkowników, używasz UserIdentifier. Interfejs Data Manager API korzysta z innego podejścia, z różnymi polami dla każdego typu danych.

W interfejsie Data Manager API wypełnij pole odpowiadające typowi danych, które wysyłasz:

Informacje kontaktowe

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

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

UserIdentifier (interfejs Google Ads API) UserIdentifier (interfejs Data Manager API) Uwagi
address_info address Szczegółowe informacje znajdziesz w sekcji Pola adresu.
hashed_email email_address Ustaw na sformatowany i zaszyfrowany adres e-mail. Możesz też zaszyfrować zaszyfrowany 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

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

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

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

Parametr wymagany. Ustaw na sformatowane i zaszyfrowane nazwisko. Możesz też zaszyfrować zaszyfrowane nazwisko.
hashed_street_address Brak odpowiednika.
postal_code postal_code Wymagany
state Brak odpowiednika.

Adres IP

Interfejs Data Manager API obsługuje przesyłanie adresów IP na potrzeby kierowania na listę klientów, a także identyfikatorów użytkowników. Są one dostępne w CompositeData, który zawiera UserData i IpData. Podanie tych pól razem może pomóc zwiększyć współczynniki dopasowania.

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 nieprzetworzony adres IPv4 lub IPv6. Zobacz wskazówki dotyczące formatu adresu IP.
Brak odpowiednika. ip_data.observe_start_time Ustaw sygnaturę czasową w formacie RFC 3339, gdy adres IP został zaobserwowany po raz pierwszy.
Brak odpowiednika. ip_data.observe_end_time Ustaw sygnaturę czasową w formacie RFC 3339, gdy adres IP był ostatnio obserwowany.
user_identifiers user_data Ustaw na obiekt UserData.

Dokumenty Mobile ID

Jeśli używasz identyfikatorów urządzeń mobilnych, ustaw mobile_data na MobileData z wpisem w mobile_ids dla każdego identyfikatora.

UserIdentifier (interfejs Google Ads API) MobileData (interfejs Data Manager API) Uwagi
mobile_id mobile_ids Ustaw listę dokumentów Mobile ID dla odbiorcy.

W interfejsie Google Ads API dodajesz osobny element UserIdentifier z mobile_id dla każdego dokumentu Mobile ID odbiorcy. W interfejsie Data Manager API dodaj pojedynczy obiekt MobileData z parametrem mobile_ids ustawionym na listę wszystkich dokumentów Mobile ID odbiorcy.

user_identifier_source Brak odpowiednika.

Identyfikatory użytkowników

Jeśli używasz identyfikatorów użytkowników, ustaw parametr user_id_data na wartość UserIdData, a parametr user_id na identyfikator użytkownika, który jest odbiorcą.

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

W interfejsie Google Ads API dodajesz osobny element UserIdentifier z atrybutem third_party_user_id dla każdego identyfikatora użytkownika, który jest odbiorcą.

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

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