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

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

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

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

upload_key_types

اضبط القيمة على قائمة تحتوي على CONTACT_INFO.

contact_id_info

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

اضبط قيمة data_source_type على DATA_SOURCE_TYPE_FIRST_PARTY.

Mobile IDs

upload_key_types

اضبط القيمة على قائمة تحتوي على MOBILE_ID.

mobile_id_info

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

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

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

upload_key_types

اضبط القيمة على قائمة تحتوي على USER_ID.

user_id_info

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

اضبط قيمة data_source_type على DATA_SOURCE_TYPE_FIRST_PARTY.

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

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