از نگاشتهای موجود در جداول برای نگاشت متدها و فیلدهای API گوگل ادز به معادل IngestEventsRequest آنها در API مدیریت داده استفاده کنید.
روشهای API
رابط برنامهنویسی کاربردی مدیریت داده (Data Manager API) به شما امکان میدهد هر دسته از رویدادهای فروش فروشگاه را در یک IngestEventsRequest واحد بارگذاری کنید.
در مقابل، API گوگل ادز به یک فرآیند سه مرحلهای با استفاده از OfflineUserDataJobService نیاز داشت:
- با استفاده از
CreateOfflineUserDataJobیک job ایجاد کنید - با استفاده از
AddOfflineUserDataJobOperationsعملیات را به job اضافه کنید - اجرای کار با استفاده از
RunOfflineUserDataJob
فیلدهای درخواست
هر IngestEventsRequest تابع محدودیتهای درخواست است. اگر تعداد عملیات در درخواست AddOfflineUserDataJobOperations شما از این محدودیتها بیشتر شود، باید آن را به چندین درخواست مصرف API Data Manager تقسیم کنید.
در اینجا نحوهی نگاشت فیلدهای درخواستهای API گوگل ادز به API مدیریت داده آمده است.
CreateOfflineUserDataJobRequest
جدول زیر نشان میدهد که چگونه فیلدهای CreateOfflineUserDataJobRequest به IngestEventsRequest نگاشت میشوند.
درخواست شغل ( CreateOfflineUserDataJobRequest ) (API تبلیغات گوگل) | IngestEventsRequest (رابط برنامهنویسی کاربردی مدیریت داده) | یادداشتها |
|---|---|---|
customer_id | destinations.operating_account | به فیلدهای مشتری و عملیات تبدیل مراجعه کنید. |
| destinations | به فیلدهای مشتری و عملیات تبدیل مراجعه کنید. |
| تشخیص | از 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 |
| به فیلد variable یک CustomVariable در سطح رویداد یا یک ItemCustomVariable در سطح آیتم نگاشت کنید. |
enable_match_rate_range_preview | معادلی وجود ندارد | |
validate_only | validate_only | |
| معادلی وجود ندارد | consent | API گوگل ادز فقط از تعیین consent در سطح رویداد در UserData پشتیبانی میکند. برای API مدیریت داده، میتوانید با تنظیم فیلد consent در IngestEventsRequest ، برای همه رویدادها در یک درخواست، رضایت تعیین کنید. میتوانید با تنظیم فیلد consent در Event ، این مقدار را برای یک رویداد خاص لغو کنید. |
| معادلی وجود ندارد | encoding | برای آپلودهای UserData الزامی است. روی Encoding مورد استفاده برای مقادیر UserIdentifier تنظیم کنید. |
| معادلی وجود ندارد | encryption_info | تنظیم کنید که آیا درخواست شامل شناسههای کاربری رمزگذاریشدهی UserData است یا خیر. برای جزئیات بیشتر به بخش رمزگذاری مراجعه کنید. |
AddOfflineUserDataJobOperationsRequest
جدول زیر نشان میدهد که چگونه فیلدهای AddOfflineUserDataJobOperationsRequest به IngestEventsRequest نگاشت میشوند.
درخواست عملیات شغلی ( AddOfflineUserDataJobOperationsRequest ) (رابط برنامهنویسی کاربردی تبلیغات گوگل) | IngestEventsRequest (رابط برنامهنویسی کاربردی مدیریت داده) | یادداشتها |
|---|---|---|
| destinations | به فیلدهای مشتری و عملیات تبدیل مراجعه کنید. |
resource_name | معادلی وجود ندارد | رابط برنامهنویسی کاربردی (API) مدیریت داده نیازی به بهروزرسانی منبع کار ندارد. |
enable_partial_failure | معادلی وجود ندارد | اگر IngestEventsRequest با موفقیت انجام شود ، هرگونه خرابی که در طول پردازش پاییندستی رخ دهد، در سطح رویداد مدیریت میشود که میتواند منجر به موفقیت جزئی شود. از Diagnostics برای بازیابی وضعیت آپلود خود و همچنین خطاها و هشدارها برای رویدادهای جداگانه استفاده کنید. اگر IngestEventsRequest با شکست مواجه شود (برای مثال، به دلیل BadRequest )، هیچ رویدادی پردازش نمیشود و شما باید خطا را برطرف کرده و درخواست را دوباره امتحان کنید. برای اطلاعات بیشتر به بخش «درک خطاهای API» مراجعه کنید. |
enable_warnings | معادلی وجود ندارد | برای دریافت هشدارهای مربوط به درخواست API مدیریت داده خود، از Diagnostics استفاده کنید. نیازی به فعال کردن این گزینه نیست. |
operations | events | عملیات OfflineUserDataJobOperation.create معادل ارسال یک IngestEventsRequest است. رابط برنامهنویسی کاربردی مدیریت داده از حذف رویدادها پشتیبانی نمیکند. |
validate_only | validate_only | |
| معادلی وجود ندارد | consent | API گوگل ادز فقط از تعیین consent در سطح رویداد در UserData پشتیبانی میکند. برای API مدیریت داده، میتوانید با تنظیم فیلد consent در IngestEventsRequest ، برای همه رویدادها در یک درخواست، رضایت تعیین کنید. میتوانید با تنظیم فیلد consent در Event ، این مقدار را برای یک رویداد خاص لغو کنید. |
| معادلی وجود ندارد | encoding | برای آپلودهای UserData الزامی است. روی Encoding مورد استفاده برای مقادیر UserIdentifier تنظیم کنید. |
| معادلی وجود ندارد | encryption_info | تنظیم کنید که آیا درخواست شامل شناسههای کاربری رمزگذاریشدهی UserData است یا خیر. برای جزئیات بیشتر به بخش رمزگذاری مراجعه کنید. |
فیلدهای مشتری و عملیات تبدیل
API گوگل ادز به هدر درخواست developer-token نیاز دارد و شما هدرهای درخواست login-customer-id و linked-customer-id را برای سناریوهای مختلف احراز هویت تنظیم میکنید.
رابط برنامهنویسی کاربردی مدیریت داده (Data Manager API) به توکن توسعهدهنده نیاز ندارد و شما میتوانید اطلاعات ورود و اطلاعات مشتری مرتبط را با استفاده از فیلدهای یک Destination به جای هدرهای درخواست، مشخص کنید. برای اطلاعات بیشتر در مورد مقصدها ، به Configure destinations مراجعه کنید.
| رابط برنامهنویسی کاربردی گوگل ادز | 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 | اگر با استفاده از لینک partner به operating_account دسترسی دارید، account_id برابر با شناسه مشتری حساب لینکشده و account_type برابر با DATA_PARTNER قرار دهید. در غیر این صورت، فیلد linked_account تنظیم نکنید. |
conversion_action | product_destination_id | روی شناسه عددی عمل تبدیل تنظیم کنید. از نام منبع استفاده نکنید. |
فیلدهای رویداد
جدول زیر نشان میدهد که چگونه فیلدهای تبدیل فروش یک فروشگاه بین دو API نگاشت میشوند.
برخلاف API گوگل ادز که با استفاده از ItemAttribute فقط از گنجاندن یک آیتم در هر تراکنش پشتیبانی میکند، API مدیریت داده از گنجاندن چندین آیتم در هر رویداد در CartData پشتیبانی میکند.
OfflineUserDataJobOperation.create (رابط برنامهنویسی کاربردی تبلیغات گوگل) | Event (رابط برنامهنویسی کاربردی مدیریت داده) | یادداشتها |
|---|---|---|
| معادلی وجود ندارد | event_source | الزامی است. برای تبدیل فروش فروشگاه، IN_STORE را تنظیم کنید. |
transaction_attribute.conversion_action | destinations.product_destination_id | به فیلدهای مشتری و عملیات تبدیل مراجعه کنید. به جای نام منبع، از شناسه عددی عملیات تبدیل استفاده کنید. |
transaction_attribute.transaction_date_time | event_timestamp |
برای جزئیات بیشتر به قالب مهر زمانی مراجعه کنید. |
transaction_attribute.transaction_amount_micros |
| روی مقدار ارز تنظیم کنید، نه مقدار بر حسب میکرو. برای مثال، برای مقدار تبدیل ۵.۲۳ دلار، از مقدار 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 |
| به فیلد 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 تنظیم کنید، برای همه اقلام به عنوان پیشفرض عمل میکند، اما میتوانید آن را برای اقلام خاص لغو کنید. |
transaction_attribute.item_attribute.country_code |
| اگر cart_data.merchant_feed_label تنظیم کنید، به عنوان پیشفرض برای همه اقلام عمل میکند، اما میتوانید آن را برای اقلام خاص لغو کنید. |
transaction_attribute.item_attribute.language_code |
| اگر cart_data.merchant_feed_language_code تنظیم کنید، به عنوان پیشفرض برای همه اقلام عمل میکند، اما میتوانید آن را برای اقلام خاص لغو کنید. |
transaction_attribute.item_attribute.quantity | cart_data.items[].quantity | |
| معادلی وجود ندارد | cart_data.items[].unit_price | قیمت واحد این کالا را بدون احتساب مالیات، هزینه ارسال و تخفیفهای مربوط به رویداد (در سطح تراکنش) تنظیم کنید. |
user_identifiers |
| الزامی است . |
consent | consent | هر دو API از یک شیء Consent مشابه ( ad_user_data ، ad_personalization ) استفاده میکنند. برای API مدیریت داده، میتوانید با تنظیم فیلد consent در IngestEventsRequest ، برای همه رویدادها در یک درخواست، رضایتنامه تنظیم کنید. |
فیلدهای شناسه کاربر
UserIdentifier (API تبلیغات گوگل) | UserIdentifier (رابط برنامهنویسی کاربردی مدیریت داده) | یادداشتها |
|---|---|---|
user_identifier_source | منبع تعیین میکند که کدام فیلد در
| |
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 | معادلی وجود ندارد | در نسخه فعلی رابط برنامهنویسی کاربردی مدیریت داده پشتیبانی نمیشود. |
address_info.state | معادلی وجود ندارد | در نسخه فعلی رابط برنامهنویسی کاربردی مدیریت داده پشتیبانی نمیشود. |
address_info.hashed_street_address | معادلی وجود ندارد | در نسخه فعلی رابط برنامهنویسی کاربردی مدیریت داده پشتیبانی نمیشود. |