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

מיפוי שדות

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

אימות

‫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.

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

`CreateOfflineUserDataJobRequest`

בטבלה הבאה מוצג המיפוי של השדות של CreateOfflineUserDataJobRequest ל-IngestEventsRequest.

`CreateOfflineUserDataJobRequest` (Google Ads API)	`IngestEventsRequest` (Data Manager API)	הערות
`customer_id`	`destinations.operating_account`	שדות של לקוחות ופעולות המרה
‫request header של `developer-token` ‫request header של `login-customer_id` ‫request header של `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`. ב-Data Manager API, אפשר לציין הסכמה לכל האירועים בבקשה על ידי הגדרת השדה `consent` ב-`IngestEventsRequest`. אפשר לשנות את הערך הזה לאירוע ספציפי על ידי הגדרת השדה `consent` של `Event`.
אין דוח מקביל	`encoding`	נדרש להעלאת קובצי `UserData`. מגדירים את `Encoding` שמשמש לערכי `UserIdentifier`.
אין דוח מקביל	`encryption_info`	צריך להגדיר אם הבקשה מכילה מזהי משתמשים מוצפנים של `UserData`. פרטים נוספים זמינים במאמר הצפנה.

`AddOfflineUserDataJobOperationsRequest`

בטבלה הבאה מוצג המיפוי של השדות של AddOfflineUserDataJobOperationsRequest ל-IngestEventsRequest.

`AddOfflineUserDataJobOperationsRequest` (Google Ads API)	`IngestEventsRequest` (Data Manager API)	הערות
‫request header של `developer-token` ‫request header של `login-customer_id` ‫request header של `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`. ‫Data Manager API לא תומך בהסרת אירועים.
`validate_only`	`validate_only`
אין דוח מקביל	`consent`	‫Google Ads API תומך רק בציון של `consent` ברמת האירוע ב-`UserData`. ב-Data Manager 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`.
‫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`.
`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. אם משתמשים במאגרי אחסון לפרוטוקולים, צריך להשתמש ב-`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`, אבל מציין שמזהי המשתמשים מגיעים ממקור של צד שלישי, ולא מנתונים מאינטראקציה ישירה (First-Party) של המפרסם. אפשר לאכלס את `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`, אבל מציין שמזהי המשתמשים מגיעים ממקור של צד שלישי, ולא מנתונים מאינטראקציה ישירה (First-Party) של המפרסם. אפשר לאכלס את `third_party_user_data` רק אם החשבון המחובר הוא שותף נתונים (`login_account.account_type` הוא `DATA_PARTNER`). פרטים נוספים זמינים בקטע שדות של מזהי משתמשים.
`hashed_email`	`email_address`	מגדירים את כתובת האימייל בפורמט הנכון ועם גיבוב (hash). אפשר גם להצפין את כתובת האימייל המגובבת.
`hashed_phone_number`	`phone_number`	מגדירים את מספר הטלפון בפורמט הנכון ומגובב. אפשר גם להצפין את מספר הטלפון המגובב.
`address_info`	`address`	צריך להגדיר לאובייקט `AddressInfo`. פועלים לפי ההנחיות בנושא פורמט וגיבוב (hash). אפשר גם להצפין את המאפיינים המגובבים של כתובת.
`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.

שלבים לשדרוג