نقشه برداری های میدانی

از نگاشت‌های فیلد برای ارتقاء هر مرحله از گردش کار تطبیق مشتری خود از API گوگل ادز به API مدیریت داده استفاده کنید:

• نگاشت‌های میدانی مدیریت مخاطبان شامل نگاشت‌های میدانی برای ایجاد، به‌روزرسانی و بازیابی مخاطبان است.

• نگاشت‌های فیلد مصرف شامل نگاشت‌های فیلد برای اضافه کردن یا حذف کردن اعضای مخاطب است.

نگاشت‌های میدانی مدیریت مخاطبان

از نگاشت‌های موجود در جداول برای نگاشت یک UserList در API گوگل ادز به UserList آن در API مدیریت داده استفاده کنید.

UserList (API تبلیغات گوگل)	UserList (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
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	مدت زمانی که یک عضو مخاطب پس از اضافه شدن در لیست باقی می‌ماند. مقدار باید معادل کل روزها باشد. اگر تنظیم نشود، به طور پیش‌فرض روی حداکثر تنظیم می‌شود. مقدار را با استفاده از قالب Timestamp قالب‌بندی کنید.
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	الزامی است. به اطلاعات مخاطب Customer Match مراجعه کنید.
معادلی ندارد.	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	معادلی ندارد.	برای تطبیق مشتری استفاده نمی‌شود.

اطلاعات مخاطب Customer Match

در API گوگل ادز، فیلد crm_based_user_list هنگام ایجاد مخاطب Customer Match الزامی است.

در رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، با تنظیم فیلد ingested_user_list_info به IngestedUserListInfo ، ویژگی‌های معادل را تنظیم کنید، سپس فیلدهای مورد نیاز برای Customer Match و نوع داده‌های کاربر را تنظیم کنید.

اطلاعات تماس

upload_key_types

روی لیستی شامل CONTACT_INFO تنظیم شود.

contact_id_info

روی ContactIdInfo تنظیم کنید.

data_source_type را روی DATA_SOURCE_TYPE_FIRST_PARTY تنظیم کنید.

شناسه‌های موبایل

upload_key_types

روی لیستی شامل MOBILE_ID تنظیم شود.

mobile_id_info

روی MobileIdInfo تنظیم کنید.

• data_source_type را روی DATA_SOURCE_TYPE_FIRST_PARTY تنظیم کنید.
• key_space روی IOS یا ANDROID تنظیم کنید.
• app_id روی رشته‌ای تنظیم کنید که به طور منحصر به فرد، برنامه تلفن همراهی را که داده‌ها از آن جمع‌آوری شده‌اند، مشخص می‌کند. از همان قالبی که برای شناسه برنامه در API تبلیغات گوگل استفاده می‌کنید، استفاده کنید.

شناسه‌های کاربری

upload_key_types

روی لیستی شامل USER_ID تنظیم می‌شود.

user_id_info

روی UserIdInfo تنظیم شود.

data_source_type را روی DATA_SOURCE_TYPE_FIRST_PARTY تنظیم کنید.

نام منابع

رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) از قالب نام منبع متفاوتی نسبت به رابط برنامه‌نویسی کاربردی گوگل ادز (Google Ads API) استفاده می‌کند.

رابط برنامه‌نویسی کاربردی گوگل ادز

در API گوگل ادز، نام منبع UserList از قالب زیر استفاده می‌کند:

customers/{customer_id}/userLists/{user_list_id}

رابط برنامه‌نویسی کاربردی مدیریت داده

در رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، نام منبع UserList از قالب زیر استفاده می‌کند:

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

نقشه‌های میدانی را بارگذاری کنید

از نگاشت‌های موجود در جداول برای نگاشت یک AddOfflineUserDataJobOperationsRequest در API گوگل ادز به معادل آن در IngestAudienceMembersRequest در API مدیریت داده استفاده کنید.

فیلدهای درخواست

درخواست عملیات شغلی ( AddOfflineUserDataJobOperationsRequest ) (رابط برنامه‌نویسی کاربردی تبلیغات گوگل)	درخواست اعضای ورودی ( IngestAudienceMembersRequest ) (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
فیلد 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 اعتبارسنجی نشود، رابط برنامه‌نویسی کاربردی مدیریت داده کل درخواست را رد می‌کند. خطاهای پردازش را با استفاده از تشخیص بازیابی کنید.
enable_warnings	معادلی وجود ندارد	رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) در پاسخ، هشداری گزارش نمی‌دهد. هشدارهای پردازش را با استفاده از diagnostics بازیابی کنید.
validate_only	validate_only
operations	audience_members	فهرست اعضای مخاطب. برای جزئیات بیشتر به بخش فیلدهای اعضای مخاطب مراجعه کنید.
معادلی وجود ندارد	terms_of_service	الزامی. تنظیم کنید تا نشان دهد که کاربر شرایط خدمات Customer Match را پذیرفته یا رد کرده است.

فیلدهای مشتری و مخاطب

API گوگل ادز فقط از آپلود اعضای مخاطب به یک مخاطب در هر شغل پشتیبانی می‌کند. علاوه بر این، هدر درخواست developer-token مورد نیاز است و شما هدرهای درخواست login-customer-id و linked-customer-id را برای سناریوهای مختلف احراز هویت تنظیم می‌کنید.

رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) از ارسال اعضای مخاطب برای چندین مخاطب در یک درخواست واحد پشتیبانی می‌کند. رابط برنامه‌نویسی کاربردی مدیریت داده به توکن توسعه‌دهنده نیاز ندارد و شما می‌توانید اطلاعات ورود و مشتری مرتبط را با استفاده از فیلدهای یک Destination (Destination) به جای هدرهای درخواست، مشخص کنید. برای اطلاعات بیشتر در مورد مقصدها ، به پیکربندی مقصدها (Configure destinations) مراجعه کنید.

رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) از حذف همه اعضای یک مخاطب پشتیبانی نمی‌کند. در رابط برنامه‌نویسی کاربردی گوگل ادز (Google Ads API)، می‌توانید با تنظیم فیلد remove_all از تابع OfflineUserDataJobOperation به true ، همه اعضای یک مخاطب را حذف کنید.

در اینجا نحوه نگاشت فیلدهای API گوگل ادز برای یک مخاطب واحد به فیلدهای معادل در یک Destination آورده شده است:

رابط برنامه‌نویسی کاربردی گوگل ادز	Destination (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
customer_id درخواست	operating_account	مقدار account_id را روی شناسه مشتری مخاطب تنظیم کنید. account_type مربوط به operating_account را روی GOOGLE_ADS تنظیم کنید.
هدر درخواست developer-token	معادلی وجود ندارد	برای رابط برنامه‌نویسی کاربردی (API) مدیریت داده، نیازی به توکن توسعه‌دهنده نیست.
هدر درخواست login-customer-id	login_account	مقدار account_id روی شناسه مشتری حساب کاربری ورود به سیستم تنظیم کنید. اگر حساب کاربری ورود به سیستم یک حساب Google Ads است، account_type روی GOOGLE_ADS یا اگر حساب کاربری ورود به سیستم یک حساب همکاری داده است، DATA_PARTNER تنظیم کنید.
هدر درخواست linked-customer-id	linked_account	account_id برابر با شناسه مشتری حساب لینک‌شده قرار دهید. account_type برابر با DATA_PARTNER قرار دهید.
user_list از OfflineUserDataJob customer_match_user_list_metadata	product_destination_id	الزامی. روی شناسه عددی مخاطب تنظیم شود. از نام منبع UserList استفاده نکنید.
معادلی وجود ندارد	reference	یک شناسه تعریف شده توسط کاربر برای Destination . اگر در یک درخواست واحد، اعضای مخاطب را برای چندین مخاطب ارسال می‌کنید ، این فیلد را تنظیم کنید.

فیلدهای اعضای مخاطب

UserData (API تبلیغات گوگل)	AudienceMember (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
consent	consent	برای مشخص کردن رضایت برای مخاطب، تنظیم کنید. هر دو API از یک شیء Consent مشابه (ad_user_data، ad_personalization) استفاده می‌کنند. برای رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، می‌توانید با تنظیم فیلد consent در سطح درخواست، برای همه اعضای مخاطب در یک درخواست، رضایت تعیین کنید.
transaction_attribute	معادلی ندارد.	برای Customer Match قابل اجرا نیست.
user_attribute	معادلی ندارد.	برای Customer Match قابل اجرا نیست.
user_identifiers	mobile_id_data user_id_data user_identifiers	فیلدی را که مربوط به نوع داده‌ای است که برای اعضای مخاطب ارسال می‌کنید، پر کنید. برای جزئیات بیشتر به فیلدهای شناسه کاربر مراجعه کنید.

فیلدهای شناسه کاربر

در API گوگل ادز، چه اطلاعات تماس، شناسه موبایل یا شناسه کاربر را ارسال کنید، UserIdentifier استفاده می‌کنید. API مدیریت داده از رویکرد متفاوتی استفاده می‌کند و برای هر نوع داده، فیلدهای متفاوتی دارد.

در رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، فیلدی را که مربوط به نوع داده‌ای است که ارسال می‌کنید، پر کنید:

اطلاعات تماس

اگر از اطلاعات تماس مانند آدرس ایمیل، شماره تلفن یا اطلاعات آدرس استفاده می‌کنید، user_data روی UserData تنظیم کنید و برای هر مورد اطلاعات تماس، یک ورودی جداگانه در user_identifiers قرار دهید.

UserIdentifier (API تبلیغات گوگل)	UserIdentifier (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
address_info	address	برای جزئیات بیشتر به فیلدهای آدرس مراجعه کنید.
hashed_email	email_address	روی آدرس ایمیل قالب‌بندی و هش‌شده تنظیم کنید. همچنین می‌توانید آدرس ایمیل هش‌شده را رمزگذاری کنید .
hashed_phone_number	phone_number	روی شماره تلفن فرمت شده و هش شده تنظیم کنید. همچنین می‌توانید شماره تلفن هش شده را رمزگذاری کنید .
user_identifier_source	معادلی ندارد.

فیلدهای آدرس

در اینجا نگاشت‌های فیلد بین OfflineUserAddressInfo در API گوگل ادز و AddressInfo در API مدیریت داده آمده است. اگر از اطلاعات تماس برای پر کردن مخاطبان Customer Match خود استفاده می‌کنید، از این نگاشت‌ها استفاده کنید.

OfflineUserAddressInfo (API تبلیغات گوگل)	AddressInfo (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_data روی MobileData تنظیم کنید و برای هر شناسه، یک ورودی در mobile_ids قرار دهید.

UserIdentifier (API تبلیغات گوگل)	MobileData (رابط برنامه‌نویسی کاربردی مدیریت داده)	یادداشت‌ها
mobile_id	mobile_ids	روی فهرست شناسه‌های موبایل برای مخاطب تنظیم شود. در API گوگل ادز، برای هر شناسه موبایل مخاطب، یک UserIdentifier جداگانه با mobile_id اضافه می‌کنید. در API مدیریت داده، یک MobileData واحد با mobile_ids تنظیم شده روی لیست تمام شناسه‌های موبایل مخاطب اضافه کنید.
user_identifier_source	معادلی ندارد.

شناسه‌های کاربری

اگر از شناسه‌های کاربری استفاده می‌کنید، user_id_data روی UserIdData تنظیم کنید و user_id روی شناسه کاربری مخاطب تنظیم کنید.

UserIdentifier (API تبلیغات گوگل)	UserIdData (رابط برنامه‌نویسی مدیریت داده)	یادداشت‌ها
third_party_user_id	user_id	در API گوگل ادز، برای هر شناسه کاربریِ مخاطب، یک UserIdentifier جداگانه با third_party_user_id اضافه می‌کنید. در رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API)، فیلد user_id_data را روی یک UserIdData تنظیم کنید و فیلد user_id آن را روی شناسه کاربری مخاطب تنظیم کنید. نمی‌توانید چندین شناسه کاربری را برای یک مخاطب ارسال کنید.
user_identifier_source	معادلی ندارد.