این سند نحوه احراز هویت در رابط برنامهنویسی کاربردی مدیریت تبلیغات (Ad Manager API) را شرح میدهد. نحوه احراز هویت شما به رابط کاربری مورد استفاده و محیطی که کد شما در آن اجرا میشود بستگی دارد، اما همه درخواستهای API باید شامل یک توکن دسترسی با دامنه API مدیریت تبلیغات (Ad Manager API scope) باشند.
کتابخانههای کلاینت Ad Manager از Application Default Credentials برای تولید توکنهای دسترسی با محدودههای API Ad Manager استفاده میکنند. این راهنما نحوه پیکربندی Application Default Credentials را نشان میدهد.
اگر از کتابخانه کلاینت استفاده نمیکنید، همچنان باید اعتبارنامه ایجاد کنید و از آنها برای تأیید درخواستهای خود استفاده کنید.
برای اطلاعات بیشتر در مورد احراز هویت و مجوز، به راهنمای استفاده از OAuth 2.0 مراجعه کنید.
نوع احراز هویت خود را تعیین کنید
| نوع احراز هویت | توضیحات |
|---|---|
| حساب کاربری خدمات | اگر میخواهید به جای یک شخص خاص، به عنوان یک حساب اختصاصی تأیید اعتبار کنید، این گزینه را انتخاب کنید. بیشتر بدانید . |
| برنامه وب | اگر میخواهید به عنوان هر کاربری که به برنامه شما اجازه دسترسی به دادههای Ad Manager خود را میدهد، احراز هویت شوید، این گزینه را انتخاب کنید. بیشتر بدانید |
| توسعه محلی | اگر میخواهید به عنوان حساب گوگل خودتان یا یک حساب سرویس از محیط توسعه محلی خود تأیید اعتبار کنید، این را انتخاب کنید. |
فعال کردن رابط برنامهنویسی کاربردی مدیریت تبلیغات (Ad Manager API)
رابط برنامهنویسی کاربردی مدیریت تبلیغات (Ad Manager API) را در پروژه ابری کنسول API گوگل خود فعال کنید.
در صورت درخواست، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید.
ایجاد اعتبارنامه
روی برگه مربوط به نوع احراز هویت خود کلیک کنید و دستورالعملها را برای ایجاد اعتبارنامه دنبال کنید:
حساب کاربری خدمات
روی فضای ابری گوگل
برای تأیید اعتبار یک بار کاری که روی Google Cloud اجرا میشود، از اعتبارنامههای حساب سرویس متصل به منبع محاسباتی که کد شما در آن اجرا میشود، استفاده میکنید.
برای مثال، میتوانید یک حساب کاربری سرویس را به یک نمونه ماشین مجازی (VM) از Compute Engine، یک سرویس Cloud Run یا یک کار Dataflow متصل کنید. این رویکرد، روش احراز هویت ترجیحی برای اجرای کد روی منبع محاسباتی Google Cloud است.
برای اطلاعات در مورد اینکه به کدام منابع میتوانید یک حساب سرویس متصل کنید و کمک در اتصال حساب سرویس به منبع، به مستندات مربوط به اتصال یک حساب سرویس مراجعه کنید.
در محل یا در یک ارائه دهنده ابری متفاوت
روش ترجیحی برای تنظیم احراز هویت از خارج از Google Cloud، استفاده از فدراسیون هویت بار کاری است؛ شما یک فایل پیکربندی اعتبارنامه ایجاد میکنید و متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را طوری تنظیم میکنید که به آن اشاره کند. این رویکرد نسبت به ایجاد یک کلید حساب سرویس، امنتر است.
اگر قادر به پیکربندی فدراسیون هویت بار کاری نیستید، باید یک حساب کاربری سرویس ایجاد کنید و برای حساب کاربری سرویس یک کلید ایجاد کنید:
صفحه اعتبارنامههای کنسول API گوگل را باز کنید.
در صفحه اعتبارنامهها، گزینه ایجاد اعتبارنامهها و سپس حساب سرویس را انتخاب کنید.
روی آدرس ایمیل حساب سرویسی که میخواهید برای آن کلید ایجاد کنید، کلیک کنید.
روی برگه کلیدها کلیک کنید.
روی منوی کشویی «افزودن کلید» کلیک کنید، سپس «ایجاد کلید جدید» را انتخاب کنید.
نوع کلید را JSON انتخاب کنید و روی Create کلیک کنید.
متغیر محیطی
GOOGLE_APPLICATION_CREDENTIALSرا روی مسیر فایل JSON تنظیم کنید.
لینوکس یا macOS
export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATHویندوز
set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATHبرنامه وب
صفحه اعتبارنامههای کنسول API گوگل را باز کنید.
در صورت درخواست، پروژهای را که در آن رابط برنامهنویسی کاربردی مدیریت تبلیغات (Ad Manager API) را فعال کردهاید، انتخاب کنید.
در صفحه اعتبارنامهها، گزینه ایجاد اعتبارنامهها و سپس شناسه کلاینت OAuth را انتخاب کنید.
نوع برنامه کاربردی وب را انتخاب کنید.
فرم را پر کنید و روی ایجاد کلیک کنید. برنامههایی که از زبانها و چارچوبهایی مانند PHP، Java، Python، Ruby و .NET استفاده میکنند، باید URI های ریدایرکت مجاز را مشخص کنند. URI های ریدایرکت، نقاط پایانی هستند که سرور OAuth 2.0 میتواند به آنها پاسخ ارسال کند. این نقاط پایانی باید از قوانین اعتبارسنجی گوگل پیروی کنند.
پس از ایجاد اعتبارنامههای خود، فایل client_secret.json را دانلود کنید. این فایل را به طور ایمن در مکانی که فقط برنامه شما به آن دسترسی داشته باشد، ذخیره کنید.
از اینجا، مراحل دریافت توکنهای دسترسی OAuth 2.0 را دنبال کنید.
توسعه محلی
اعتبارنامههای پیشفرض برنامه (ADC) را در محیط محلی خود تنظیم کنید.
رابط خط فرمان گوگل کلود (Google Cloud CLI) را نصب کنید، سپس با اجرای دستور زیر آن را راهاندازی کنید:
gcloud initاعتبارنامههای احراز هویت محلی را برای حساب گوگل خود ایجاد کنید و شناسه پروژه را روی پروژهای تنظیم کنید که API مدیریت تبلیغات در آن فعال باشد:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/admanager"
gcloud auth application-default set-quota-project PROJECT_ID روش دیگر، احراز هویت به عنوان یک حساب کاربری سرویس با تنظیم متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS به مسیر فایل کلید خود است.
لینوکس یا macOS
export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATHویندوز
set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATHشبکه مدیریت تبلیغات خود را پیکربندی کنید
حساب کاربری خدمات
- به شبکه مدیر تبلیغات خود بروید.
- روی برگه مدیریت کلیک کنید.
- مطمئن شوید که دسترسی API فعال است.
- روی دکمه افزودن حساب کاربری سرویس کلیک کنید.
- فرم را با استفاده از ایمیل حساب کاربری سرویس پر کنید. کاربر حساب کاربری سرویس باید به نقشها و تیمهای مناسب برای ادغام API شما اضافه شود.
- روی دکمه ذخیره کلیک کنید. پیامی ظاهر میشود که افزودن حساب کاربری سرویس شما را تأیید میکند.
- با رفتن به برگه کاربران و سپس کلیک بر روی فیلتر حساب سرویس ، کاربران حساب سرویس موجود را مشاهده کنید.
برنامه وب
- به شبکه مدیر تبلیغات خود بروید.
- روی برگه مدیریت کلیک کنید.
- مطمئن شوید که دسترسی API فعال است.
توسعه محلی
- به شبکه مدیر تبلیغات خود بروید.
- روی برگه مدیریت کلیک کنید.
- مطمئن شوید که دسترسی API فعال است.
بدون کتابخانه کلاینت
اگر از کتابخانه کلاینت استفاده نمیکنید، ما همچنان اکیداً توصیه میکنیم از کتابخانه OAuth2 برای احراز هویت استفاده کنید.
برای دستورالعملهای دقیق در مورد دریافت توکنهای دسترسی، به بخش «استفاده از OAuth2 با APIهای گوگل» مراجعه کنید.
توکنهای دسترسی
توکن دسترسی خود را در درخواست به API با وارد کردن پارامتر پرسوجوی access_token یا مقدار حامل هدر HTTP Authorization HTTP header Bearer ) قرار دهید. در صورت امکان، هدر HTTP ترجیح داده میشود، زیرا رشتههای پرسوجو معمولاً در گزارشهای سرور قابل مشاهده هستند.
برای مثال:
GET /v1/networks/1234
Host: admanager.googleapis.com
Authorization: Bearer ya29.a0Ad52N3_shYLX
GET https://admanager.googleapis.com/v1/networks/1234?access_token=1/fFAGRNJru1FTz70BzhT3Zg
محدوده
هر توکن دسترسی با یک یا چند حوزه مرتبط است. یک حوزه، مجموعه منابع و عملیاتی را که یک توکن دسترسی مجاز میداند، کنترل میکند. رابط برنامهنویسی کاربردی مدیریت تبلیغات (Ad Manager API) دو حوزه دارد. اگر برنامه شما نیازی به نوشتن داده ندارد، توصیه میکنیم از حوزه محدودتر admanager.readonly استفاده کنید.
| محدوده | مجوزها |
|---|---|
https://www.googleapis.com/auth/admanager | کمپینهای خود را در Google Ad Manager مشاهده و مدیریت کنید. |
https://www.googleapis.com/auth/admanager.readonly | کمپینها و دادههای خود را در Google Ad Manager مشاهده کنید. |