همان‌طور که در راهنمای ساختار 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» می‌گوید کدام مشخصه‌ها را درطول عملیات به‌روزرسانی تغییر دهد. هر کتابخانه کارخواه شامل ابزار یا روش کمکی فیلد ماسک است که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 بیشتر بخوانید.