מיפוי שדות

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

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

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

אימות

‫Data Manager API דורש פרטי כניסה עם היקף שונה מזה של Google Ads API. כדי ליצור פרטי כניסה חדשים שכוללים את ההיקף של Data Manager API, פועלים לפי השלבים שמפורטים בקטע הגדרת גישה ל-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 בתור CrmBasedUserListInfo.

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

שמות המשאבים

הפורמט של שם המשאב ב-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 לבקשת IngestionService המקבילה ב-Data Manager API.

שדות הבקשה

המיפויים האלה משתמשים ב-IngestAudienceMembersRequest ב-Data Manager API כהפניה, אבל אתם יכולים להשתמש במיפויים האלה גם אם אתם ממירים את בקשת Google Ads API ל-RemoveAudienceMembersRequest או ל-RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API)	IngestAudienceMembersRequest (Data Manager API)	הערות
השדה customer_id השדה customer_match_user_list_metadata של OfflineUserDataJob ‫request header של developer-token ‫request header של login-customer_id ‫request header של 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 משתמש במודל שגיאות מסוג fast-fail. אם שדה כלשהו של 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 במקום כותרות של בקשות. מידע נוסף על יעדים זמין במאמר הגדרת יעדים.

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

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

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

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

שדות של פעולות

ה-Data Manager API מכיל שיטות נפרדות להוספה ולהסרה של משתמשים מקהל היעד. לעומת זאת, השדה AddOfflineUserDataJobOperationsRequest ב-Google Ads API מכיל רשימה של operations, שכל אחד מהם מוסיף חבר, מסיר חבר או מסיר את כל החברים, בהתאם לסוג הפעולה. כאן מפורט המיפוי של כל סוג פעולה ל-method המתאים ב-Data Manager API:

OfflineUserDataJobOperation (Google Ads API)	IngestionService (Data Manager API)	הערות
create	IngestAudienceMembers	פרטים נוספים זמינים בקטע "שדות של משתמשים מקהל היעד".
remove	RemoveAudienceMembers	פרטים נוספים זמינים בקטע "שדות של משתמשים מקהל היעד".
remove_all	RemoveAllAudienceMembers	פרטים נוספים זמינים בקטע הסרת כל המשתמשים מקהל היעד.

שדות של משתמשים מקהל היעד

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

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

ב-Google Ads API, בין שאתם שולחים פרטים ליצירת קשר, Mobile ID (mID) או מזהי משתמשים, אתם משתמשים ב-UserIdentifier. ב-Data Manager API משתמשים בגישה אחרת, עם שדות שונים לכל סוג של נתונים.

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