هنگام فراخوانی Google Ads API، به اعتبارنامه OAuth 2.0 نیاز دارید. اگر با حساب مدیر Google Ads تماس‌های API برقرار می‌کنید، باید برای هر درخواست یک سرصفحه login-customer-id نیز مشخص کنید. این صفحه نحوه تنظیم این مقادیر را شرح می‌دهد و چندین سرایند HTTP دیگر مختص API را که هنگام استفاده از میانای REST ارسال و دریافت می‌شوند مستند می‌کند.
اعتبارنامه‌های OAuth 2.0
Google Ads API از OAuth 2.0 برای صدور مجوز درخواست‌های API استفاده می‌کند. هم جریان اصالت‌سنجی کاربر OAuth 2.0 و هم جریان حساب سرویس پشتیبانی می‌شوند. برای جزئیات بیشتر، OAuth 2.0 در Google Ads API را ببینید.
اگر با Google API آشنایی ندارید، می‌توانید از ابزار خط فرمان gcloud یا OAuth 2.0 Playground برای آزمایش اعتبارنامه‌های OAuth 2.0 و Google Ads API قبل‌از نوشتن کد برای برنامه‌تان استفاده کنید.
توصیه می‌کنیم از یکی از کتابخانه‌های OAuth 2.0 موجود در https://oauth.net/code/ برای پیاده‌سازی گردش‌های کاری مجوز OAuth 2.0 استفاده کنید. بااین‌حال، دستورالعمل‌های curl را فهرست کرده‌ایم تا درصورت نیاز خودتان آن را پیاده‌سازی کنید.
حساب‌های سرویس
مراحل پیکربندی پروژه Google Cloud برای Google Ads API را دنبال کنید. ایمیل حساب سرویس و کلید حساب سرویس را ثبت کنید. سپس، دستورالعمل‌های رایج در راهنمای حساب‌های سرویس را دنبال کنید تا حساب سرویس را برای دسترسی به حساب Google Ads خود راه‌اندازی کنید.
اصالت‌سنجی کاربر
مراحل پیکربندی پروژه «کنسول Google Cloud» برای
Google Ads API را دنبال کنید. شناسه کارخواه و رمز کارخواه را ضبط کنید. سپس، دستورالعمل‌های جریان برنامه رایانه‌ای
یا دستورالعمل‌های جریان برنامه وب
را دنبال کنید تا ژتون بازآوری و کد دسترسی تولید کنید. scope برای استفاده
برای دسترسی به Google Ads API، https://www.googleapis.com/auth/adwords است.
تولید کردن کدهای دسترسی جدید
حساب‌های سرویس
وقتی ایمیل حساب سرویس و کلید حساب سرویس را داشتید،
راهنمای استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور را دنبال کنید
تا مجموعه ادعای JWT تولید کنید که سپس می‌توان آن را برای دریافت
کد دسترسی OAuth 2.0 مبادله کرد. هنگام دنبال کردن راهنما، حتماً برگه HTTP/REST را انتخاب کنید. OAuth 2.0 scope برای استفاده جهت دسترسی به Google Ads API عبارت است از
https://www.googleapis.com/auth/adwords. علاوه‌براین، می‌توانید هنگام ساختن مجموعه ادعای JWT، از پارامتر sub صرف‌نظر کنید، زیرا مراحل راه‌اندازی به حساب سرویس دسترسی مستقیم به حساب Google Ads می‌دهد، بنابراین نیازی به جعل هویت کاربر Google Ads نیست.
سپس از کد دسترسی در سرایند Authorization HTTP
هر فراخوانی API به Google Ads API استفاده می‌کنید:
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
اصالت‌سنجی کاربر
وقتی شناسه کارخواه، رمز کارخواه، و ژتون بازآوری OAuth 2.0 را دریافت کردید، می‌توانید بااستفاده از ابزار خط فرمان curl، کد دسترسی جدیدی برای استفاده در فراخوانی‌های API تولید کنید:
curl \
--data "grant_type=refresh_token" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "refresh_token=REFRESH_TOKEN" \
https://www.googleapis.com/oauth2/v3/tokenسپس از کد دسترسی برگردانده‌شده توسط درخواست curl در
Authorization سرایند HTTP هر فراخوانی میانای برنامه‌سازی کاربردی به Google Ads API استفاده می‌کنید:
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
سرایندهای درخواست
بخش‌های زیر سرایندهای HTTP را که هنگام درخواست به Google Ads API لازم است یا استفاده می‌شود شرح می‌دهد.
شناسه مشتری ورود به سیستم
برای فراخوانی‌های Google Ads API که توسط مدیر برای حساب مشتری انجام می‌شود (یعنی هنگام ورود به سیستم به‌عنوان مدیر برای انجام فراخوانی‌های میانای برنامه‌سازی کاربردی به یکی از حساب‌های مشتری)، باید سرصفحه HTTP login-customer-id را نیز ارائه دهید. این مقدار نشان‌دهنده شناسه مشتری Google Ads مدیری است که فراخوانی میانای برنامه‌سازی کاربردی را انجام می‌دهد.
گنجاندن این سرصفحه معادل انتخاب حساب در میانای کاربری Google Ads
پس‌از ورود به سیستم یا کلیک کردن روی تصویر نمایه در گوشه بالا سمت چپ
صفحه است. هنگام مشخص کردن شناسه مشتری، حتماً خط تیره‌ها (—) را بردارید. برای مثال: 1234567890، نه 123-456-7890. برای کسب اطلاعات بیشتر درباره شناسه مشتری ورود به سیستم، به راهنمای مدل دسترسی Google Ads مراجعه کنید.
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
شناسه مشتری پیوندشده
سرصفحه «شناسه مشتری پیوندشده» توسط شرکا (مانند ارائه‌دهندگان تحلیل داده‌های برنامه طرف سوم یا شرکای داده) هنگام اقدام در حساب Google Ads پیوندشده استفاده می‌شود. برای جزئیات بیشتر، راهنمای ساختار فراخوانی میانای برنامه‌سازی کاربردی را ببینید.
Authorization: Bearer ACCESS_TOKEN
login-customer-id: PARTNER_CUSTOMER_ID
linked-customer-id: ADVERTISER_CUSTOMER_ID
سرایندهای پاسخ
سرایندهای زیر در پاسخ‌های HTTP از API برگردانده می‌شوند.
شناسه درخواست
request-id رشته‌ای است که درخواست API را به‌طور منحصربه‌فرد شناسایی می‌کند. هنگام
اشکال‌زدایی یا عیب‌یابی مشکلات مربوط به فراخوانی‌های میانای برنامه‌سازی کاربردی خاص، request-id
شناسه مهمی است که باید هنگام تماس با پشتیبانی توسعه‌دهنده Google
دردسترس باشد.
request-id: 2a5Cj89VV7CNhya1DZjjrC