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