تماس‌ها با Search Ads 360 Reporting API معمولاً از طریق کتابخانه مشتری شما انجام می‌شود. برای اطلاعات بیشتر به توضیح کتابخانه های مشتری مراجعه کنید. با این حال، دانش در مورد ساختار جزئیات درخواست اساسی می تواند هنگام آزمایش و اشکال زدایی مفید باشد.
Search Ads 360 Reporting API یک API gRPC با اتصالات REST است. این بدان معنی است که می توانید به دو روش جایگزین با API تماس بگیرید:
- روش ترجیحی
- از کتابخانه مشتری استفاده کنید:
- بدنه درخواست را به عنوان بافر پروتکل ایجاد کنید.
- درخواست را با استفاده از HTTP/2 به سرور ارسال کنید.
- پاسخ به یک بافر پروتکل را غیراصولی کنید.
- نتایج را تفسیر کنید.
- روش جایگزین اختیاری
- از REST استفاده کنید:
- بدنه درخواست را به عنوان یک شی JSON ایجاد کنید.
- درخواست را با استفاده از HTTP 1.1 به سرور ارسال کنید.
- پاسخ را به‌عنوان یک شی JSON از حالت سریال خارج کنید.
- نتایج را تفسیر کنید.
برای اطلاعات بیشتر به Google Cloud API مراجعه کنید.
بخش های زیر برای هر دو پروتکل gRPC و REST اعمال می شود.
نام منابع
اکثر اشیاء در API با رشته های نام منبع خود شناسایی می شوند. این رشته ها هنگام استفاده از رابط REST نیز به عنوان URL عمل می کنند.
برای اطلاعات بیشتر در مورد منابع پشتیبانی شده و نمایش مسیر آنها به Reference > REST مراجعه کنید. از همین قالب برای سایر خدمات استفاده می شود.
شناسه های ترکیبی
اگر شناسه یک شی در سطح جهانی منحصر به فرد نباشد، یک شناسه ترکیبی برای آن شیء با اضافه کردن شناسه والد آن و یک tilde (~) ساخته می شود.
به عنوان مثال، از آنجایی که شناسه آگهی گروه آگهی در سطح جهانی منحصر به فرد نیست، شناسه شی والد (گروه آگهی) به آن اضافه می شود که منجر به یک شناسه ترکیبی منحصر به فرد می شود.
مثال: AdGroupId of 123 + ~ + AdGroupAdId of 45678 = شناسه تبلیغ گروه تبلیغات ترکیبی 123~45678 .
درخواست سرصفحه ها
سرصفحه های HTTP (یا فراداده های gRPC ) در بخش های زیر باید در متن درخواست گنجانده شوند.
مجوز
شما باید یک نشانه دسترسی OAuth2 را در فرم اضافه کنید:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
این توکن باید یا یک حساب مدیر که از طرف یک مشتری عمل می کند یا یک تبلیغ کننده که مستقیماً حساب مدیر فرعی یا مشتری خود را مدیریت می کند، مشخص کند. برای کسب اطلاعات بیشتر ، درباره حساب‌های مدیر Search Ads 360 و احراز هویت مراجعه کنید.
هدر شناسه مشتری وارد شوید
هنگام استفاده از حساب مدیر برای دسترسی به حساب مدیر فرعی یا مشتری، هدر login-customer-id مشتری الزامی است. هنگام دسترسی مستقیم به حساب مدیر فرعی یا مشتری نیازی به آن نیست. اگرچه کاملاً ضروری نیست، توصیه می کنیم همیشه login-customer-id برای کاربران احراز هویتی که به بیش از یک حساب دسترسی دارند، مشخص کنید. این امر از ابهام جلوگیری می کند و از تنظیم ناخواسته زمینه به حساب نادرست جلوگیری می کند.
درخواست باید شامل شناسه مشتری کاربر مجاز، بدون خط تیره ( - ) باشد، به عنوان مثال:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
تنظیم login-customer-id برابر است با انتخاب یک حساب کاربری در Search Ads 360 UI پس از ورود به سیستم یا کلیک کردن روی تصویر نمایه خود در بالا سمت راست.
سرصفحه های پاسخ
سرصفحه های زیر (یا gRPC trailing-metadata ) با بدنه پاسخ بازگردانده می شوند. توصیه می کنیم این مقادیر را برای اهداف اشکال زدایی ثبت کنید.
شناسه درخواست
سرآیند request-id رشته ای است که به طور منحصر به فرد درخواست را مشخص می کند.