نگاشت‌های فیلد

از نگاشت‌های موجود در جدول‌ها برای نگاشت روش‌ها و فیلدهای Google Ads API به معادل IngestEventsRequest آن‌ها در Data Manager API استفاده کنید.

اصالت‌سنجی

‫Data Manager API به اعتبارنامه‌هایی با دامنه‌ای متفاوت از Google Ads API نیاز دارد. مراحل مندرج در راه‌اندازی دسترسی به API را دنبال کنید تا اطلاعات اعتباری جدیدی که شامل حوزه «میانای برنامه‌سازی کاربردی مدیر داده‌ها» است تولید کنید.

روش‌های میانای برنامه‌سازی کاربردی

«میانای برنامه‌سازی کاربردی مدیر داده‌ها» به شما امکان می‌دهد هر دسته از رویدادهای فروشگاه را در یک IngestEventsRequest بارگذاری کنید.

درمقابل، Google Ads API به فرایندی سه‌مرحله‌ای بااستفاده از OfflineUserDataJobService نیاز داشت:

1. ایجاد شغل بااستفاده از CreateOfflineUserDataJob
2. بااستفاده از AddOfflineUserDataJobOperations، عملیات را به کار اضافه کنید
3. اجرای کار بااستفاده از RunOfflineUserDataJob

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

هر IngestEventsRequest مشمول محدودیت‌های درخواست است. اگر تعداد عملیات در درخواست AddOfflineUserDataJobOperations شما از این محدودیت‌ها فراتر رود، باید آن را به چندین درخواست انتقال داده «میانای برنامه‌سازی کاربردی مدیر داده» تقسیم کنید.

در اینجا نحوه نگاشت فیلدهای درخواست‌های Google Ads API به Data Manager API آمده است.

CreateOfflineUserDataJobRequest

جدول زیر نشان می‌دهد که چگونه فیلدهای CreateOfflineUserDataJobRequest به IngestEventsRequest نگاشت می‌شوند.

CreateOfflineUserDataJobRequest (Google Ads API)	IngestEventsRequest (Data Manager API)	یادداشت‌ها
customer_id	destinations.operating_account	فیلدهای کنش تبدیل و مشتری را ببینید.
سرایند درخواست developer-token سرایند درخواست login-customer_id سرایند درخواست linked-customer-id	destinations	فیلدهای کنش تبدیل و مشتری را ببینید.
job.status job.failure_reason	تشخیص خرابی	از request_id برگشتی در IngestEventsResponse برای بازیابی تشخیص خرابی درباره بارگذاری تبدیل استفاده کنید.
job.id	request_id	از request_id برگشتی در IngestEventsResponse برای بازیابی تشخیص خرابی درباره بارگذاری تبدیل استفاده کنید.
job.external_id	معادل ندارد
job.type	معادل ندارد
job.store_sales_metadata.third_party_metadata.partner_id	destinations.login_account	شریک داده‌ای که تبدیل‌های فروش فروشگاهی را بارگذاری می‌کند با login_account مقصد شناسایی می‌شود. برای جزئیات بیشتر، پیکربندی مقصدها را ببینید.
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time	معادل ندارد
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction	معادل ندارد
job.store_sales_metadata.third_party_metadata.partner_match_fraction	معادل ندارد
job.store_sales_metadata.third_party_metadata.partner_upload_fraction	معادل ندارد
job.store_sales_metadata.third_party_metadata.bridge_map_version_id	معادل ندارد
job.store_sales_metadata.loyalty_fraction	معادل ندارد
job.store_sales_metadata.transaction_upload_fraction	معادل ندارد
job.store_sales_metadata.custom_key	events[].custom_variables[].variable events[].cart_data.items[].custom_variables[].variable	به فیلد variable در CustomVariable در سطح رویداد یا ItemCustomVariable در سطح مورد نگاشت کنید.
enable_match_rate_range_preview	معادل ندارد
validate_only	validate_only
معادل ندارد	consent	‫Google Ads API فقط از مشخص کردن consent در سطح رویداد در UserData پشتیبانی می‌کند. برای Data Manager API، می‌توانید با تنظیم کردن فیلد consent در IngestEventsRequest، موافقت را برای همه رویدادها در یک درخواست مشخص کنید. با تنظیم فیلد consent در Event می‌توانید این مقدار را برای رویداد تکی ملغی کنید.
معادل ندارد	encoding	برای بارگذاری‌های UserData الزامی است. روی Encoding استفاده‌شده برای مقادیر UserIdentifier تنظیم کنید.
معادل ندارد	encryption_info	تنظیم کنید که آیا درخواست حاوی شناسه‌های کاربر رمزگذاری‌شده UserData است یا نه. برای جزئیات، رمزگذاری را ببینید.

AddOfflineUserDataJobOperationsRequest

جدول زیر نشان می‌دهد که چگونه فیلدهای AddOfflineUserDataJobOperationsRequest به IngestEventsRequest نگاشت می‌شوند.

AddOfflineUserDataJobOperationsRequest (Google Ads API)	IngestEventsRequest (Data Manager API)	یادداشت‌ها
سرایند درخواست developer-token سرایند درخواست login-customer_id سرایند درخواست linked-customer-id	destinations	فیلدهای کنش تبدیل و مشتری را ببینید.
resource_name	معادل ندارد	«میانای برنامه‌سازی کاربردی مدیر داده» نیازی به به‌روزرسانی منبع شغل ندارد.
enable_partial_failure	معادل ندارد	اگر IngestEventsRequest موفق شود، هرگونه خطا که درطول پردازش پایین‌دست رخ دهد در سطح رویداد مدیریت می‌شود که می‌تواند منجر به موفقیت جزئی شود. از تشخیص خرابی برای بازیابی وضعیت بارگذاری و همچنین خطاها و هشدارهای مربوط به رویدادهای فردی استفاده کنید. اگر IngestEventsRequest ناموفق باشد (برای مثال، به‌دلیل BadRequest)، هیچ رویدادی پردازش نمی‌شود و باید خطا را برطرف کنید و درخواست را دوباره امتحان کنید. برای اطلاعات بیشتر، درک خطاهای API را ببینید.
enable_warnings	معادل ندارد	از تشخیص خرابی برای بازیابی هشدارهای مربوط به درخواست Data Manager API استفاده کنید. لازم نیست این را فعال کنید.
operations	events	عملکرد OfflineUserDataJobOperation.create معادل ارسال IngestEventsRequest است. «میانای برنامه‌سازی کاربردی مدیر داده» از برداشتن رویدادها پشتیبانی نمی‌کند.
validate_only	validate_only
معادل ندارد	consent	‫Google Ads API فقط از مشخص کردن consent در سطح رویداد در UserData پشتیبانی می‌کند. برای Data Manager API، می‌توانید با تنظیم کردن فیلد consent در IngestEventsRequest، موافقت را برای همه رویدادها در یک درخواست مشخص کنید. با تنظیم فیلد consent در Event می‌توانید این مقدار را برای رویداد تکی ملغی کنید.
معادل ندارد	encoding	برای بارگذاری‌های UserData الزامی است. روی Encoding استفاده‌شده برای مقادیر UserIdentifier تنظیم کنید.
معادل ندارد	encryption_info	تنظیم کنید که آیا درخواست حاوی شناسه‌های کاربر رمزگذاری‌شده UserData است یا نه. برای جزئیات، رمزگذاری را ببینید.

فیلدهای کنش تبدیل و مشتری

«میانای برنامه‌سازی کاربردی Google Ads» به سرایند درخواست developer-token نیاز دارد و شما login-customer-id و linked-customer-id سرایندهای درخواست را برای سناریوهای اصالت‌سنجی مختلف تنظیم می‌کنید.

‫Data Manager API به کد توسعه‌دهنده نیاز ندارد و اطلاعات ورود به سیستم و مشتری پیوندی را بااستفاده از فیلدهای Destination به‌جای سرایندهای درخواست مشخص می‌کنید. برای اطلاعات بیشتر درباره مقصدها، پیکربندی مقصدها را بررسی کنید.

Google Ads API	Destination (Data Manager API)	یادداشت‌ها
‫customer_id درخواست	operating_account	account_id را روی شناسه مشتری حساب تبدیل Google Ads تنظیم کنید. ‫account_type operating_account را روی GOOGLE_ADS تنظیم کن.
سرایند درخواست developer-token	معادل ندارد	برای «میانای برنامه‌سازی کاربردی مدیر داده»، کد توسعه‌دهنده لازم نیست.
سرایند درخواست login-customer-id	login_account	‫account_id را روی شناسه مشتری حساب ورود به سیستم تنظیم کنید. اگر حساب ورود به سیستم حساب Google Ads است، account_type را روی GOOGLE_ADS تنظیم کنید، یا اگر حساب ورود به سیستم حساب شریک داده است، DATA_PARTNER را تنظیم کنید.
سرایند درخواست linked-customer-id	linked_account	اگر بااستفاده از پیوند شریک به operating_account دسترسی پیدا می‌کنید، account_id را روی شناسه مشتری حساب پیوندشده تنظیم کنید و account_type را روی DATA_PARTNER تنظیم کنید. درغیراین‌صورت، فیلد linked_account را تنظیم نکنید.
conversion_action	product_destination_id	روی شناسه عددی کنش تبدیل تنظیم کنید. از نام منبع استفاده نکنید.

فیلدهای رویداد

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

برخلاف Google Ads API که از افزودن تنها یک مورد در هر تراکنش بااستفاده از ItemAttribute پشتیبانی می‌کند، Data Manager API از افزودن چندین مورد در هر رویداد در CartData پشتیبانی می‌کند.

OfflineUserDataJobOperation.create (Google Ads API)	Event (Data Manager API)	یادداشت‌ها
معادل ندارد	event_source	الزامی برای تبدیل‌های فروش فروشگاهی روی IN_STORE تنظیم شود.
transaction_attribute.conversion_action	destinations.product_destination_id	فیلدهای کنش تبدیل و مشتری را ببینید. به‌جای نام منبع، از شناسه عددی کنش تبدیل استفاده کنید.
transaction_attribute.transaction_date_time	event_timestamp	اگر از قالب JSON استفاده می‌کنید، آن را روی مقداری در قالب RFC 3339 تنظیم کنید که کمی با قالب تاریخ و زمان Google Ads API متفاوت است. اگر از بافرهای پروتکل استفاده می‌کنید، از Timestamp استفاده کنید و seconds و (درصورت تمایل) فیلدهای nanoseconds را تنظیم کنید. برای جزئیات بیشتر، قالب مُهر زمان را ببینید.
transaction_attribute.transaction_amount_micros	conversion_value (الزامی) cart_data.items[].conversion_value	روی مقدار واحد پول تنظیم کنید، نه مقدار در میکرو. برای مثال، برای مقدار تبدیل ۵٫۲۳ دلار، از مقدار 5.23 استفاده کنید.
transaction_attribute.currency_code	currency	الزامی.
transaction_attribute.order_id	transaction_id	الزامی.
transaction_attribute.store_attribute.store_code	event_location.store_id	الزامی کد فروشگاه را در فیلد store_id در شیء EventLocation تنظیم کنید.
transaction_attribute.custom_value	custom_variables[].value cart_data.items[].custom_variables[].value	به فیلد value در CustomVariable در سطح رویداد یا ItemCustomVariable در سطح مورد نگاشت کنید.
transaction_attribute.item_attribute.item_id	cart_data.items[].merchant_product_id
transaction_attribute.item_attribute.merchant_id	cart_data.merchant_id cart_data.items[].merchant_id	اگر cart_data.merchant_id را تنظیم کنید، به‌عنوان پیش‌فرض برای همه موارد عمل می‌کند، اما می‌توانید آن را برای موارد جداگانه ملغی کنید.
transaction_attribute.item_attribute.country_code	cart_data.merchant_feed_label cart_data.items[].merchant_feed_label	اگر cart_data.merchant_feed_label را تنظیم کنید، به‌عنوان پیش‌فرض برای همه موارد عمل می‌کند، اما می‌توانید آن را برای موارد جداگانه ملغی کنید.
transaction_attribute.item_attribute.language_code	cart_data.merchant_feed_language_code cart_data.items[].merchant_feed_language_code	اگر cart_data.merchant_feed_language_code را تنظیم کنید، به‌عنوان پیش‌فرض برای همه موارد عمل می‌کند، اما می‌توانید آن را برای موارد جداگانه ملغی کنید.
transaction_attribute.item_attribute.quantity	cart_data.items[].quantity
معادل ندارد	cart_data.items[].unit_price	روی قیمت واحد بدون احتساب مالیات، ارسال، و تخفیف‌های محدوده رویداد (سطح تراکنش) برای این مورد تنظیم شده است.
user_identifiers	user_data.user_identifiers third_party_user_data.user_identifiers	الزامی. third_party_user_dataاز همان ساختار user_data استفاده می‌کند، اما نشان می‌دهد که شناسه‌های کاربر از منبع طرف سوم می‌آیند نه داده‌های تبلیغ‌کننده طرف اول. پر کردن third_party_user_data فقط درصورتی مجاز است که حساب ورود به سیستم شریک داده باشد (login_account.account_type DATA_PARTNER). برای جزئیات، فیلدهای شناسه کاربر را ببینید.
consent	consent	هر دو API از شیء Consent مشابهی (ad_user_data، ad_personalization) استفاده می‌کنند. برای Data Manager API، می‌توانید با تنظیم فیلد consent در IngestEventsRequest، موافقت را برای همه رویدادهای درخواست نیز تنظیم کنید.

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

UserIdentifier (Google Ads API)	UserIdentifier (Data Manager API)	یادداشت‌ها
user_identifier_source	منبع تعیین می‌کند کدام فیلد در Data Manager API Event تکمیل شود: user_data third_party_user_data	از همان ساختار third_party_user_data user_data استفاده می‌کند، اما نشان می‌دهد که شناسه‌های کاربر از منبع طرف سوم می‌آیند نه از داده‌های تبلیغ‌کننده طرف اول. پر کردن third_party_user_data فقط درصورتی مجاز است که حساب ورود به سیستم شریک داده باشد (login_account.account_type DATA_PARTNER). برای جزئیات، فیلدهای شناسه کاربر را ببینید.
hashed_email	email_address	روی نشانی ایمیل قالب‌بندی‌شده و درهم‌سازی‌شده تنظیم کنید. همچنین می‌توانید نشانی ایمیل درهم‌سازی‌شده را رمزگذاری کنید.
hashed_phone_number	phone_number	روی شماره تلفن قالب‌بندی‌شده و درهم‌سازی‌شده تنظیم کنید. همچنین می‌توانید شماره تلفن درهم‌سازی‌شده را رمزگذاری کنید.
address_info	address	روی شیء AddressInfo تنظیم کنید. دستورالعمل‌های قالب‌بندی و درهم‌سازی را دنبال کنید. همچنین می‌توانید مشخصه‌های درهم‌سازی‌شده نشانی را رمزگذاری کنید.
address_info.hashed_first_name	address.given_name
address_info.hashed_last_name	address.family_name
address_info.country_code	address.region_code
address_info.postal_code	address.postal_code
address_info.city	معادل ندارد	برای مقصدهای Google Ads پشتیبانی نمی‌شود.
address_info.state	معادل ندارد	برای مقصدهای Google Ads پشتیبانی نمی‌شود.
address_info.hashed_street_address	معادل ندارد	برای مقصدهای Google Ads پشتیبانی نمی‌شود.