هنگام فراخوانی 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 APIs آشنایی ندارید، می‌توانید از gcloud CLI یا OAuth 2.0 Playground برای آزمایش کردن با اطلاعات اعتباری OAuth 2.0 و Google Ads API قبل‌از نوشتن کد برای برنامه‌تان استفاده کنید.
توصیه می‌کنیم برای پیاده‌سازی گردش‌های کار OAuth 2.0، از یکی از کتابخانه‌های OAuth 2.0 موجود در https://oauth.net/code/ استفاده کنید. بااین‌حال، دستورالعمل‌های 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 که توسط مدیر به حساب مشتری انجام می‌شود (یعنی زمانی که به‌عنوان مدیر وارد سیستم می‌شوید تا فراخوانی‌های API را به یکی از حساب‌های مشتری خود انجام دهید)، باید سرصفحه 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