ویدئوی : سخنرانی مربوط به خدمات و منابع را از کارگاه سال ۲۰۱۹ ببینید
این راهنما اجزای اصلی تشکیلدهندهی API گوگل ادز را معرفی میکند. API گوگل ادز از منابع و سرویسها تشکیل شده است. یک منبع، یک موجودیت گوگل ادز را نشان میدهد، در حالی که سرویسها، موجودیتهای گوگل ادز را بازیابی و دستکاری میکنند.
سلسله مراتب شیء
یک حساب کاربری گوگل ادز را میتوان به صورت سلسله مراتبی از اشیاء در نظر گرفت.
منبع سطح بالای یک حساب، مشتری است.
هر مشتری شامل یک یا چند کمپین فعال است.
هر کمپین شامل یک یا چند گروه تبلیغاتی است که برای گروهبندی تبلیغات شما در مجموعههای منطقی استفاده میشود.
یک تبلیغ گروهی، تبلیغی را نشان میدهد که شما در حال اجرا دارید. به جز کمپینهای اپلیکیشن که میتوانند فقط یک تبلیغ گروه تبلیغاتی در هر گروه تبلیغاتی داشته باشند، هر گروه تبلیغاتی شامل یک یا چند تبلیغ گروه تبلیغاتی است.
شما میتوانید یک یا چند AdGroupCriterion یا CampaignCriterion را به یک گروه تبلیغاتی یا کمپین اضافه کنید. این معیارها، معیارهایی هستند که نحوهی نمایش تبلیغات را تعریف میکنند.
انواع معیارها ، مانند کلمات کلیدی، محدوده سنی و مکانها، وجود دارد. معیارهای تعریف شده در سطح کمپین بر سایر منابع درون کمپین تأثیر میگذارند. همچنین میتوانید بودجهها و تاریخهای کل کمپین را مشخص کنید.
در نهایت، میتوانید داراییها را در سطح حساب، کمپین یا گروه تبلیغاتی پیوست کنید. داراییها به شما امکان میدهند اطلاعات اضافی مانند شماره تلفن، آدرس خیابان یا تبلیغات را به تبلیغات خود اضافه کنید. به نمای کلی داراییها مراجعه کنید.
منابع
منابع، موجودیتهای موجود در حساب گوگل ادز شما را نشان میدهند. Campaign و AdGroup دو نمونه از منابع هستند.
شناسههای شیء
هر شیء در گوگل ادز با شناسه (ID) مخصوص به خود شناسایی میشود. برخی از این شناسهها در تمام حسابهای گوگل ادز منحصر به فرد هستند، در حالی که برخی دیگر فقط در یک محدوده خاص منحصر به فرد هستند.
| شناسه شیء | دامنه منحصر به فرد بودن | منحصر به فرد در سطح جهانی؟ |
|---|---|---|
| شناسه بودجه | جهانی | بله |
| شناسه کمپین | جهانی | بله |
| شناسه گروه تبلیغاتی | جهانی | بله |
| شناسه آگهی | گروه تبلیغاتی | خیر، اما جفت ( AdGroupId ، AdId ) به صورت سراسری منحصر به فرد است. |
| شناسه معیار گروه تبلیغاتی | گروه تبلیغاتی | خیر، اما جفت ( AdGroupId ، CriterionId ) به صورت سراسری منحصر به فرد است. |
| شناسه معیار کمپین | کمپین | خیر، اما جفت ( CampaignId ، CriterionId ) به صورت سراسری منحصر به فرد است. |
| شناسه برچسب | مشتری | خیر، اما جفت ( CustomerId و LabelId ) به صورت سراسری منحصر به فرد است. |
| شناسه فهرست کاربران | جهانی | بله |
| شناسه دارایی | جهانی | بله |
این قوانین شناسه میتوانند هنگام طراحی فضای ذخیرهسازی محلی برای اشیاء Google Ads شما مفید باشند.
برخی از اشیاء میتوانند برای چندین نوع موجودیت استفاده شوند. در چنین مواردی، شیء شامل یک فیلد type است که محتوای آن را توصیف میکند. برای مثال، AdGroupAd میتواند به یک شیء مانند یک تبلیغ متنی، تبلیغ هتل یا تبلیغ محلی اشاره کند. این مقدار از طریق فیلد AdGroupAd.ad.type قابل دسترسی است و مقداری را در شمارش AdType برمیگرداند.
نام منابع
هر منبع به طور منحصر به فرد توسط یک رشته resource_name شناسایی میشود که منبع و والدینش را در یک مسیر به هم متصل میکند. برای مثال، نام منابع کمپین به شکل زیر است:
customers/customer_id/campaigns/campaign_id
بنابراین برای یک کمپین با شناسه 987654 در حساب گوگل ادز با شناسه مشتری 1234567 ، resource_name خواهد بود:
customers/1234567/campaigns/987654
خدمات
سرویسها به شما امکان میدهند موجودیتهای گوگل ادز خود را بازیابی و اصلاح کنید. سه نوع سرویس وجود دارد: سرویسهای اصلاح، بازیابی اشیاء و آمار، و بازیابی فراداده.
تغییر (جهش) اشیاء
این سرویسها نمونههایی از یک نوع منبع مرتبط را با استفاده از یک درخواست mutate اصلاح میکنند. آنها همچنین یک درخواست get ارائه میدهند که یک نمونه منبع واحد را بازیابی میکند، که میتواند برای بررسی ساختار یک منبع مفید باشد.
نمونههایی از خدمات:
CustomerServiceبرای اصلاح مشتریان .CampaignServiceبرای اصلاح کمپینها .AdGroupServiceبرای تغییر گروههای تبلیغاتی .
هر درخواست mutate باید شامل اشیاء operation مربوطه باشد. برای مثال، متد CampaignService.MutateCampaigns انتظار یک یا چند نمونه از CampaignOperation را دارد. برای بحث مفصل در مورد عملیات، به بخش تغییر و بازرسی اشیاء مراجعه کنید.
جهشهای همزمان
یک شیء گوگل ادز نمیتواند همزمان توسط بیش از یک منبع تغییر کند. اگر چندین کاربر یک شیء را با برنامه شما بهروزرسانی کنند، یا اگر اشیاء گوگل ادز را به صورت موازی با استفاده از چندین thread تغییر دهید، این میتواند باعث بروز خطا شود. این شامل بهروزرسانی شیء از چندین thread در همان برنامه یا از برنامههای مختلف (به عنوان مثال، برنامه شما و یک جلسه رابط کاربری گوگل ادز همزمان) میشود.
این API راهی برای قفل کردن یک شیء قبل از بهروزرسانی ارائه نمیدهد؛ اگر دو منبع سعی کنند همزمان یک شیء را تغییر دهند، API DatabaseError.CONCURRENT_MODIFICATION_ERROR را ایجاد میکند.
جهشهای ناهمگام در مقابل جهشهای همزمان
متدهای تغییر API گوگل ادز همگام هستند. فراخوانیهای API فقط پس از تغییر اشیاء پاسخ میدهند و شما را ملزم میکنند که برای پاسخ به هر درخواست منتظر بمانید. اگرچه این رویکرد از نظر کدنویسی نسبتاً ساده است، اما اگر فرآیندها مجبور شوند برای تکمیل فراخوانیها منتظر بمانند، میتواند تأثیر منفی بر تعادل بار و اتلاف منابع داشته باشد.
یک رویکرد جایگزین، تغییر اشیاء به صورت غیرهمزمان با استفاده از BatchJobService است که دستههایی از عملیات را روی چندین سرویس بدون انتظار برای تکمیل آنها انجام میدهد. پس از ارسال یک کار دستهای، سرورهای Google Ads API عملیات را به صورت غیرهمزمان اجرا میکنند و فرآیندها را برای انجام سایر عملیات آزاد میکنند. میتوانید به صورت دورهای وضعیت تکمیل کار را بررسی کنید.
برای اطلاعات بیشتر در مورد پردازش ناهمزمان، به راهنمای پردازش دستهای مراجعه کنید.
اعتبارسنجی جهشی
اکثر درخواستهای mutate را میتوان بدون اجرای واقعی فراخوانی در برابر دادههای واقعی اعتبارسنجی کرد. میتوانید درخواست را برای پارامترهای از دست رفته و مقادیر نادرست فیلد بدون اجرای واقعی عملیات آزمایش کنید.
برای استفاده از این ویژگی، فیلد بولی اختیاری validate_only درخواست را روی true تنظیم کنید. سپس درخواست به طور کامل اعتبارسنجی میشود، گویی قرار است اجرا شود، اما اجرای نهایی نادیده گرفته میشود. اگر هیچ خطایی یافت نشود، یک پاسخ خالی بازگردانده میشود. اگر اعتبارسنجی با شکست مواجه شود، پیامهای خطا در پاسخ، نقاط شکست را نشان میدهند.
validate_only به ویژه در آزمایش تبلیغات برای نقضهای رایج سیاستها مفید است. اگر تبلیغات سیاستهایی مانند داشتن کلمات خاص، علائم نگارشی، حروف بزرگ یا طول را نقض کنند، به طور خودکار رد میشوند. یک تبلیغ بد میتواند باعث شکست کل یک دسته شود. آزمایش یک تبلیغ جدید در یک درخواست validate_only میتواند هرگونه نقض این چنینی را آشکار کند. برای مشاهده این مورد در عمل، به مثال کد برای مدیریت خطاهای نقض سیاست مراجعه کنید.
دریافت اشیاء و آمار عملکرد
GoogleAdsService یک سرویس واحد و یکپارچه برای بازیابی اشیاء و آمار عملکرد است.
همه درخواستهای Search و SearchStream برای GoogleAdsService نیاز به یک پرسوجو دارند که منبع مورد نظر برای پرسوجو، ویژگیهای منبع و معیارهای عملکرد مورد نیاز برای بازیابی، گزارههای مورد استفاده برای فیلتر کردن درخواست و بخشهای مورد استفاده برای تجزیه و تحلیل بیشتر آمار عملکرد را مشخص کند. برای اطلاعات بیشتر در مورد قالب پرسوجو، به راهنمای زبان پرسوجوی Google Ads مراجعه کنید.
بازیابی فراداده
GoogleAdsFieldService فرادادههایی درباره منابع موجود در API گوگل ادز، مانند ویژگیهای موجود برای یک منبع و نوع داده آن، را بازیابی میکند.
این سرویس اطلاعات مورد نیاز برای ساخت یک پرسوجو به GoogleAdsService را فراهم میکند. برای راحتی، اطلاعات برگردانده شده توسط GoogleAdsFieldService در مستندات مرجع فیلدها نیز موجود است.