هنگام فراخوانی API گوگل ادز، به اعتبارنامه OAuth 2.0 و یک توکن توسعه‌دهنده نیاز دارید. اگر فراخوانی‌های API را با یک حساب مدیر گوگل ادز انجام می‌دهید، باید یک هدر login-customer-id را نیز با هر درخواست مشخص کنید. این صفحه نحوه تنظیم این مقادیر را شرح می‌دهد و چندین هدر HTTP مخصوص API اضافی را که هنگام استفاده از رابط REST ارسال و دریافت می‌شوند، مستند می‌کند.
اعتبارنامه‌های OAuth 2.0
API گوگل ادز از OAuth 2.0 برای تأیید درخواست‌های API استفاده می‌کند. هم جریان تأیید هویت کاربر OAuth 2.0 و هم جریان حساب کاربری سرویس OAuth 2.0 پشتیبانی می‌شوند. برای جزئیات بیشتر، به OAuth 2.0 در API گوگل ادز مراجعه کنید.
اگر در استفاده از APIهای گوگل تازه‌کار هستید، می‌توانید قبل از نوشتن کد برای برنامه خود، از gcloud CLI یا OAuth 2.0 Playground برای آزمایش اعتبارنامه‌های OAuth 2.0 و API تبلیغات گوگل استفاده کنید.
توصیه می‌کنیم برای پیاده‌سازی گردش‌های کاری احراز هویت OAuth 2.0 از یکی از کتابخانه‌های OAuth 2.0 موجود در https://oauth.net/code/ استفاده کنید. با این حال، دستورالعمل‌های curl را در صورتی که نیاز به پیاده‌سازی خودتان داشته باشید، فهرست کرده‌ایم.
حساب‌های خدماتی
مراحل پیکربندی یک پروژه Google Cloud برای API تبلیغات گوگل را دنبال کنید. ایمیل حساب سرویس و کلید حساب سرویس را ثبت کنید. در مرحله بعد، دستورالعمل‌های رایج در راهنمای حساب‌های سرویس را برای تنظیم حساب سرویس جهت دسترسی به حساب تبلیغات گوگل خود دنبال کنید.
احراز هویت کاربر
مراحل پیکربندی یک پروژه کنسول ابری گوگل برای API گوگل ادز را دنبال کنید. شناسه کلاینت و رمز کلاینت را ثبت کنید. سپس، دستورالعمل‌های جریان برنامه دسکتاپ یا دستورالعمل‌های جریان برنامه وب را برای تولید یک توکن به‌روزرسانی و یک توکن دسترسی دنبال کنید. scope مورد استفاده برای دسترسی به API گوگل ادز، https://www.googleapis.com/auth/adwords است.
ایجاد توکن‌های دسترسی جدید
حساب‌های خدماتی
وقتی ایمیل حساب سرویس و کلید حساب سرویس را دارید، راهنمای استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور را برای تولید یک مجموعه ادعای JWT دنبال کنید، که سپس می‌تواند برای دریافت توکن دسترسی OAuth 2.0 مبادله شود. هنگام دنبال کردن راهنما، حتماً تب HTTP/REST را انتخاب کنید. scope OAuth 2.0 که برای دسترسی به API تبلیغات گوگل استفاده می‌شود، https://www.googleapis.com/auth/adwords است. علاوه بر این، می‌توانید هنگام ساخت مجموعه ادعای JWT از پارامتر sub صرف نظر کنید، زیرا مراحل راه‌اندازی، دسترسی مستقیم به حساب سرویس به حساب تبلیغات گوگل را فراهم می‌کند و از این رو از نیاز به جعل هویت یک کاربر تبلیغات گوگل جلوگیری می‌شود.
سپس از توکن دسترسی در هدر HTTP Authorization در هر فراخوانی API به API گوگل ادز استفاده می‌کنید:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
احراز هویت کاربر
زمانی که شناسه کلاینت OAuth 2.0، رمز کلاینت و توکن refresh را داشته باشید، می‌توانید با استفاده از ابزار خط فرمان 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 برگردانده می‌شود، در هدر HTTP Authorization در هر فراخوانی API به API گوگل ادز استفاده می‌کنید:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
درخواست سربرگ‌ها
توکن توسعه‌دهنده
API گوگل ادز همچنین برای برقراری ارتباط با API به یک توکن توسعه‌دهنده نیاز دارد. اگر از قبل توکن توسعه‌دهنده دارید، می‌توانید با مراجعه به آدرس https://ads.google.com/aw/apicenter آن را پیدا کنید. در صورت درخواست، وارد حساب مدیریت گوگل ادز خود شوید. اگر ندارید، دستورالعمل‌ها را برای ثبت‌نام برای دریافت توکن توسعه‌دهنده دنبال کنید.
شما باید مقدار توکن توسعه‌دهنده خود را در هدر HTTP developer-token هر فراخوانی API به API تبلیغات گوگل وارد کنید:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
شناسه مشتری ورود
برای فراخوانی‌های API گوگل ادز که توسط یک مدیر به یک حساب کاربری انجام می‌شود (یعنی، هنگام ورود به عنوان مدیر برای برقراری فراخوانی‌های API به یکی از حساب‌های کاربری خود)، باید هدر HTTP login-customer-id را نیز ارائه دهید. این مقدار نشان دهنده شناسه مشتری گوگل ادز مدیری است که فراخوانی API را انجام می‌دهد.
قرار دادن این سربرگ معادل انتخاب یک حساب کاربری در رابط کاربری گوگل ادز پس از ورود به سیستم یا کلیک روی تصویر پروفایل خود در گوشه سمت راست بالای صفحه است. هنگام مشخص کردن شناسه مشتری، حتماً هرگونه خط تیره (—) را حذف کنید. به عنوان مثال: 1234567890 ، نه 123-456-7890 . برای کسب اطلاعات بیشتر در مورد شناسه مشتری ورود به سیستم، به راهنمای مدل دسترسی گوگل ادز مراجعه کنید.
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
شناسه مشتری مرتبط
هدر شناسه مشتری لینک‌شده فقط توسط [ارائه‌دهندگان تجزیه و تحلیل برنامه شخص ثالث هنگام آپلود تبدیل‌ها به یک حساب Google Ads لینک‌شده استفاده می‌شود. برای جزئیات بیشتر به راهنمای ساختار فراخوانی API مراجعه کنید.
...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID
هدرهای پاسخ
هدرهای زیر در پاسخ‌های HTTP از API برگردانده می‌شوند.
درخواست شناسه
request-id رشته‌ای است که به طور منحصر به فرد درخواست API را مشخص می‌کند. هنگام اشکال‌زدایی یا عیب‌یابی مشکلات مربوط به فراخوانی‌های خاص API، شناسه request-id یک شناسه مهم است که هنگام تماس با پشتیبانی توسعه‌دهندگان گوگل باید در دسترس داشته باشید.
request-id: 2a5Cj89VV7CNhya1DZjjrC