این راهنما مؤلفه‌های اصلی تشکیل‌دهنده Google Ads API را معرفی می‌کند. Google Ads API از منابع و سرویس‌ها تشکیل شده است. منبع نشان‌دهنده یک نهاد Google Ads است، درحالی‌که سرویس‌ها نهادهای Google Ads را بازیابی و دستکاری می‌کنند.
سلسله مراتب شیء
حساب Google Ads را می‌توان به‌عنوان سلسله‌مراتبی از اشیا مشاهده کرد.
منبع سطح بالای حساب مشتری است.
هر مشتری یک یا چند پویش فعال دارد.
هر پویش شامل یک یا چند گروه آگهی است که برای گروه‌بندی آگهی‌هایتان در مجموعه‌های منطقی استفاده می‌شود.
آگهی گروه آگهی نشان‌دهنده آگهی‌ای است که در گروه آگهی اجرا می‌کنید. به‌جز «پویش‌های برنامه» که فقط می‌توانند یک آگهی گروه آگهی در هر گروه آگهی داشته باشند، هر گروه آگهی شامل یک یا چند آگهی گروه آگهی است.
پویش‌های «عملکرد بیشینه» از ساختار متفاوتی نسبت‌به انواع دیگر پویش استفاده می‌کنند: به‌جای گروه‌های آگهی و آگهی‌های گروه آگهی، پویش «عملکرد بیشینه» حاوی گروه‌های دارایی است. بااستفاده از AssetGroupAsset، دارایی‌های خلاقانه را به گروه دارایی پیوند می‌دهید و بااستفاده از AssetGroupSignal، سیگنال‌های مخاطب یا موضوع جستجو را پیوست می‌کنید.
می‌توانید یک یا چند AdGroupCriterion
یا CampaignCriterion منبع را به گروه آگهی یا پویش پیوست کنید. این‌ها معیارهایی را نشان می‌دهند که نحوه راه‌اندازی آگهی‌ها را تعریف می‌کنند.
انواع معیار زیادی وجود دارد،
مثل کلیدواژه‌ها، محدوده‌های سنی، و مکان‌ها. معیارهای تعریف‌شده در سطح پویش بر همه منابع دیگر در پویش تأثیر می‌گذارد. همچنین می‌توانید
بودجه و تاریخ و زمان شروع و پایان را برای پویش‌ها یا
آگهی‌های تکی بااستفاده از AdGroupAd.start_date_time و AdGroupAd.end_date_time مشخص کنید.
درنهایت، می‌توانید دارایی‌ها را در سطح حساب، پویش، گروه آگهی، یا گروه دارایی پیوست کنید. دارایی‌ها به شما امکان می‌دهند اطلاعات اضافی به آگهی‌هایتان اضافه کنید، مثل شماره تلفن، نشانی خیابان، یا تبلیغات ویژه. دارایی‌ها نمای کلی را ببینید.
منابع
منابع نشان‌دهنده نهادهای موجود در حساب Google Ads شما هستند.
Campaign و AdGroup دو نمونه از منابع هستند.
شناسه‌های شیء
هر شیء در Google Ads با شناسه خودش شناسایی می‌شود. برخی‌از این شناسه‌ها در سراسر همه حساب‌های Google Ads منحصربه‌فرد هستند، درحالی‌که برخی دیگر فقط در یک محدوده محدود منحصربه‌فرد هستند.
| شناسه شیء | حوزه تکینگی | در سطح جهانی منحصربه‌فرد است؟ |
|---|---|---|
| شناسه بودجه | جهانی | بله |
| شناسه کمپین | جهانی | بله |
| شناسه گروه آگهی | جهانی | بله |
| شناسه آگهی | گروه آگهی | نه، اما جفت (AdGroupId، AdId) در سطح جهانی منحصربه‌فرد است. هم‌رسانی AdId در چندین گروه آگهی ممنوع است. |
| شناسه AdGroupCriterion | گروه آگهی | نه، اما جفت (AdGroupId، CriterionId) در سطح جهانی منحصربه‌فرد است |
| شناسه CampaignCriterion | پویش | نه، اما جفت (CampaignId، CriterionId) در سطح جهانی یکتا است |
| شناسه برچسب | مشتری | نه، اما جفت (CustomerId، LabelId) در سطح جهانی منحصربه‌فرد است |
| شناسه فهرست کاربر | جهانی | بله |
| شناسه دارایی | جهانی | بله |
این قوانین شناسه می‌تواند هنگام طراحی فضای ذخیره‌سازی محلی برای اشیاء Google Ads شما مفید باشد.
برخی‌از اشیاء را می‌توان برای چند نوع نهاد استفاده کرد. در چنین مواردی، شیء
حاوی فیلد type است که محتوای آن را توصیف می‌کند. برای مثال،
AdGroupAd می‌تواند به شیئی مثل
آگهی واکنش‌گرای جستجو، آگهی هتل، یا آگهی «تولید تقاضا» اشاره کند. این مقدار ازطریق فیلد AdGroupAd.ad.type قابل دسترسی است و مقداری را در شمارش AdType برمی‌گرداند. توجه داشته باشید که
تغییرپذیری می‌تواند براساس نسخه متفاوت باشد (برای مثال، VideoResponsiveAdInfo در Ad
در نسخه ۲۴ و جدیدتر تغییرپذیر است).
نام منابع
هر منبع به‌طور منحصربه‌فرد با رشته resource_name شناسایی می‌شود که
منبع و والدین آن را در یک مسیر به‌هم متصل می‌کند. برای مثال، نام‌های منبع پویش
به این شکل است:
customers/customer_id/campaigns/campaign_id
بنابراین برای کمپینی با شناسه 987654 در حساب Google Ads با شناسه مشتری
1234567، resource_name به‌صورت زیر خواهد بود:
customers/1234567/campaigns/987654
خدمات
سرویس‌ها به شما امکان می‌دهند نهادهای Google Ads خود را بازیابی و اصلاح کنید. سه نوع سرویس وجود دارد: سرویس‌های اصلاح، بازیابی شیء و آمار، و بازیابی فراداده.
تغییر دادن (جهش دادن) هدف‌ها
سرویس‌های مختص منبع، نمونه‌های نوع منبع مرتبط را بااستفاده از
درخواست mutate اصلاح می‌کنند. همچنین می‌توانید از
GoogleAdsService.Mutate برای انجام تغییرات اتمی
در چندین نوع منبع در یک درخواست واحد استفاده کنید (مانند ایجاد
بودجه پویش، پویش، و گروه آگهی باهم).
نمونه‌هایی از سرویس‌های مختص منابع:
CustomerServiceبرای اصلاح مشتریان.CampaignServiceبرای اصلاح پویش‌ها.AdGroupServiceبرای اصلاح گروه‌های آگهی.
هر درخواست mutate باید شامل اشیای operation مربوطه باشد. برای
مثال، روش CampaignService.MutateCampaigns یک یا چند نمونه از CampaignOperation را انتظار دارد. برای بحث مفصل درباره عملیات،
تغییر دادن اشیا را ببینید.
تغییرات هم‌زمان
بیش‌از یک منبع نمی‌تواند به‌طور هم‌زمان شیء Google Ads را تغییر دهد. اگر چند کاربر داشته باشید که شیء یکسانی را با برنامه‌تان به‌روزرسانی می‌کنند، یا اگر اشیاء Google Ads را به‌طور موازی بااستفاده از چند رشته تغییر می‌دهید، این امر می‌تواند باعث بروز خطا شود. این شامل به‌روزرسانی شیء از چندین رشته در یک برنامه، یا از برنامه‌های مختلف (برای مثال، برنامه شما و یک جلسه هم‌زمان رابط کاربری Google Ads) می‌شود.
«میانای برنامه‌سازی کاربردی» روشی برای قفل کردن شیء قبل‌از به‌روزرسانی ارائه نمی‌دهد؛ اگر دو منبع
تلاش کنند شیئی را به‌طور هم‌زمان تغییر دهند، «میانای برنامه‌سازی کاربردی»
DatabaseError.CONCURRENT_MODIFICATION_ERROR را افزایش می‌دهد.
جهش‌های ناهمگام درمقابل همگام
روش‌های تغییر Google Ads API همگام هستند. فراخوانی‌های API فقط پس‌از تغییر اشیاء پاسخ برمی‌گردانند، بنابراین باید برای هر درخواست منتظر پاسخ بمانید. اگرچه کدنویسی این رویکرد نسبتاً ساده است، اما اگر فرایندها مجبور شوند منتظر تکمیل تماس‌ها بمانند، می‌تواند بر توازن بار تأثیر منفی بگذارد و منابع را هدر دهد.
رویکرد جایگزین این است که اشیاء را به‌طور ناهمگام بااستفاده از
BatchJobService جهش دهید، که دسته‌هایی از
عملیات را در چندین سرویس بدون انتظار برای تکمیل آن‌ها انجام می‌دهد. پس‌از ارسال کار دسته‌ای، سرورهای Google Ads API عملیات را به‌صورت ناهمزمان اجرا می‌کنند و فرایندها را برای انجام عملیات دیگر آزاد می‌کنند. می‌توانید به‌طور دوره‌ای وضعیت کار را برای تکمیل بررسی کنید.
برای اطلاعات بیشتر درباره پردازش ناهمزمان، راهنمای پردازش دسته‌ای را ببینید.
اعتبارسنجی جهش
بیشتر درخواست‌های تغییر را می‌توان بدون اجرای واقعی تماس دربرابر داده‌های واقعی اعتبارسنجی کرد. می‌توانید درخواست را برای پارامترهای مفقود و مقادیر فیلد نادرست بدون اجرای واقعی عملیات آزمایش کنید.
برای استفاده از این ویژگی، فیلد بولی اختیاری validate_only درخواست را روی
true تنظیم کنید. درخواست به‌طور کامل اعتبارسنجی می‌شود، انگار که قرار است اجرا شود، اما
اجرای نهایی رد می‌شود. اگر خطایی پیدا نشود، پاسخ بدون نتایج جهش‌یافته برگردانده می‌شود (results خالی است). اگر اعتبارسنجی ناموفق باشد، درخواست به‌طور پیش‌فرض با خطای GoogleAdsFailure RPC (partial_failure = false) ناموفق می‌شود، یا وقتی partial_failure = true، پاسخ عادی با خطاهای مختص عملیات در partial_failure_error برمی‌گرداند.
validate_only به‌ویژه در آزمایش آگهی‌ها برای نقض‌های خط‌مشی رایج مفید است. اگر آگهی‌ها خط‌مشی‌هایی مثل
داشتن کلمات خاص، نشانه‌های سجاوندی، حروف بزرگ، یا طول را نقض کنند، به‌طور خودکار رد می‌شوند. یک آگهی بد می‌تواند باعث شود کل گروه رد شود. آزمایش آگهی جدید در validate_only
درخواست می‌تواند چنین نقض‌هایی را آشکار کند. برای دیدن این مورد در عمل، به نمونه کد مربوط به رسیدگی به خطاهای نقض خط‌مشی مراجعه کنید.
دریافت اشیا و آمار عملکرد
GoogleAdsService تنها سرویس یکپارچه برای بازیابی اشیاء و آمار عملکرد است.
همه درخواست‌های Search و
SearchStream برای
GoogleAdsService به پرسمانی نیاز دارند که
منبع موردنظر برای پُرسمان، مشخصه‌های منبع، و سنجه‌های عملکرد
برای بازیابی، گزاره‌های موردنظر برای فیلتر کردن درخواست، و بخش‌های
موردنظر برای تجزیه بیشتر آمار عملکرد را مشخص کند. برای اطلاعات بیشتر درباره
قالب پُرسمان، راهنمای زبان پُرسمان Google Ads را ببینید.
بازیابی فراداده
GoogleAdsFieldService فراداده‌های مربوط به منابع را در Google Ads API بازیابی می‌کند، مانند مشخصه‌های دردسترس برای یک منبع و نوع داده آن. برای جزئیات مربوط به پُرسمان کردن این سرویس، راهنمای فراداده منبع را ببینید.
این سرویس اطلاعات موردنیاز برای ساختن پُرسمان را به
GoogleAdsService ارائه می‌دهد. برای راحتی،
اطلاعات برگشتی از
GoogleAdsFieldService نیز در
مستندات مرجع فیلدها دردسترس است.