این راهنما مؤلفه‌های اصلی تشکیل‌دهنده 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) در سطح جهانی منحصربه‌فرد است |
| شناسه UserList | جهانی | بله |
| شناسه دارایی | جهانی | بله |
این قوانین شناسه می‌تواند هنگام طراحی فضای ذخیره‌سازی محلی برای اشیاء 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 عملیات را به‌صورت ناهمگام اجرا می‌کنند،
و فرایندها را برای انجام عملیات دیگر آزاد می‌کنند. می‌توانید به‌طور دوره‌ای وضعیت کار را برای تکمیل بررسی کنید.
برای اطلاعات بیشتر درباره پردازش ناهمگام، راهنمای پردازش دسته‌ای را ببینید.
اعتبارسنجی Mutate
اکثر درخواست‌های تغییر را می‌توان بدون اجرای واقعی فراخوانی دربرابر داده‌های واقعی اعتبارسنجی کرد. می‌توانید درخواست را برای پارامترهای مفقود و مقادیر فیلد نادرست بدون اجرای واقعی عملیات آزمایش کنید.
برای استفاده از این ویژگی، فیلد بولی اختیاری validate_only درخواست را روی
true تنظیم کنید. درخواست به‌طور کامل اعتبارسنجی می‌شود، گویی قرار است اجرا شود، اما
اجرای نهایی نادیده گرفته می‌شود. اگر خطایی پیدا نشود، پاسخ بدون نتایج جهش‌یافته برگردانده می‌شود (results خالی است). اگر اعتبارسنجی ناموفق باشد،
درخواست به‌طور پیش‌فرض با خطای GoogleAdsFailure RPC
ناموفق می‌شود (partial_failure = false)، یا پاسخ عادی با
خطاهای خاص عملیات در partial_failure_error برمی‌گرداند وقتی
partial_failure = true.
validate_only به‌ویژه برای آزمایش آگهی‌ها ازنظر نقض خط‌مشی‌های رایج مفید است. اگر آگهی‌ها خط‌مشی‌هایی مثل داشتن کلمات، نقطه‌گذاری، حروف بزرگ، یا طول خاص را نقض کنند، به‌طور خودکار رد می‌شوند. یک آگهی بد می‌تواند باعث شود کل دسته رد شود. آزمایش آگهی جدید در درخواست validate_only می‌تواند چنین نقض‌هایی را آشکار کند. برای دیدن این مورد در عمل، به نمونه کد مربوط به رسیدگی به خطاهای نقض خط‌مشی مراجعه کنید.
دریافت اشیاء و آمار عملکرد
GoogleAdsService تنها سرویس یکپارچه برای بازیابی اشیاء و آمار عملکرد است.
همه درخواست‌های Search و
SearchStream برای
GoogleAdsService به پرسمانی نیاز دارند که
منبع موردنظر برای پرسمان، مشخصه‌های منبع و سنجه‌های عملکرد
برای بازیابی، گزاره‌های مورداستفاده برای فیلتر کردن درخواست، و بخش‌های
مورداستفاده برای تفکیک بیشتر آمار عملکرد را مشخص کند. برای اطلاعات بیشتر درباره
قالب پُرسمان، به راهنمای زبان پُرسمان Google Ads مراجعه کنید.
بازیابی فراداده
GoogleAdsFieldService فراداده‌های مربوط به منابع را در Google Ads API بازیابی می‌کند، مانند مشخصه‌های دردسترس برای یک منبع و نوع داده آن. برای جزئیات مربوط به پُرسمان این سرویس، راهنمای فراداده منبع را ببینید.
این سرویس اطلاعات موردنیاز برای ساختن پُرسمان را به
GoogleAdsService ارائه می‌دهد. برای راحتی،
اطلاعات برگردانده‌شده توسط
GoogleAdsFieldService در
اسناد مرجع فیلدها نیز دردسترس است.