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

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

استخدِم عمليات الربط في الجداول لربط طرق Google Ads API وحقولها بمثيلاتها IngestEventsRequest في 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. في حال استخدام بروتوكولات المخزن المؤقت، استخدِم `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`	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.
`address_info.state`	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.
`address_info.hashed_street_address`	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.

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