מיפוי שדות

משתמשים במיפוי השדות כדי לשדרג כל שלב בתהליך העבודה של התאמה ללקוחות מ-Google Ads API ל-Data Manager API:

• מיפויי שדות לניהול קהלים מכיל מיפויי שדות ליצירה, לעדכון ולאחזור של קהלים.

• מיפוי שדות להעברה מכיל מיפוי שדות להוספה או להסרה של חברים בקהל.

מיפוי שדות של ניהול קהלים

משתמשים במיפויים שבטבלאות כדי למפות UserList ב-Google Ads API למקבילה UserList ב-Data Manager API.

‫UserList (Google Ads API)	‫UserList (Data Manager API)	הערות
resource_name	name	פרטים נוספים זמינים במאמר בנושא שמות משאבים.
id	id
read_only	read_only
name	display_name	חובה
description	description	חובה
membership_status	membership_status
integration_code	integration_code
membership_life_span	membership_duration	משך הזמן שחבר בקהל נשאר ברשימה אחרי שהוא נוסף אליה. הערך צריך להיות מספר שלם של ימים. אם לא מגדירים את הפרמטר, ברירת המחדל היא הערך המקסימלי. הערך צריך להיות בפורמט חותמת זמן.
size_for_display	size_info.display_network_members_count
size_range_for_display	אין מקבילה.	משתמשים בsize_info.display_network_members_count כדי לציין את המידה.
size_for_search	size_info.search_network_members_count
size_range_for_search	אין מקבילה.	משתמשים בsize_info.search_network_members_count כדי לציין את המידה.
type	אין מקבילה.
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	לא נעשה בה שימוש בהתאמה ללקוחות.
crm_based_user_list	ingested_user_list_info	חובה. מידע על קהל מסוג 'התאמה ללקוחות'
אין מקבילה.	ingested_user_list_info.pair_id_info	לא נעשה בה שימוש בהתאמה ללקוחות.
אין מקבילה.	ingested_user_list_info.partner_audience_info	לא נעשה בה שימוש בהתאמה ללקוחות.
logical_user_list	אין מקבילה.	לא נעשה בה שימוש בהתאמה ללקוחות.
logical_user_list	אין מקבילה.	לא נעשה בה שימוש בהתאמה ללקוחות.
lookalike_user_list	אין מקבילה.	לא נעשה בה שימוש בהתאמה ללקוחות.
rule_based_user_list	אין מקבילה.	לא נעשה בה שימוש בהתאמה ללקוחות.
similar_user_list	אין מקבילה.	לא נעשה בה שימוש בהתאמה ללקוחות.

מידע על קהל מסוג 'התאמה ללקוחות'

ב-Google Ads API, חובה למלא את השדה crm_based_user_list כשיוצרים קהל מסוג 'התאמה ללקוחות'.

ב-Data Manager API, מגדירים את המאפיינים המקבילים על ידי הגדרת השדה ingested_user_list_info לערך IngestedUserListInfo, ואז מגדירים את השדות הנדרשים להתאמה ללקוחות ואת סוג נתוני המשתמש.

פרטים ליצירת קשר

upload_key_types

מוגדר לרשימה שמכילה את CONTACT_INFO.

contact_id_info

ההגדרה היא ContactIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY.

מזהי מכשירים ניידים

upload_key_types

מוגדר לרשימה שמכילה את MOBILE_ID.

mobile_id_info

ההגדרה היא MobileIdInfo.

• מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY.
• מגדירים את key_space לערך IOS או ANDROID.
• מגדירים את app_id למחרוזת שמזהה באופן ייחודי את האפליקציה לנייד שממנה נאספו הנתונים. צריך להשתמש באותו פורמט שבו משתמשים למזהה האפליקציה ב-Google Ads API.

מזהי משתמשים

upload_key_types

מוגדר לרשימה שמכילה את USER_ID.

user_id_info

ההגדרה היא UserIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY.

שמות המשאבים

הפורמט של שם המשאב ב-Data Manager API שונה מהפורמט ב-Google Ads API.

Google Ads API

ב-Google Ads API, שם משאב UserList מבוסס על הפורמט הבא:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

ב-Data Manager API, שם משאב UserList מופיע בפורמט:

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

העלאה של מיפוי השדות

משתמשים במיפויים בטבלאות כדי למפות AddOfflineUserDataJobOperationsRequest ב-Google Ads API למקבילה IngestAudienceMembersRequest ב-Data Manager API.

שדות של בקשות

AddOfflineUserDataJobOperationsRequest (Google Ads API)	IngestAudienceMembersRequest (Data Manager API)	הערות
שדה customer_id השדה customer_match_user_list_metadata של OfflineUserDataJob כותרת הבקשה developer-token כותרת הבקשה login-customer_id כותרת הבקשה linked-customer-id	destinations	מידע נוסף על שדות של לקוחות וקהלים
consent מתוך customer_match_user_list_metadata של OfflineUserDataJob	consent	הגדרות ברירת מחדל אופציונליות בנוגע להסכמה של חברי קהל בבקשה. אפשר לשנות את הערך הזה עבור חבר ספציפי בקהל על ידי הגדרת השדה consent של AudienceMember.
אין דוח מקביל	encoding	חובה: מגדירים את הערך Encoding שמשמש לערכים של UserIdentifier.
אין דוח מקביל	encryption_info	הגדרה אם הבקשה מכילה ערכים מוצפנים. פרטים נוספים זמינים במאמר בנושא הצפנה.
job_id	אין דוח מקביל	משתמשים ב-request_id שמוחזר בתשובה כדי לאחזר אבחון.
enable_partial_failure	אין דוח מקביל	‫Data Manager API לא תומך בכשל חלקי. אם אחד מהשדות ב-IngestAudienceMembersRequest נכשל באימות, Data Manager API דוחה את הבקשה כולה. אפשר לאחזר שגיאות עיבוד באמצעות כלי האבחון.
enable_warnings	אין דוח מקביל	ממשק Data Manager API לא מדווח על אזהרות בתגובה. אחזור אזהרות עיבוד באמצעות אבחון.
validate_only	validate_only
operations	audience_members	רשימת החברים בקהל. פרטים נוספים זמינים בקטע שדות של חברי קהל.
אין דוח מקביל	terms_of_service	חובה. הערך מוגדר כדי לציין שהמשתמש אישר או דחה את התנאים וההגבלות של התאמה ללקוחות.

שדות של לקוחות וקהלים

ממשק Google Ads API תומך בהעלאת חברי קהל לקהל אחד בלבד לכל משימה.בנוסף, נדרשת כותרת בקשה של developer-token, וצריך להגדיר את login-customer-id ו-linked-customer-id כותרות הבקשה לתרחישי אימות שונים.

‫Data Manager API תומך בשליחת חברים בקהל לכמה קהלים בבקשה אחת. כדי להשתמש ב-Data Manager API לא צריך קוד מפתח, ופרטי ההתחברות ופרטי הלקוחות המקושרים מוגדרים באמצעות שדות של Destination ולא באמצעות כותרות של בקשות. מידע נוסף על יעדים זמין במאמר הגדרת יעדים.

ה-API של המרכז לניהול נתונים לא תומך בהסרה של כל חברי הקהל. ב-Google Ads API, אפשר להסיר את כל חברי הקהל על ידי הגדרת השדה remove_all של OfflineUserDataJobOperation לערך true.

כך ממפים את השדות של Google Ads API לקהל יחיד לשדות המקבילים ב-Destination:

Google Ads API	Destination (Data Manager API)	הערות
customer_id של הבקשה	operating_account	מגדירים את הערך account_id למספר הלקוח של הקהל. מגדירים את account_type של operating_account לערך GOOGLE_ADS.
כותרת הבקשה developer-token	אין דוח מקביל	לא נדרש קוד מפתח ל-Data Manager API.
כותרת הבקשה login-customer-id	login_account	מגדירים את account_id למספר הלקוח של חשבון הכניסה. מגדירים את account_type לערך GOOGLE_ADS אם חשבון הכניסה הוא חשבון Google Ads, או לערך DATA_PARTNER אם חשבון הכניסה הוא חשבון של שותף נתונים.
כותרת הבקשה linked-customer-id	linked_account	מגדירים את account_id למספר הלקוח של החשבון המקושר. מגדירים את account_type לערך DATA_PARTNER.
user_list מתוך customer_match_user_list_metadata של OfflineUserDataJob	product_destination_id	חובה. הערך שמוגדר הוא המזהה המספרי של הקהל. אסור להשתמש בשם המשאב של UserList.
אין דוח מקביל	reference	מזהה שהמשתמש מגדיר עבור Destination. מגדירים את השדה הזה אם שולחים חברים בקהל לכמה קהלים בבקשה אחת.

שדות של חברים בקהל

UserData (Google Ads API)	AudienceMember (Data Manager API)	הערות
consent	consent	הגדרה שמציינת את ההסכמה של חבר הקהל. שני ממשקי ה-API משתמשים באותו אובייקט Consent (ad_user_data, ‏ ad_personalization). ב-API של המרכז לניהול נתונים, אפשר גם להגדיר הסכמה לכל חברי הקהל בבקשה על ידי הגדרת השדה consentברמת הבקשה.
transaction_attribute	אין מקבילה.	לא רלוונטי להתאמה ללקוחות.
user_attribute	אין מקבילה.	לא רלוונטי להתאמה ללקוחות.
user_identifiers	mobile_id_data user_id_data user_identifiers	מאכלסים את השדה שמתאים לסוג הנתונים שאתם שולחים לגבי חברי הקהל. פרטים נוספים זמינים במאמר בנושא שדות של מזהי משתמשים.

שדות של מזהי משתמשים

ב-Google Ads API, כששולחים פרטים ליצירת קשר, מזהים לנייד או מזהי משתמשים, משתמשים ב-UserIdentifier. ממשק ה-API של המרכז לניהול נתונים משתמש בגישה שונה, עם שדות שונים לכל סוג של נתונים.

ב-Data Manager API, מאכלסים את השדה שמתאים לסוג הנתונים ששולחים:

פרטים ליצירת קשר

אם משתמשים בפרטים ליצירת קשר כמו כתובת אימייל, מספר טלפון או פרטי כתובת, צריך להגדיר את user_data כUserData עם רשומה נפרדת ב-user_identifiers לכל פריט של פרטים ליצירת קשר.

UserIdentifier (Google Ads API)	UserIdentifier (Data Manager API)	הערות
address_info	address	פרטים נוספים מופיעים במאמר בנושא שדות כתובת.
hashed_email	email_address	מגדירים את כתובת האימייל בפורמט הנכון עם גיבוב. אפשר גם להצפין את כתובת האימייל שעברה גיבוב.
hashed_phone_number	phone_number	הערך מוגדר למספר הטלפון בפורמט מגובב. אפשר גם להצפין את מספר הטלפון המגובב.
user_identifier_source	אין מקבילה.

שדות כתובת

אלה מיפויי השדות בין OfflineUserAddressInfo ב-Google Ads API לבין AddressInfo ב-Data Manager API. כדאי להשתמש במיפויים האלה אם אתם משתמשים בפרטים ליצירת קשר כדי לאכלס את קהל הלקוחות שלכם.

OfflineUserAddressInfo (Google Ads API)	AddressInfo (Data Manager API)	הערות
city	אין מקבילה.
country_code	region_code
hashed_first_name	given_name	הערך שמוגדר הוא השם הפרטי שניתן בפורמט מגובב. אפשר גם להצפין את השם הנתון שעבר גיבוב.
hashed_last_name	family_name	ההגדרה היא formatted and hashed family name. אפשר גם להצפין את שם המשפחה שעבר גיבוב.
hashed_street_address	אין מקבילה.
postal_code	postal_code
state	אין מקבילה.

מזהי מכשירים ניידים

אם משתמשים במזהים לנייד, מגדירים את mobile_data ל-a MobileData עם רשומה ב-mobile_ids לכל מזהה.

UserIdentifier (Google Ads API)	MobileData (Data Manager API)	הערות
mobile_id	mobile_ids	מגדירים את הרשימה של מזהי המכשירים הניידים של חבר הקהל. ב-Google Ads API, מוסיפים פרמטר נפרד UserIdentifier עם mobile_id לכל מזהה לנייד של חבר בקהל. ב-Data Manager API, מוסיפים single MobileData עם mobile_ids שמוגדר לרשימה של כל המזהים לנייד של חבר הקהל.
user_identifier_source	אין מקבילה.

מזהי משתמשים

אם משתמשים במזהי משתמשים, מגדירים את user_id_data ל-UserIdData ואת user_id למזהה המשתמש של חבר הקהל.

UserIdentifier (Google Ads API)	UserIdData (Data Manager API)	הערות
third_party_user_id	user_id	ב-Google Ads API, מוסיפים תג נפרד UserIdentifier עם third_party_user_id לכל מזהה משתמש של חבר בקהל. ב-Data Manager API, מגדירים את השדה user_id_data לערך UserIdData, ואת השדה user_id למזהה המשתמש של חבר הקהל. אי אפשר לשלוח כמה מזהי משתמשים לאותו חבר בקהל.
user_identifier_source	אין מקבילה.