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

استخدِم عمليات ربط الحقول لترقية كل خطوة من سير عمل "مطابقة العملاء" من Google Ads API إلى Data Manager API:

المصادقة

تتطلّب واجهة Data Manager API بيانات اعتماد بنطاق مختلف عن واجهة Google Ads API. اتّبِع الخطوات الواردة في مقالة إعداد إمكانية الوصول إلى واجهة برمجة التطبيقات لإنشاء بيانات اعتماد جديدة تتضمّن نطاق Data Manager API.

عمليات ربط حقول إدارة الجمهور

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

‫UserList (Google Ads API) ‫UserList (Data Manager API) ملاحظات
resource_name name لمزيد من التفاصيل، يُرجى الاطّلاع على أسماء الموارد.
id id
read_only read_only
name display_name مطلوب
description description مطلوب
membership_status membership_status
integration_code integration_code
membership_life_span membership_duration

المدة التي يبقى فيها عضو في الجمهور في القائمة بعد إضافته يجب أن تتوافق القيمة مع أيام كاملة. في حال عدم ضبط هذه السمة، يتم ضبطها تلقائيًا على الحد الأقصى.

يجب تنسيق القيمة باستخدام تنسيق الطابع الزمني.
size_for_display size_info.display_network_members_count
size_range_for_display ما مِن مكافئ. استخدِم السمة size_info.display_network_members_count لإضافة معلومات المقاس.
size_for_search size_info.search_network_members_count
size_range_for_search ما مِن مكافئ. استخدِم السمة size_info.search_network_members_count لإضافة معلومات المقاس.
type ما مِن مكافئ.
access_reason access_reason
account_user_list_status account_access_status
closing_reason closing_reason
eligible_for_search target_network_info.eligible_for_search
eligible_for_display target_network_info.eligible_for_display
match_rate_percentage ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list ingested_user_list_info.pseudonymous_id_info لا يتم استخدامها في "مطابقة العملاء".
crm_based_user_list ingested_user_list_info هذا العنصر مطلوب. اطّلِع على معلومات جمهور "مطابقة العملاء".
ما مِن مكافئ. ingested_user_list_info.pair_id_info لا يتم استخدامها في "مطابقة العملاء".
ما مِن مكافئ. ingested_user_list_info.partner_audience_info لا يتم استخدامها في "مطابقة العملاء".
logical_user_list ما مِن مكافئ. لا يتم استخدامها في "مطابقة العملاء".
logical_user_list ما مِن مكافئ. لا يتم استخدامها في "مطابقة العملاء".
lookalike_user_list ما مِن مكافئ. لا يتم استخدامها في "مطابقة العملاء".
rule_based_user_list ما مِن مكافئ. لا يتم استخدامها في "مطابقة العملاء".
similar_user_list ما مِن مكافئ. لا يتم استخدامها في "مطابقة العملاء".

معلومات عن جمهور "مطابقة العملاء"

في Google Ads API، عليك ضبط الحقل crm_based_user_list على CrmBasedUserListInfo عند إنشاء شريحة جمهور من "مطابقة العملاء".

في Data Manager API، اضبط السمات المكافئة من خلال ضبط الحقل ingested_user_list_info على IngestedUserListInfo، ثم اضبط الحقول المطلوبة لميزة "مطابقة العملاء" ونوع بيانات المستخدمين.

معلومات الاتصال

upload_key_types
يتم ضبطه على قائمة تحتوي على CONTACT_ID. ويعادل ذلك ضبط upload_key_type على CONTACT_INFO في Google Ads API.
contact_id_info

اضبط السمة على ContactIdInfo.

اضبط النوع data_source_type على DATA_SOURCE_TYPE_FIRST_PARTY. ويعادل ذلك ضبط data_source_type على FIRST_PARTY في Google Ads API.

بيانات تعريف رقمية

upload_key_types
يتم ضبطه على قائمة تحتوي على MOBILE_ID. ويعادل ذلك ضبط upload_key_type على MOBILE_ADVERTISING_ID في Google Ads API.
mobile_id_info

اضبط السمة على MobileIdInfo.

  • اضبط النوع data_source_type على DATA_SOURCE_TYPE_FIRST_PARTY. ويعادل ذلك ضبط data_source_type على FIRST_PARTY في Google Ads API.
  • اضبط السمة key_space على IOS أو ANDROID. تتطلّب واجهة Data Manager API هذه القيمة. ويختلف ذلك عن Google Ads API، حيث يتم استنتاج مساحة المفتاح من app_id.
  • اضبط app_id على السلسلة التي تحدّد بشكل فريد تطبيق الأجهزة الجوّالة الذي تم جمع البيانات منه. استخدِم التنسيق نفسه الذي تستخدمه مع app_id في Google Ads API.

أرقام تعريف المستخدمين

upload_key_types
يتم ضبطه على قائمة تحتوي على USER_ID. ويعادل ذلك ضبط upload_key_type على CRM_ID في Google Ads API.
user_id_info

اضبط السمة على UserIdInfo.

اضبط النوع data_source_type على DATA_SOURCE_TYPE_FIRST_PARTY. ويعادل ذلك ضبط data_source_type على FIRST_PARTY في Google Ads API.

أسماء الموارد

تستخدم Data Manager API تنسيقًا مختلفًا لاسم المورد عن Google Ads API.

Google Ads API

في Google Ads API، يستخدم اسم المورد UserList التنسيق التالي:

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

في Data Manager API، يستخدم اسم المورد UserList التنسيق التالي:

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

تحميل عمليات ربط الحقول

استخدِم عمليات الربط في الجداول لربط AddOfflineUserDataJobOperationsRequest في Google Ads API بطلب IngestionService المكافئ له في Data Manager API.

حقول الطلب

تستخدم عمليات الربط هذه IngestAudienceMembersRequest في Data Manager API كمرجع، ولكن يمكنك أيضًا استخدام عمليات الربط هذه إذا كنت تحوّل طلب بيانات من واجهة برمجة التطبيقات في Google Ads API إلى RemoveAudienceMembersRequest أو RemoveAllAudienceMembersRequest.

AddOfflineUserDataJobOperationsRequest (Google Ads API) IngestAudienceMembersRequest (Data Manager API) ملاحظات
  • حقل customer_id
  • حقل واحد (customer_match_user_list_metadata) من إجمالي OfflineUserDataJob
  • عنوان الطلب developer-token
  • عنوان الطلب login-customer_id
  • عنوان الطلب linked-customer-id
 destinations يُرجى الاطّلاع على حقول العملاء والجمهور.
‫consent من customer_match_user_list_metadata في OfflineUserDataJob consent إعدادات الموافقة التلقائية الاختيارية لأعضاء الجمهور في الطلب ويمكنك إلغاء هذه القيمة لعضو فردي في الجمهور من خلال ضبط حقل consent في AudienceMember.
بدون مكافئ encoding مطلوبة: يجب ضبطها على Encoding المستخدَمة لقيم UserIdentifier.
بدون مكافئ encryption_info يتم ضبط هذه السمة إذا كان الطلب يحتوي على قيم مشفّرة. يُرجى الاطّلاع على التشفير لمزيد من التفاصيل.
job_id بدون مكافئ استخدِم request_id الذي تم عرضه في الردّ لاسترداد بيانات التشخيص.
enable_partial_failure بدون مكافئ تستخدم واجهة Data Manager API نموذج خطأ الإخفاق السريع. إذا تعذّر التحقّق من صحة أي حقل في IngestAudienceMembersRequest، ترفض Data Manager API الطلب بأكمله. استرداد أخطاء المعالجة باستخدام بيانات التشخيص
enable_warnings بدون مكافئ لا تُبلغ واجهة Data Manager API عن التحذيرات في الردّ. استرداد تحذيرات المعالجة باستخدام بيانات التشخيص
validate_only validate_only
operations audience_members قائمة أعضاء الجمهور المطلوب إضافتهم أو إزالتهم لمزيد من التفاصيل، يُرجى الاطّلاع على قسم حقول العمليات.
بدون مكافئ terms_of_service هذا العنصر مطلوب. يتم ضبط هذه السمة للإشارة إلى أنّ المستخدم قد وافق على بنود الخدمة الخاصة بميزة "مطابقة العملاء" أو رفضها.

حقول العملاء والجمهور

تتيح Google Ads API تحميل أعضاء الجمهور إلى جمهور واحد فقط لكل مهمة.بالإضافة إلى ذلك، يجب استخدام عنوان الطلب developer-token، ويمكنك ضبط عنوانَي الطلب login-customer-id وlinked-customer-id لسيناريوهات المصادقة المختلفة.

تتيح واجهة Data Manager API إرسال أعضاء الجمهور لشرائح جمهور متعددة في طلب واحد. لا تتطلّب واجهة Data Manager API رمزًا مميّزًا للمطوّر، ويمكنك تحديد معلومات تسجيل الدخول ومعلومات العملاء المرتبطين باستخدام حقول Destination بدلاً من عناوين الطلبات. يمكنك الاطّلاع على مقالة ضبط الوجهات لمزيد من المعلومات حول الوجهات.

في Google Ads API، يمكنك إزالة جميع أعضاء شريحة جمهور من خلال ضبط الحقل remove_all في OfflineUserDataJobOperation على true.

في Data Manager API، يمكنك تحقيق ذلك من خلال إرسال RemoveAllAudienceMembersRequest. يُرجى الاطّلاع على دليل إزالة جميع الأعضاء لمزيد من التفاصيل.

في ما يلي كيفية ربط حقول Google Ads API لشريحة جمهور واحدة بالحقول المكافئة في Destination:

Google Ads API Destination (Data Manager API) ملاحظات
‫customer_id من الطلب operating_account اضبط account_id على رقم تعريف العميل للجمهور. اضبط السمة 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.
‫user_list من customer_match_user_list_metadata الخاصة بـ OfflineUserDataJob product_destination_id هذا العنصر مطلوب. يتم ضبطها على رقم التعريف الرقمي للجمهور. لا تستخدِم اسم المورد الخاص بـ UserList.
بدون مكافئ reference معرّف يحدّده المستخدم لـ Destination. اضبط هذا الحقل إذا كنت ترسل أعضاء في الجمهور لشرائح جمهور متعددة في طلب واحد.

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

تحتوي Data Manager API على طرق منفصلة لإضافة أعضاء الجمهور وإزالتهم. في المقابل، يحتوي الحقل AddOfflineUserDataJobOperationsRequest في Google Ads API على قائمة من operations، يضيف كلّ منها عضوًا أو يزيله أو يزيل جميع الأعضاء استنادًا إلى نوع العملية. في ما يلي عملية ربط كل نوع عملية بالطريقة المقابلة له في Data Manager API:

OfflineUserDataJobOperation (Google Ads API) IngestionService (Data Manager API) ملاحظات
create IngestAudienceMembers لمعرفة التفاصيل، يُرجى الاطّلاع على قسم حقول أعضاء الجمهور.
remove RemoveAudienceMembers لمعرفة التفاصيل، يُرجى الاطّلاع على قسم حقول أعضاء الجمهور.
remove_all RemoveAllAudienceMembers يُرجى الاطّلاع على إزالة جميع أعضاء الجمهور لمزيد من التفاصيل.

حقول أعضاء الجمهور

UserData (Google Ads API) AudienceMember (Data Manager API) ملاحظات
consent consent

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

تستخدم كلتا واجهتَي برمجة التطبيقات عنصر Consent مشابهًا (ad_user_data وad_personalization).

بالنسبة إلى Data Manager API، يمكنك أيضًا ضبط الموافقة لجميع أعضاء الجمهور في طلب معيّن من خلال ضبط حقل consent على مستوى الطلب.
transaction_attribute ما مِن مكافئ. لا ينطبق ذلك على "مطابقة العملاء".
user_attribute ما مِن مكافئ. لا ينطبق ذلك على "مطابقة العملاء".
user_identifiers
  • mobile_data
  • user_id_data
  • composite_data
    • user_data
    • ip_data

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

حقول معرّفات المستخدمين

في Google Ads API، سواء كنت ترسل معلومات الاتصال أو بيانات تعريف رقمية أو أرقام تعريف المستخدمين، يمكنك استخدام UserIdentifier. تستخدم واجهة برمجة التطبيقات Data Manager API نهجًا مختلفًا، مع حقول مختلفة لكل نوع من البيانات.

في Data Manager API، املأ الحقل الذي يتوافق مع نوع البيانات التي ترسلها:

معلومات الاتصال

في حال استخدام معلومات الاتصال، مثل عنوان البريد الإلكتروني أو رقم الهاتف أو معلومات العنوان، اضبط السمة composite_data على CompositeData مع إدخال منفصل في السمة user_data.user_identifiers لكل عنصر من عناصر معلومات الاتصال.

مع أنّنا ما زلنا نتيح استخدام user_data، ننصحك باستخدام composite_data لضمان أنّ عملية الدمج جاهزة للتحسينات المستقبلية. يُرجى الاطّلاع على البيانات المركّبة لمزيد من التفاصيل.

UserIdentifier (Google Ads API) UserIdentifier (Data Manager API) ملاحظات
address_info address لمزيد من التفاصيل، يُرجى الاطّلاع على حقول العناوين.
hashed_email email_address اضبط هذه السمة على عنوان البريد الإلكتروني المُنسَّق والمُجزَّأ. يمكنك أيضًا تشفير عنوان البريد الإلكتروني المُجزّأ.
hashed_phone_number phone_number يجب ضبطها على رقم الهاتف المُنسَّق والمُجزَّأ. يمكنك أيضًا تشفير رقم الهاتف المجزّأ.
user_identifier_source ما مِن مكافئ.

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

في ما يلي عمليات ربط الحقول بين OfflineUserAddressInfo في Google Ads API و AddressInfo في Data Manager API. استخدِم عمليات الربط هذه إذا كنت تستخدم معلومات الاتصال لتعبئة جمهور "مطابقة العملاء".

OfflineUserAddressInfo (Google Ads API) AddressInfo (Data Manager API) ملاحظات
city ما مِن مكافئ.
country_code region_code مطلوب
hashed_first_name given_name

هذا العنصر مطلوب. يجب ضبط هذه السمة على الاسم الأول المُجزَّأ والمُنسَّق. يمكنك أيضًا تشفير الاسم الأول المجزّأ.
hashed_last_name family_name

هذا العنصر مطلوب. يجب ضبط هذه السمة على اسم العائلة المُجزَّأ والمُنسَّق. يمكنك أيضًا تشفير اسم العائلة المُجزَّأ.
hashed_street_address ما مِن مكافئ.
postal_code postal_code مطلوب
state ما مِن مكافئ.

عنوان IP

تتيح واجهة Data Manager API تضمين عناوين IP لعمليات تحميل "مطابقة العملاء" بالإضافة إلى معرّفات المستخدمين. يتم توفير هذه الميزات في CompositeData التي تتضمّن UserData وIpData. يمكن أن يساعد تقديم هذه الحقول معًا في تحسين نِسب المطابقة.

لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة استيراد عناوين IP في ميزة "مطابقة العملاء".

Google Ads API CompositeData (Data Manager API) ملاحظات
ما مِن مكافئ. ip_data.ip_address يتم ضبطه على عنوان IPv4 أو IPv6 الأولي. اطّلِع على إرشادات تنسيق عنوان IP.
ما مِن مكافئ. ip_data.observe_start_time يجب ضبط هذه السمة على الطابع الزمني بتنسيق RFC 3339 الذي تم فيه رصد عنوان IP لأول مرة.
ما مِن مكافئ. ip_data.observe_end_time يجب ضبط هذه السمة على الطابع الزمني بتنسيق RFC 3339 الذي تم فيه رصد عنوان IP آخر مرة.
user_identifiers user_data يجب ضبطها على عنصر UserData.

بيانات تعريف رقمية

في حال استخدام بيانات التعريف الرقمية، اضبط السمة mobile_data على MobileData مع إدخال في mobile_ids لكل معرّف.

UserIdentifier (Google Ads API) MobileData (Data Manager API) ملاحظات
mobile_id mobile_ids يجب ضبطها على قائمة بيانات تعريف رقمية للعضو في الجمهور.

في Google Ads API، يمكنك إضافة منفصل UserIdentifier مع mobile_id لكل بيانات تعريف رقمية خاصة بعضو الجمهور. في Data Manager API، أضِف MobileData واحدًا مع ضبط mobile_ids على قائمة جميع أرقام تعريف الأجهزة الجوّالة لعضو الجمهور.

user_identifier_source ما مِن مكافئ.

أرقام تعريف المستخدمين

في حال استخدام أرقام تعريف المستخدمين، اضبط user_id_data على UserIdData، واضبط user_id على رقم تعريف المستخدم الخاص بالعضو في الجمهور.

UserIdentifier (Google Ads API) UserIdData (Data Manager API) ملاحظات
third_party_user_id user_id

في Google Ads API، يمكنك إضافة منفصل UserIdentifier مع third_party_user_id لكل رقم تعريف مستخدم لعضو في الجمهور.

في Data Manager API، اضبط الحقل user_id_data على UserIdData، واضبط الحقل user_id على رقم تعريف المستخدم الخاص بالعضو في الجمهور. لا يمكنك إرسال أرقام تعريف مستخدمين متعددة لعضو الجمهور نفسه.

user_identifier_source ما مِن مكافئ.
السابق
خطوات الترقية