Authentication

במאמר הזה מוסבר איך לבצע אימות ב-Ad Manager API. האופן שבו מבצעים אימות משתנה לפי הממשק שמשמש לגישה ל-API ולסביבה שבה הקוד פועל, אבל כל בקשות ה-API חייבות לכלול אסימון גישה עם היקף הרשאות של Ad Manager API.

ספריות הלקוח של Ad Manager משתמשות ב-Application Default Credentials כדי ליצור אסימוני גישה עם היקפי הרשאות של Ad Manager API. במדריך הזה מוסבר איך להגדיר Application Default Credentials.

אם אתם לא משתמשים בספריית לקוח, אתם עדיין צריכים ליצור פרטי כניסה ולהשתמש בהם כדי לאשר את הבקשות שלכם.

למידע נוסף על אימות ומתן הרשאות, אפשר לעיין במדריך בנושא שימוש ב-OAuth 2.0.

קביעת סוג האימות

סוג אימות תיאור
חשבון שירות בוחרים באפשרות הזו אם רוצים לבצע אימות בתור חשבון ייעודי ולא בתור אדם מסוים.
מידע נוסף
אפליקציית אינטרנט בוחרים באפשרות הזו אם רוצים לבצע אימות בתור משתמש שמעניק לאפליקציה הרשאה לגשת לנתונים שלו ב-Ad Manager.
מידע נוסף
פיתוח מקומי בוחרים באפשרות הזו אם רוצים לבצע אימות כחשבון Google או כחשבון שירות בסביבת הפיתוח המקומית.

הפעלת Ad Manager API

  1. מפעילים את Ad Manager API בפרויקט ב-Google API Console Cloud.

  2. אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.

יצירת פרטי כניסה

לוחצים על הכרטיסייה של סוג האימות ופועלים לפי ההוראות כדי ליצור את פרטי הכניסה:

חשבון שירות

ב-Google Cloud

כדי לאמת עומס עבודה שפועל ב-Google Cloud, צריך להשתמש בפרטי הכניסה של חשבון השירות שמקושר למשאב המחשוב שבו הקוד פועל.

לדוגמה, אתם יכולים לקשר חשבון שירות למכונה וירטואלית (VM) של Compute Engine, לשירות Cloud Run או למשימת Dataflow. זאת שיטת האימות המועדפת לקוד שפועל במשאב מחשוב של Google Cloud.

במאמרים ומסמכי העזרה בנושא צירוף חשבונות שירות מוסבר לאילו משאבים אפשר לצרף חשבונות שירות ואיך מצרפים אותם.

בארגון או אצל ספק אחר של שירותי ענן

השיטה המועדפת להגדרת אימות מחוץ ל-Google Cloud היא באמצעות איחוד שירותי אימות הזהות של עומסי עבודה. כדי לעשות זאת, יוצרים קובץ תצורה עם פרטי הכניסה, ומגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS שיצביע אליו. הדרך הזו מאובטחת יותר מאשר יצירה של מפתח לחשבון שירות.

אם אין לכם אפשרות להגדיר את איחוד שירותי אימות הזהות של עומסי עבודה, תצטרכו ליצור חשבון שירות וליצור מפתח לחשבון השירות:

  1. פותחים את הדף Credentials (פרטי כניסה) ב-Google API Console.

  2. בדף Credentials, בוחרים באפשרות Create credentials ואז באפשרות Service Account.

  3. לוחצים על כתובת האימייל של חשבון השירות שעבורו רוצים ליצור מפתח.

  4. לוחצים על הכרטיסייה Keys.

  5. לוחצים על התפריט הנפתח Add key ובוחרים באפשרות Create new key.

  6. בוחרים באפשרות JSON בתור Key type ולוחצים על Create.

  7. מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ ה-JSON.

Linux או macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

אפליקציית אינטרנט

  1. פותחים את הדף Credentials (פרטי כניסה) ב-Google API Console.

  2. אם מתבקשים, בוחרים את הפרויקט שבו הפעלתם את Ad Manager API.

  3. בדף Credentials (פרטי כניסה), בוחרים באפשרות Create credentials (יצירת פרטי כניסה) ואז באפשרות OAuth client ID (מזהה לקוח OAuth).

  4. בוחרים את סוג האפליקציה אפליקציית אינטרנט.

  5. ממלאים את הטופס ולוחצים על יצירה. באפליקציות שמשתמשות בשפות ובמסגרות כמו PHP, ‏ Java, ‏ Python, ‏ Ruby ו-NET, צריך לציין מזהי URI של הפניה אוטומטית מורשים. כתובות ה-URI להפניה אוטומטית הן נקודות הקצה שאליהן שרת OAuth 2.0 יכול לשלוח תגובות. נקודות הקצה האלה צריכות לעמוד בכללי האימות של Google.

  6. אחרי שיוצרים את פרטי הכניסה, מורידים את הקובץ client_secret.json. מאחסנים את הקובץ באופן מאובטח במיקום שרק האפליקציה יכולה לגשת אליו.

מכאן, פועלים לפי השלבים לקבלת אסימוני גישה מסוג OAuth 2.0.

פיתוח מקומי

מגדירים את Application Default Credentials (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

הגדרת רשת Ad Manager

חשבון שירות

  1. עוברים אל רשת Ad Manager.
  2. לוחצים על הכרטיסייה אדמין.
  3. מוודאים שגישת API מופעלת.
  4. לוחצים על הלחצן הוספת משתמש לחשבון שירות.
  5. ממלאים את הטופס באמצעות כתובת האימייל של חשבון השירות. צריך להוסיף את המשתמש בחשבון השירות לתפקידים ולצוותים המתאימים לשילוב ה-API.
  6. לוחצים על הלחצן שמירה. אמורה להופיע הודעה שמאשרת את הוספת חשבון השירות.
  7. כדי לראות את המשתמשים הקיימים בחשבון השירות, עוברים לכרטיסייה Users ולוחצים על המסנן Service Account.

אפליקציית אינטרנט

  1. עוברים אל רשת Ad Manager.
  2. לוחצים על הכרטיסייה אדמין.
  3. מוודאים שגישת API מופעלת.

פיתוח מקומי

  1. עוברים אל רשת Ad Manager.
  2. לוחצים על הכרטיסייה אדמין.
  3. מוודאים שגישת API מופעלת.

ללא ספריית לקוח

אם אתם לא משתמשים בספריית לקוח, אנחנו עדיין ממליצים מאוד להשתמש בספריית OAuth2 לאימות.

הוראות מפורטות לקבלת אסימוני גישה זמינות במאמר שימוש ב-OAuth2 עם Google APIs.

אסימוני גישה

כדי לכלול את אסימון הגישה בבקשה ל-API, צריך לכלול פרמטר שאילתה 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.