Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מיפוי שדות

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

שיטות API

‫Data Manager API מאפשר להעלות כל קבוצה של אירועי מכירות בחנות הפיזית ב-IngestEventsRequest אחד.

לעומת זאת, ב-Google Ads API נדרש תהליך בן שלושה שלבים באמצעות OfflineUserDataJobService:

יצירת משרה באמצעות CreateOfflineUserDataJob
הוספת פעולות למשימה באמצעות AddOfflineUserDataJobOperations
הפעלת המשימה באמצעות RunOfflineUserDataJob

שדות של בקשה

כל IngestEventsRequest כפוף למגבלות על בקשות. אם מספר הפעולות בבקשה חורג מהמגבלות האלה, צריך לפצל את הבקשה לכמה בקשות להעברת נתונים באמצעות Data Manager API.AddOfflineUserDataJobOperations

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

`CreateOfflineUserDataJobRequest`

בטבלה הבאה אפשר לראות איך השדות של CreateOfflineUserDataJobRequest ממופים ל-IngestEventsRequest.

‫`CreateOfflineUserDataJobRequest` (Google Ads API)	‫`IngestEventsRequest` (Data Manager API)	הערות
`customer_id`	`destinations.operating_account`	מידע על שדות של לקוחות ופעולות המרה
כותרת הבקשה `developer-token` כותרת הבקשה `login-customer_id` כותרת הבקשה `linked-customer-id`	`destinations`	מידע על שדות של לקוחות ופעולות המרה
`job.status` `job.failure_reason`	אבחון	משתמשים בערך `request_id` שמוחזר ב-`IngestEventsResponse` כדי לאחזר אבחון לגבי העלאת ההמרות.
`job.id`	`request_id`	משתמשים בערך `request_id` שמוחזר ב-`IngestEventsResponse` כדי לאחזר אבחון לגבי העלאת ההמרות.
`job.external_id`	אין דוח מקביל
`job.type`	אין דוח מקביל
`job.store_sales_metadata.third_party_metadata.partner_id`	`destinations.login_account`	שותף נתונים שמעלה המרות מסוג מכירות בחנות יזוהה באמצעות `login_account` של יעד. מידע נוסף זמין במאמר בנושא הגדרת יעדים.
`job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time`	אין דוח מקביל
`job.store_sales_metadata.third_party_metadata.valid_transaction_fraction`	אין דוח מקביל
`job.store_sales_metadata.third_party_metadata.partner_match_fraction`	אין דוח מקביל
`job.store_sales_metadata.third_party_metadata.partner_upload_fraction`	אין דוח מקביל
`job.store_sales_metadata.third_party_metadata.bridge_map_version_id`	אין דוח מקביל
`job.store_sales_metadata.loyalty_fraction`	אין דוח מקביל
`job.store_sales_metadata.transaction_upload_fraction`	אין דוח מקביל
`job.store_sales_metadata.custom_key`	`events[].custom_variables[].variable` `events[].cart_data.items[].custom_variables[].variable`	מיפוי לשדה `variable` של `CustomVariable` ברמת האירוע או של `ItemCustomVariable` ברמת הפריט.
`enable_match_rate_range_preview`	אין דוח מקביל
`validate_only`	`validate_only`
אין דוח מקביל	`consent`	‫Google Ads API תומך רק בהגדרה של `consent` ברמת האירוע ב-`UserData`. ב-API של המרכז לניהול נתונים, אפשר לציין הסכמה לכל האירועים בבקשה על ידי הגדרת השדה `consent` ב-`IngestEventsRequest`. אפשר לשנות את הערך הזה לאירוע ספציפי על ידי הגדרת השדה `consent` של `Event`.
אין דוח מקביל	`encoding`	שדה חובה להעלאות של `UserData`. מגדירים את הערך `Encoding` שמשמש לערכי `UserIdentifier`.
אין דוח מקביל	`encryption_info`	הגדרה שמציינת אם הבקשה מכילה מזהי משתמשים מוצפנים של `UserData`. פרטים נוספים זמינים במאמר בנושא הצפנה.

`AddOfflineUserDataJobOperationsRequest`

בטבלה הבאה אפשר לראות איך השדות של AddOfflineUserDataJobOperationsRequest ממופים ל-IngestEventsRequest.

‫`AddOfflineUserDataJobOperationsRequest` (Google Ads API)	‫`IngestEventsRequest` (Data Manager API)	הערות
כותרת הבקשה `developer-token` כותרת הבקשה `login-customer_id` כותרת הבקשה `linked-customer-id`	`destinations`	מידע על שדות של לקוחות ופעולות המרה
`resource_name`	אין דוח מקביל	לא צריך לעדכן משאב של משימה ב-Data Manager API.
`enable_partial_failure`	אין דוח מקביל	אם `IngestEventsRequest` הפעולה מצליחה, כל הכשלים שמתרחשים במהלך העיבוד במורד הזרם מטופלים ברמת האירוע, מה שיכול להוביל להצלחה חלקית. אפשר להשתמש בדף אבחון כדי לאחזר את הסטטוס של ההעלאה, וגם שגיאות ואזהרות לגבי אירועים ספציפיים. אם `IngestEventsRequest` נכשל (לדוגמה, בגלל `BadRequest`), לא מתבצע עיבוד של אירועים ותצטרכו לפתור את השגיאה ולנסות שוב לשלוח את הבקשה. מידע נוסף מופיע במאמר הסבר על שגיאות ב-API.
`enable_warnings`	אין דוח מקביל	משתמשים באבחון כדי לאחזר אזהרות לגבי בקשת Data Manager API. אין צורך להפעיל את האפשרות הזו.
`operations`	`events`	הפעולה `OfflineUserDataJobOperation.create` שוות ערך לשליחת `IngestEventsRequest`. ה-API של Data Manager לא תומך בהסרת אירועים.
`validate_only`	`validate_only`
אין דוח מקביל	`consent`	‫Google Ads API תומך רק בהגדרה של `consent` ברמת האירוע ב-`UserData`. ב-API של המרכז לניהול נתונים, אפשר לציין הסכמה לכל האירועים בבקשה על ידי הגדרת השדה `consent` ב-`IngestEventsRequest`. אפשר לשנות את הערך הזה לאירוע ספציפי על ידי הגדרת השדה `consent` של `Event`.
אין דוח מקביל	`encoding`	שדה חובה להעלאות של `UserData`. מגדירים את הערך `Encoding` שמשמש לערכי `UserIdentifier`.
אין דוח מקביל	`encryption_info`	הגדרה שמציינת אם הבקשה מכילה מזהי משתמשים מוצפנים של `UserData`. פרטים נוספים זמינים במאמר בנושא הצפנה.

שדות של לקוחות ושל פעולות המרה

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

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

Google Ads API	‫`Destination` (Data Manager API)	הערות
`customer_id` של הבקשה	`operating_account`	מגדירים את `account_id` למספר הלקוח של חשבון ההמרות ב-Google Ads. מגדירים את `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`	אם אתם ניגשים אל `operating_account` באמצעות קישור לשותף, צריך להגדיר את `account_id` למספר הלקוח של החשבון המקושר ואת `account_type` לערך `DATA_PARTNER`. אחרת, לא מגדירים את השדה `linked_account`.
`conversion_action`	`product_destination_id`	מוגדר למזהה המספרי של פעולת ההמרה. אל תשתמשו בשם המשאב.

שדות של אירועים

בטבלה הבאה אפשר לראות איך השדות של מיפוי המרות למכירות בחנות הפיזית ממופים בין שני ממשקי ה-API.

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

‫`OfflineUserDataJobOperation.create` (Google Ads API)	‫`Event` (Data Manager API)	הערות
אין דוח מקביל	`event_source`	חובה להגדיר את הערך `IN_STORE` להמרות מסוג 'מכירות בחנות'.
`transaction_attribute.conversion_action`	`destinations.product_destination_id`	מידע על שדות של לקוחות ופעולות המרה משתמשים במזהה המספרי של פעולת ההמרה במקום בשם המשאב.
`transaction_attribute.transaction_date_time`	`event_timestamp`	אם משתמשים בפורמט JSON, צריך להגדיר ערך בפורמט RFC 3339, ששונה מעט מפורמט התאריך והשעה של Google Ads API. אם משתמשים ב-protocol buffers, צריך להשתמש ב-`Timestamp` ולהגדיר את השדות `seconds` ו-(אופציונלית) `nanoseconds`. פרטים נוספים מופיעים בקטע פורמט של חותמות זמן.
`transaction_attribute.transaction_amount_micros`	`conversion_value` (חובה) `cart_data.items[].conversion_value`	הערך שמוגדר הוא ערך המטבע, ולא ערך במיקרו. לדוגמה, אם ערך ההמרה הוא 5.23$, משתמשים בערך `5.23`.
`transaction_attribute.currency_code`	`currency`	חובה.
`transaction_attribute.order_id`	`transaction_id`	חובה.
`transaction_attribute.store_attribute.store_code`	`event_location.store_id`	חובה להגדיר את קוד החנות בשדה `store_id` באובייקט `EventLocation`.
`transaction_attribute.custom_value`	`custom_variables[].value` `cart_data.items[].custom_variables[].value`	מיפוי לשדה `value` של `CustomVariable` ברמת האירוע או של `ItemCustomVariable` ברמת הפריט.
`transaction_attribute.item_attribute.item_id`	`cart_data.items[].merchant_product_id`
`transaction_attribute.item_attribute.merchant_id`	`cart_data.merchant_id` `cart_data.items[].merchant_id`	אם מגדירים את `cart_data.merchant_id`, הוא משמש כברירת מחדל לכל הפריטים, אבל אפשר לשנות אותו לפריטים ספציפיים.
`transaction_attribute.item_attribute.country_code`	`cart_data.merchant_feed_label` `cart_data.items[].merchant_feed_label`	אם מגדירים את `cart_data.merchant_feed_label`, הוא משמש כברירת מחדל לכל הפריטים, אבל אפשר לשנות אותו לפריטים ספציפיים.
`transaction_attribute.item_attribute.language_code`	`cart_data.merchant_feed_language_code` `cart_data.items[].merchant_feed_language_code`	אם מגדירים את `cart_data.merchant_feed_language_code`, הוא משמש כברירת מחדל לכל הפריטים, אבל אפשר לשנות אותו לפריטים ספציפיים.
`transaction_attribute.item_attribute.quantity`	`cart_data.items[].quantity`
אין דוח מקביל	`cart_data.items[].unit_price`	המחיר ליחידה, לא כולל מס, משלוח והנחות ברמת האירוע (ברמת העסקה) של הפריט הזה.
`user_identifiers`	`user_data.user_identifiers` `third_party_user_data.user_identifiers`	נדרש. `third_party_user_data` משתמש באותה מבנה כמו `user_data`, אבל מציין שמזהי המשתמשים מגיעים ממקור צד שלישי ולא מנתוני מפרסם מאינטראקציה ישירה. מותר לאכלס את `third_party_user_data` רק אם חשבון הכניסה הוא שותף נתונים (`login_account.account_type` הוא `DATA_PARTNER`). פרטים נוספים זמינים במאמר בנושא שדות של מזהה משתמש.
`consent`	`consent`	בשני ממשקי ה-API נעשה שימוש באובייקט `Consent` דומה (`ad_user_data`, `ad_personalization`). ב-Data Manager API אפשר גם להגדיר הסכמה לכל האירועים בבקשה על ידי הגדרת השדה `consent` ב-`IngestEventsRequest`.

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

‫`UserIdentifier` (Google Ads API)	‫`UserIdentifier` (Data Manager API)	הערות
`user_identifier_source`	המקור קובע איזה שדה יאוכלס ב-Data Manager API `Event`: `user_data` `third_party_user_data`	`third_party_user_data` משתמש באותה מבנה כמו `user_data`, אבל מציין שמזהי המשתמשים מגיעים ממקור צד שלישי ולא מנתוני מפרסם מאינטראקציה ישירה. מותר לאכלס את `third_party_user_data` רק אם חשבון הכניסה הוא שותף נתונים (`login_account.account_type` הוא `DATA_PARTNER`). פרטים נוספים זמינים במאמר בנושא שדות של מזהה משתמש.
`hashed_email`	`email_address`	הערך שמוגדר הוא כתובת האימייל בפורמט הנכון עם גיבוב. אפשר גם להצפין את כתובת האימייל שעברה גיבוב.
`hashed_phone_number`	`phone_number`	הערך מוגדר למספר הטלפון בפורמט מגובב. אפשר גם להצפין את מספר הטלפון המגובב.
`address_info`	`address`	מוגדר לאובייקט `AddressInfo`. פועלים לפי ההנחיות בנוגע לפורמט ולגיבוב. אפשר גם להצפין את מאפייני הכתובת שעברו גיבוב.
`address_info.hashed_first_name`	`address.given_name`
`address_info.hashed_last_name`	`address.family_name`
`address_info.country_code`	`address.region_code`
`address_info.postal_code`	`address.postal_code`
`address_info.city`	אין דוח מקביל	אין תמיכה בגרסה הנוכחית של Data Manager API.
`address_info.state`	אין דוח מקביל	אין תמיכה בגרסה הנוכחית של Data Manager API.
`address_info.hashed_street_address`	אין דוח מקביל	אין תמיכה בגרסה הנוכחית של Data Manager API.

שלבים לשדרוג