همان‌طور که در راهنمای ساختار API بحث شد، هر
منبع سطح بالا در Google Ads API دارای یک سرویس مختص نوع منبع متناظر است
که از اصلاح نمونه‌های منبع پشتیبانی می‌کند. همچنین می‌توانید از
GoogleAdsService.Mutate برای تغییر دادن
چند نوع منبع به‌صورت اتمی در یک درخواست استفاده کنید.
این راهنما از CampaignService برای
نمایش اصلاح اشیاء Campaign استفاده می‌کند، اما همین
مفاهیم برای همه سرویس‌های خاص نوع منبع دیگر نیز اعمال می‌شود.
درخواست‌های تغییر
هر سرویس مختص نوع منبع دارای یک روش تغییر است که درخواست تغییر را می‌پذیرد. این درخواست شامل موارد زیر است:
customer_id(یاcustomerIdدر نشانی‌های وب REST)- مجموعه‌ای از
operations - تنظیمات اجرای اختیاری مانند
partial_failure،validate_only، وresponse_content_type(که تعیین می‌کند آیا منبع قابل‌تغییر یا فقط نام منبع پس‌از تغییر برگردانده شود)
برای مثال، روش MutateCampaigns از CampaignService یک
MutateCampaignsRequest را می‌پذیرد که شامل موارد زیر است:
- یک
customer_id - مجموعه‌ای از
CampaignOperationشیء (operations) - تنظیمات اجرای اختیاری (
partial_failure،validate_only، وresponse_content_typeنشان‌دهنده نوع پاسخ ترجیحی)
عملیات
یک شیء عملیات مانند CampaignOperation به شما امکان می‌دهد با تنظیم فیلد operation، کنشی را که می‌خواهید روی یک منبع انجام دهید مشخص کنید.
این فیلد یک فیلد oneof است که شامل مشخصه‌های زیر است:
create- نمونه جدیدی از منبع ایجاد می‌کند.
update- منبع را به‌روز می‌کند تا با مشخصه‌های منبع
updateمطابقت داشته باشد. وقتی این فیلد تنظیم می‌شود، بایدupdate_maskعملیات را نیز تنظیم کنید که به Google Ads API می‌گوید کدام مشخصه‌ها را درطول عملیات به‌روزرسانی تغییر دهد. هر کتابخانه کارخواه شامل یک ابزار کمکی ماسک فیلد یا روش کمکی است کهupdate_maskرا برای شما تولید می‌کند. remove- منبع مشخص‌شده با رشته نام منبع را برمی‌دارد (برای مثال،
customers/1234567890/campaigns/987654321).
چون فیلد operation فیلد oneof است، نمی‌توانید از یک عملیات برای اصلاح چند شیء استفاده کنید. برای مثال، اگر می‌خواهید یک پویش ایجاد کنید و پویش دیگری را بردارید، دو نمونه از CampaignOperation را به درخواستتان اضافه کنید: یکی با تنظیم create و دیگری با تنظیم remove.
عملیات گروهی
اگرچه یک عملیات واحد فقط می‌تواند یک منبع واحد را ایجاد، به‌روزرسانی، یا حذف کند، یک درخواست تغییر واحد می‌تواند شامل چندین عملیات باشد. باید عملیات‌هایتان را در یک درخواست تغییر ترکیب کنید، به‌جای اینکه چند درخواست تغییر ارسال کنید که هرکدام حاوی یک عملیات باشد.
برای مثال، اگر می‌خواهید ده پویش ایجاد کنید، باید یک MutateCampaignsRequest تکی
ارسال کنید که ده شیء CampaignOperation داشته باشد. برای گروه‌بندی کردن
عملیات در انواع مختلف منابع در یک درخواست، از
GoogleAdsService.Mutate یا
منابع جهش‌یافته استفاده کنید.
پاسخ‌های جهش‌یافته
آنچه در پاسخ برگردانده می‌شود به آنچه در فیلد response_content_type درخواست تغییر ارسال شده است بستگی دارد.
برای مثال، اگر MUTABLE_RESOURCE مشخص شده باشد،
پاسخ حاوی هم resource_name منبع و هم فیلدهای تغییرپذیر پویش در campaign است. به‌طور
پیش‌فرض (RESOURCE_NAME_ONLY)، فقط resource_name در هر
MutateCampaignResult پر می‌شود.
خطاهای جهش
به‌طور پیش‌فرض (partial_failure = false)، عملیات در درخواست تغییر
فقط درصورتی در حساب Google Ads شما اعمال می‌شود که همه عملیات در درخواست
موفقیت‌آمیز باشد؛ اگر هر عملیاتی ناموفق باشد، کل درخواست برگردانده می‌شود. برای درخواست‌های تغییر که از شکست جزئی پشتیبانی می‌کنند (درخواست‌هایی که فیلد partial_failure در پیام درخواست دارند)، تنظیم partial_failure = true عملیات معتبر را ثبت می‌کند، درحالی‌که عملیات ناموفق خطاهای خاص عملیات را در فیلد partial_failure_error پاسخ برمی‌گرداند. برای جزئیات مربوط به رسیدگی به خطاها، راهنمای
شکست جزئی و راهنمای
خطاهای رایج را ببینید.
ردگیری تغییرات
برای ردیابی تغییرات ایجادشده در اشیاء در حساب Google Ads خود، یا برای بازیابی
وضعیت فعلی اشیاء، می‌توانید از منابع change_status و change_event
استفاده کنید.
change_statusخلاصه‌ای از منابعی را که در یک دوره زمانی مشخص تغییر کرده‌اند ارائه می‌دهد.change_eventسابقه دقیقی از تغییرات، ازجمله مقادیر قدیمی و جدید فیلدهای تغییریافته، ارائه می‌دهد.
برای پرسمان این منابع، از روش
GoogleAdsService.SearchStream یا
GoogleAdsService.Search استفاده کنید. درباره جاری‌سازی گزارش
بااستفاده از GoogleAdsService بیشتر بخوانید.