تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تعيينات الحقول

استخدِم عمليات الربط في الجداول لربط طرق وحقول Google Ads API بما يعادلها في IngestEventsRequest في Data Manager API.

المصادقة

تتطلّب واجهة Data Manager API بيانات اعتماد بنطاق مختلف عن واجهة Google Ads API. اتّبِع الخطوات الواردة في مقالة إعداد إمكانية الوصول إلى واجهة برمجة التطبيقات لإنشاء بيانات اعتماد جديدة تتضمّن نطاق Data Manager 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` عنوان الطلب `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`. بالنسبة إلى 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)	ملاحظات
عنوان الطلب `developer-token` عنوان الطلب `login-customer_id` عنوان الطلب `linked-customer-id`	`destinations`	اطّلِع على حقول العميل وإجراء الإحالة الناجحة.
`resource_name`	بدون مكافئ	لا تتطلّب واجهة Data Manager API تعديل مورد مهمة.
`enable_partial_failure`	بدون مكافئ	إذا نجح `IngestEventsRequest`، يتم التعامل مع أي حالات تعذُّر تحدث أثناء المعالجة اللاحقة على مستوى الحدث، ما قد يؤدي إلى نجاح جزئي. استخدِم بيانات التشخيص لاسترداد حالة التحميل بالإضافة إلى الأخطاء والتحذيرات للأحداث الفردية. إذا تعذّر تنفيذ `IngestEventsRequest` (على سبيل المثال، بسبب `BadRequest`)، لن تتم معالجة أي أحداث وسيكون عليك حلّ الخطأ وإعادة محاولة إرسال الطلب. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة فهم أخطاء واجهة برمجة التطبيقات.
`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". اضبط `account_type` لـ `operating_account` على `GOOGLE_ADS`.
عنوان الطلب `developer-token`	بدون مكافئ	لا يتطلّب استخدام Data Manager API رمزًا مميّزًا للمطوّر.
عنوان الطلب `login-customer-id`	`login_account`	اضبط `account_id` على رقم تعريف العميل لحساب تسجيل الدخول. اضبط `account_type` على `GOOGLE_ADS` إذا كان حساب تسجيل الدخول هو حساب على "إعلانات Google"، أو `DATA_PARTNER` إذا كان حساب تسجيل الدخول هو حساب شريك بيانات.
عنوان الطلب `linked-customer-id`	`linked_account`	في حال الوصول إلى `operating_account` باستخدام رابط شريك، اضبط `account_id` على رقم تعريف العميل للحساب المرتبط واضبط `account_type` على `DATA_PARTNER`. وإلا، لا تضبط الحقل `linked_account`.
`conversion_action`	`product_destination_id`	يجب ضبط هذه السمة على المعرّف الرقمي لإجراء الإحالة الناجحة. لا تستخدِم اسم المورد.

حقول الحدث

يوضّح الجدول التالي كيفية ربط حقول الإحالة الناجحة للمبيعات في المتاجر بين واجهتَي برمجة التطبيقات.

على عكس 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`	تستخدم كلتا واجهتَي برمجة التطبيقات عنصر `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".
`address_info.state`	بدون مكافئ	غير متاحة لوجهات "إعلانات Google".
`address_info.hashed_street_address`	بدون مكافئ	غير متاحة لوجهات "إعلانات Google".

خطوات الترقية