Authentication

این سند نحوه اصالت‌سنجی کردن در Ad Manager API را شرح می‌دهد. نحوه اصالت‌سنجی شما به واسطی که استفاده می‌کنید و محیطی که کد شما در آن اجرا می‌شود بستگی دارد، اما همه درخواست‌های میانای برنامه‌سازی کاربردی باید شامل یک کد دسترسی با دامنه Ad Manager API باشند.

کتابخانه‌های کارخواه Ad Manager از اعتبارنامه‌های پیش‌فرض برنامه برای تولید کردن کد دسترسی با گستره‌های Ad Manager API استفاده می‌کنند. این راهنما نشان می‌دهد چگونه «اعتبارنامه‌های پیش‌فرض برنامه» را پیکربندی کنید.

اگر از کتابخانه کارخواه استفاده نمی‌کنید، همچنان باید اعتبارنامه ایجاد کنید و از آن برای صدور مجوز درخواست‌هایتان استفاده کنید.

برای اطلاعات بیشتر درباره اصالت‌سنجی و صدور مجوز، راهنمای استفاده از OAuth 2.0 را ببینید.

تعیین نوع اصالت‌سنجی

نوع اصالت‌سنجی شرح
حساب خدمات اگر می‌خواهید به‌عنوان حساب اختصاصی اصالت‌سنجی کنید و نه به‌عنوان فردی خاص، این گزینه را انتخاب کنید.
بیشتر بدانید.
برنامه وب اگر می‌خواهید به‌عنوان کاربری اصالت‌سنجی شوید که به برنامه شما اجازه می‌دهد به داده‌های Ad Manager او دسترسی داشته باشید، این گزینه را انتخاب کنید.
بیشتر بدانید
توسعه محلی اگر می‌خواهید به‌عنوان «حساب Google» خودتان یا «حساب سرویس» از محیط توسعه محلی‌تان اصالت‌سنجی کنید، این گزینه را انتخاب کنید.

فعال کردن Ad Manager API

  1. Ad Manager API را در «پروژه ابری کنسول Google API» فعال کنید.

  2. درصورت درخواست، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.

ایجاد اطلاعات کاربری

روی برگه مربوط به نوع اصالت‌سنجی‌تان کلیک کنید و دستورالعمل‌ها را برای ایجاد اطلاعات اعتباری‌تان دنبال کنید:

حساب خدمات

در Google Cloud

برای اصالت‌سنجی کردن حجم کاری درحال اجرا در Google Cloud، از اطلاعات اعتباری حساب سرویس پیوست‌شده به منبع محاسباتی که کد شما در آن اجرا می‌شود استفاده می‌کنید.

برای مثال، می‌توانید حساب سرویس را به نمونه ماشین مجازی (VM) موتور محاسباتی، سرویس Cloud Run، یا کار Dataflow پیوست کنید. این رویکرد روش اصالت‌سنجی ترجیحی برای اجرای کد در منبع محاسباتی Google Cloud است.

برای کسب اطلاعات درباره منابعی که می‌توانید حساب سرویس را به آن‌ها پیوست کنید، و راهنمایی درباره پیوست کردن حساب سرویس به منبع، به اسناد مربوط به پیوست کردن حساب سرویس مراجعه کنید.

در محل یا در ارائه‌دهنده فضای ابری دیگر

روش ترجیحی برای راه‌اندازی اصالت‌سنجی از خارج از Google Cloud استفاده از workload identity federation است؛ شما یک فایل پیکربندی اعتبارنامه ایجاد می‌کنید و متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم می‌کنید تا به آن اشاره کند. این رویکرد از ایجاد کلید حساب سرویس ایمن‌تر است.

اگر نمی‌توانید فدراسیون هویت حجم کاری را پیکربندی کنید، باید حساب سرویس ایجاد کنید و کلیدی برای حساب سرویس ایجاد کنید:

  1. صفحه اطلاعات کاربری کنسول Google API را باز کنید.

  2. در صفحه «اطلاعات کاربری»، ایجاد اطلاعات کاربری و سپس حساب سرویس را انتخاب کنید.

  3. روی نشانی ایمیل حساب خدماتی که می‌خواهید برای آن کلید ایجاد کنید کلیک کنید.

  4. روی برگه کلیدها کلیک کنید.

  5. روی منوِ کرکره‌ای افزودن کلید کلیک کنید، سپس ایجاد کلید جدید را انتخاب کنید.

  6. JSON را به‌عنوان نوع کلید انتخاب کنید و روی ایجاد کلیک کنید.

  7. متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل JSON تنظیم کنید.

Linux یا macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

برنامه وب

  1. صفحه اطلاعات کاربری کنسول Google API را باز کنید.

  2. درصورت درخواست، پروژه‌ای را که Ad Manager API را در آن فعال کرده‌اید انتخاب کنید.

  3. در صفحه «اعتبارنامه‌ها»، ایجاد اعتبارنامه را انتخاب کنید، سپس شناسه کارخواه OAuth را انتخاب کنید.

  4. نوع برنامه برنامه وب را انتخاب کنید.

  5. فرم را پر کنید و روی ایجاد کلیک کنید. برنامه‌هایی که از زبان‌ها و چارچوب‌هایی مثل PHP،‏ Java،‏ Python،‏ Ruby، و ‎ .NET استفاده می‌کنند باید URIهای تغییرمسیر مجاز را مشخص کنند. URIهای هدایت نقاط پایانی هستند که سرور OAuth 2.0 می‌تواند پاسخ‌ها را به آن‌ها ارسال کند. این نقاط پایانی باید از قوانین اعتبارسنجی Google پیروی کنند.

  6. پس‌از ایجاد اطلاعات کاربری، فایل client_secret.json را بارگیری کنید. فایل را به‌طور ایمن در مکانی ذخیره کنید که فقط برنامه‌تان بتواند به آن دسترسی داشته باشد.

از اینجا، مراحل دریافت کد دسترسی OAuth 2.0 را دنبال کنید

توسعه محلی

«اعتبارنامه‌های پیش‌فرض برنامه» (ADC) را در محیط محلی‌تان راه‌اندازی کنید.

Google Cloud CLI را نصب کنید، سپس آن را با اجرای فرمان زیر مقداردهی اولیه کنید:

gcloud init

اعتبارنامه‌های اصالت‌سنجی محلی برای «حساب Google» خود ایجاد کنید و شناسه پروژه را روی پروژه‌ای تنظیم کنید که Ad Manager 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 را روی مسیر فایل کلیدتان تنظیم کنید.

Linux یا macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

پیکربندی شبکه «مدیر آگهی» شما

حساب خدمات

  1. به شبکه Ad Manager خود بروید.
  2. روی برگه سرپرست کلیک کنید.
  3. مطمئن شوید دسترسی به میانای برنامه‌سازی کاربردی فعال باشد.
  4. روی دکمه افزودن کاربر حساب سرویس کلیک کنید.
  5. فرم را بااستفاده از ایمیل حساب خدمات تکمیل کنید. کاربر حساب سرویس باید به نقش‌ها و تیم‌های مناسب برای ادغام میانای برنامه‌سازی کاربردی شما اضافه شود.
  6. روی دکمه ذخیره کلیک کنید. پیامی باید ظاهر شود که اضافه شدن حساب سرویس شما را تأیید کند.
  7. با رفتن به برگه «کاربران» و سپس کلیک کردن روی فیلتر حساب خدمات، کاربران حساب خدمات موجود را مشاهده کنید.

برنامه وب

  1. به شبکه Ad Manager خود بروید.
  2. روی برگه سرپرست کلیک کنید.
  3. مطمئن شوید دسترسی به میانای برنامه‌سازی کاربردی فعال باشد.

توسعه محلی

  1. به شبکه Ad Manager خود بروید.
  2. روی برگه سرپرست کلیک کنید.
  3. مطمئن شوید دسترسی به میانای برنامه‌سازی کاربردی فعال باشد.

بدون کتابخانه مشتری

اگر از کتابخانه کارخواه استفاده نمی‌کنید، همچنان اکیداً توصیه می‌کنیم از کتابخانه OAuth2 برای اصالت‌سنجی استفاده کنید.

برای دستورالعمل‌های دقیق درباره دریافت کد دسترسی، استفاده از OAuth2 با Google APIs را ببینید.

کدهای دسترسی

با گنجاندن پارامتر پُرسمان access_token یا مقدار سرایند HTTP Authorization 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.