‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

מיפוי שדות

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

אימות

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

שיטות API

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

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

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

שדות של בקשות

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

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

`CreateOfflineUserDataJobRequest`

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

‫`CreateOfflineUserDataJobRequest` (Google Ads API)	‫`IngestEventsRequest` (Data Manager API)	הערות
`customer_id`	`destinations.operating_account`	מידע על שדות של לקוחות ופעולות המרה
`developer-token` request header `login-customer_id` request header `linked-customer-id` request header	`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` request header `login-customer_id` request header `linked-customer-id` request header	`destinations`	מידע על שדות של לקוחות ופעולות המרה
`resource_name`	אין דוח מקביל	לא צריך לעדכן משאב של משימה ב-Data Manager API.
`enable_partial_failure`	אין דוח מקביל	אם `IngestEventsRequest` מצליח, כל הכשלים שמתרחשים במהלך העיבוד בהמשך המערכת מטופלים ברמת האירוע, מה שיכול להוביל להצלחה חלקית. אפשר להשתמש בכלי ניתוח כדי לאחזר את סטטוס ההעלאה, וגם שגיאות ואזהרות לגבי אירועים ספציפיים. אם `IngestEventsRequest` הבקשה נכשלת (לדוגמה, בגלל `BadRequest`), לא מתבצע עיבוד של אירועים ותצטרכו לפתור את השגיאה ולנסות לשלוח את הבקשה שוב. מידע נוסף מופיע במאמר הסבר על שגיאות ב-API.
`enable_warnings`	אין דוח מקביל	אפשר להשתמש באבחון כדי לאחזר אזהרות לגבי בקשת Data Manager API. אין צורך להפעיל את האפשרות הזו.
`operations`	`events`	הפעולה `OfflineUserDataJobOperation.create` שקולה לשליחת `IngestEventsRequest`. ה-Data Manager API לא תומך בהסרת אירועים.
`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` 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`.
`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`	אין דוח מקביל	אין תמיכה ביעדים ב-Google Ads.
`address_info.state`	אין דוח מקביל	אין תמיכה ביעדים ב-Google Ads.
`address_info.hashed_street_address`	אין דוח מקביל	לא נתמך ביעדים ב-Google Ads.

שלבים לשדרוג