מיפוי שדות

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

אימות

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

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

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

upload_key_types
מוגדר לרשימה שמכילה את CONTACT_ID. זה שווה להגדרה של upload_key_type ל-CONTACT_INFO ב-Google Ads API.
contact_id_info

הערך שמוגדר הוא ContactIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY. ההגדרה הזו מקבילה להגדרת הערך data_source_type ל-FIRST_PARTY ב-Google Ads API.

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

upload_key_types
מוגדר לרשימה שמכילה את MOBILE_ID. זה שווה להגדרה של upload_key_type ל-MOBILE_ADVERTISING_ID ב-Google Ads API.
mobile_id_info

הערך שמוגדר הוא MobileIdInfo.

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

מזהי משתמשים

upload_key_types
מוגדר לרשימה שמכילה את USER_ID. זה שווה להגדרה של upload_key_type ל-CRM_ID ב-Google Ads API.
user_id_info

הערך שמוגדר הוא UserIdInfo.

מגדירים את data_source_type להיות DATA_SOURCE_TYPE_FIRST_PARTY. ההגדרה הזו מקבילה להגדרת הערך data_source_type ל-FIRST_PARTY ב-Google Ads API.

שמות המשאבים

הפורמט של שם המשאב ב-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, אבל אפשר להשתמש בהם גם אם ממירים את בקשת ה-API ב-Google Ads API ל-RemoveAudienceMembersRequest או ל-RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) הערות
  • שדה אחד (customer_id)
  • השדה customer_match_user_list_metadata של OfflineUserDataJob
  • developer-token request header
  • login-customer_id request header
  • linked-customer-id request header
 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.
developer-token request header אין דוח מקביל לא נדרש קוד מפתח לשימוש ב-Data Manager API.
login-customer-id request header login_account מגדירים את account_id למספר הלקוח של חשבון הכניסה. מגדירים את account_type לערך GOOGLE_ADS אם חשבון הכניסה הוא חשבון Google Ads, או לערך DATA_PARTNER אם חשבון הכניסה הוא חשבון של שותף נתונים.
linked-customer-id request header 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, שכל אחד מהם מוסיף חבר, מסיר חבר או מסיר את כל החברים בהתאם לסוג הפעולה. הטבלה הבאה מציגה את המיפוי של כל סוג פעולה לשיטה המתאימה ב-Data Manager API:

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

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

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

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

למרות שעדיין יש תמיכה ב-user_data מומלץ להשתמש ב-composite_data כדי לוודא שהשילוב מוכן לשיפורים עתידיים. פרטים נוספים זמינים במאמר בנושא נתונים מורכבים.

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

חובה. ההגדרה היא שם המשפחה בפורמט מגובב. אפשר גם להצפין את שם המשפחה שעבר גיבוב.
hashed_street_address אין מקבילה.
postal_code postal_code חובה
state אין מקבילה.

כתובת IP

‫Data Manager API תומך בהכללת כתובות IP בהעלאות של קהלים מסוג "התאמה ללקוחות", בנוסף למזהי משתמשים. הם מסופקים בחבילה CompositeData, שכוללת את UserData ואת IpData. צירוף השדות האלה יכול לשפר את שיעורי ההתאמה.

פרטים נוספים זמינים במאמר העברה של כתובות IP לצורך התאמה ללקוחות.

Google Ads API CompositeData (Data Manager API) הערות
אין מקבילה. ip_data.ip_address הערך מוגדר לכתובת IPv4 או IPv6 הגולמית. אפשר לעיין בהנחיות בנושא פורמט של כתובת IP.
אין מקבילה. ip_data.observe_start_time מוגדר לחותמת הזמן בפורמט RFC 3339 שבה נצפתה כתובת ה-IP בפעם הראשונה.
אין מקבילה. ip_data.observe_end_time מוגדר לחותמת הזמן בפורמט RFC 3339 שבה נצפתה כתובת ה-IP בפעם האחרונה.
user_identifiers user_data הגדרה לאובייקט UserData.

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

אם משתמשים במזהים לנייד, מגדירים את 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 אין מקבילה.
הקודם
שלבים לשדרוג