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

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

ملاحظة مهمة: لا تضبط الحقل address إلا إذا كانت لديك قيمة لكل حقل مطلوب. وفي حال عدم إجراء ذلك، سيتعذّر تنفيذ طلب بيانات من واجهة برمجة التطبيقات من Data Manager API. يختلف ذلك عن واجهة Google Ads 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 لميزة "مطابقة العملاء" لمزيد من التفاصيل.

ملاحظة: مع أنّنا نشجّعك على تضمين عنوان IP والطابع الزمني، من المتوقّع أن تبدأ التحسينات على معدّل المطابقة من خلال هاتين الإشارتين في أكتوبر 2026.

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