هنگام فراخوانی 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. علاوه‌براین، می‌توانید از پارامتر
sub هنگام ساختن مجموعه ادعای JWT صرف‌نظر کنید، زیرا مراحل راه‌اندازی
به حساب سرویس دسترسی مستقیم به حساب Google Ads می‌دهد، بنابراین نیازی به
جعل هویت کاربر Google Ads نیست.
سپس از کد دسترسی در سرصفحه Authorization HTTP
هر فراخوانی میانای برنامه‌سازی کاربردی به Google Ads API استفاده می‌کنید:
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
اصالت‌سنجی کاربر
وقتی شناسه کارخواه، رمز کارخواه، و ژتون بازآوری OAuth 2.0 را دریافت کردید، می‌توانید کد دسترسی جدیدی برای استفاده در فراخوانی‌های API با ابزار خط فرمان curl تولید کنید:
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 مدیری است که فراخوانی API را انجام می‌دهد.
گنجاندن این سرصفحه معادل انتخاب حساب در میانای کاربری 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 را به‌طور یکتا شناسایی می‌کند. هنگام اشکال‌زدایی یا عیب‌یابی مشکلات مربوط به فراخوانی‌های API خاص، request-id شناسه مهمی است که باید هنگام تماس با پشتیبانی توسعه‌دهنده Google در دسترس داشته باشید.
request-id: 2a5Cj89VV7CNhya1DZjjrC