חשבונות שירות

במדריך הזה מוסבר איך לגשת ל-Google Ads API באמצעות חשבונות שירות.

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

חשבונות שירות משתמשים בתהליך OAuth 2.0 שלא מחייב הרשאה אנושית, ובמקום זאת משתמשים בקובץ מפתח שרק לאפליקציה שלכם יש גישה אליו.

לשימוש בחשבונות שירות יש שני יתרונות עיקריים:

  • ההרשאה לגישה ל-Google API מתבצעת כשלב בהגדרה, וכך נמנעים מהמורכבויות שמשויכות לתהליכים אחרים של OAuth 2.0 שדורשים אינטראקציות של משתמשים.

  • תהליך טענת הנכוֹנוּת (assertion) של OAuth 2.0 מאפשר לאפליקציה להתחזות למשתמשים אחרים במקרה הצורך.

יש שתי דרכים להעניק הרשאה באמצעות חשבונות שירות: ישירות או באמצעות התחזות.

הרשאה עם גישה ישירה לחשבון

באפשרות הזו, אתם מעניקים לחשבון השירות גישה ישירה לחשבון Google Ads שלכם.

הגדרת הגישה לחשבון

  1. קודם צריך ליצור חשבון שירות ופרטי כניסה.

    מורידים את המפתח של חשבון השירות בפורמט JSON ומתעדים את מזהה חשבון השירות ואת כתובת האימייל שלו.

  2. נכנסים לחשבון Google Ads כאדמינים. עוברים אל אדמין > אבטחה וגישה.

  3. לוחצים על הלחצן + בכרטיסייה משתמשים.

  4. מקלידים את כתובת האימייל של חשבון השירות בתיבה Email. בוחרים את רמת הגישה המתאימה לחשבון ולוחצים על הלחצן Add account. לתשומת ליבכם: אין תמיכה ברמות הגישה 'אימייל' ו'אדמין' בחשבונות שירות.

  5. חשבון השירות מקבל גישה.

הגדרת ספריית הלקוח

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

Java

מגדירים את הנתיב של קובץ ה-JSON של המפתח הפרטי בהגדרות. אם משתמשים בקובץ ads.properties, מוסיפים את הפרטים הבאים:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

פרטים נוספים זמינים במדריך להגדרה.

‎.NET

מגדירים את המפתחות הבאים ב-App.config / Web.config. פרטים נוספים זמינים במדריך להגדרה.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

מגדירים את הנתיב של קובץ ה-JSON של המפתח הפרטי בהגדרות. אם משתמשים ב-google-ads.yaml file, במחרוזת YAML או ב-dict, מוסיפים את הפרטים הבאים:

json_key_file_path: JSON_KEY_FILE_PATH

אם אתם משתמשים במשתני סביבה, מוסיפים את הפרטים הבאים לתצורה או לסביבה של Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

מגדירים את המפתחות הבאים ב-google_ads_php.ini. פרטים נוספים זמינים במדריך להגדרה.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

מגדירים את המפתחות הבאים ב-google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

מגדירים את הנתיב של קובץ ה-JSON של המפתח הפרטי ואת מזהה החשבון להענקת גישה בהגדרות. אם משתמשים בקובץ googleads.properties, מוסיפים את הקוד הבא:

jsonKeyFilePath=JSON_KEY_FILE_PATH

אם אתם משתמשים במשתני סביבה, מוסיפים את הפרטים הבאים לתצורה או לסביבה של Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

הרשאה באמצעות התחזות

באפשרות הזו, מתחזים למשתמש שיש לו גישה לחשבון Google Ads באמצעות חשבון השירות. הגישה הזו רלוונטית רק ללקוחות Google Workspace. חשבון שירות יכול להתחזות רק למשתמשים (כתובות אימייל) באותו Google Workspace.

דרישות מוקדמות

  • דומיין Google Workspace שבבעלותכם, כמו mydomain.com או mybusiness.com

  • קוד מפתח של Google Ads API וחשבון בדיקה (אופציונלי)

  • ספריית הלקוח בשפה שבה אתם משתמשים

  • פרויקט ב-Google API Console שהוגדרה בו תמיכה ב-Google Ads API

  • משתמש ב-Google Ads שיש לו הרשאות בחשבון Google Ads שאליו רוצים לגשת. מערכת Google Ads לא תומכת בשימוש בחשבונות שירות ללא התחזות.

הגדרת הגישה לחשבון השירות

מאחר שהשליטה בהתחזות למשתמשים מתבצעת רק ברמת הדומיין, כדי להשתמש בחשבונות שירות ובתהליך טענת הנכוֹנוּת (assertion) עם Google OAuth 2.0 צריך דומיין משלכם שמירשם ב-Google Workspace. לאחר מכן, האפליקציה והמשתמשים שלה יוכלו להתחזות לכל משתמש בדומיין.

  1. קודם צריך ליצור חשבון שירות ופרטי כניסה.

    מורידים את המפתח של חשבון השירות בפורמט JSON ומתעדים את מזהה חשבון השירות.

  2. משתפים את מזהה חשבון השירות ואת ההיקף של Google Ads API (https://www.googleapis.com/auth/adwords) עם האדמין של הדומיין.

    מבקשים מהאדמין של הדומיין להעניק לחשבון השירות הרשאה ברמת הדומיין.

  3. אם אתם מנהלי הדומיין, עליכם לפעול לפי ההוראות במרכז העזרה.

עכשיו אפשר להשתמש בחשבון השירות כדי לגשת לחשבון Google Ads באמצעות תהליך טענת הנכוֹנוּת (assertion) של OAuth 2.0.

הגדרת ספריית הלקוח

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

Java

מגדירים את הנתיב של קובץ ה-JSON של המפתח הפרטי ומזהה החשבון להענקת גישה בהגדרות. אם אתם משתמשים בקובץ ads.properties, מוסיפים את הפרטים הבאים:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

פרטים נוספים זמינים במדריך להגדרה.

‎.NET

מגדירים את המפתחות הבאים ב-App.config / Web.config. פרטים נוספים זמינים במדריך להגדרה.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

מגדירים את נתיב ה-JSON של המפתח הפרטי ואת האימייל שעבורו מתבצעת התחזות בהגדרות. אם משתמשים ב-google-ads.yaml file, במחרוזת YAML או ב-dict, מוסיפים את הקוד הבא:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

אם אתם משתמשים במשתני סביבה, מוסיפים את הפרטים הבאים לתצורה או לסביבה של Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

מגדירים את המפתחות הבאים ב-google_ads_php.ini. פרטים נוספים זמינים במדריך להגדרה.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

מגדירים את המפתחות הבאים ב-google_ads_config.rb.

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

מגדירים את הנתיב של קובץ ה-JSON של המפתח הפרטי ואת מזהה החשבון להענקת גישה בהגדרות. אם משתמשים בקובץ googleads.properties, מוסיפים את הקוד הבא:

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

אם אתם משתמשים במשתני סביבה, מוסיפים את הפרטים הבאים לתצורה או לסביבה של Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

חששות לגבי אבטחה

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

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