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

استخدِم عمليات ربط الحقول لترقية كل خطوة من خطوات سير عمل "مطابقة العملاء" من 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.

Mobile IDs

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 بمثيلها IngestAudienceMembersRequest في Data Manager API.

حقول الطلب

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 بدلاً من عناوين الطلبات. يمكنك الاطّلاع على إعداد الوجهات للحصول على مزيد من المعلومات حول الوجهات.

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

في ما يلي كيفية ربط حقول 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 اضبط قيمة account_id على رقم تعريف العميل الخاص بالحساب المرتبط. اضبط قيمة account_type على DATA_PARTNER.
user_list من customer_match_user_list_metadata OfflineUserDataJob product_destination_id مطلوبة. يتم ضبطه على المعرّف الرقمي لشريحة الجمهور. لا تستخدِم اسم المورد الخاص بـ UserList.
بدون مكافئ reference معرّف يحدّده المستخدم Destination. اضبط هذا الحقل إذا كنت ترسل أعضاء جمهور لعدة شرائح جمهور في طلب واحد.

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

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_id_data
  • user_id_data
  • user_identifiers

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

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

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

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

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

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

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 ما مِن مكافئ.

Mobile IDs

في حال استخدام معرّفات الأجهزة الجوّالة، اضبط 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 ما مِن مكافئ.
السابق
خطوات الترقية