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

במדריך הזה מוסבר איך לגשת ל-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 הנדרשת. זוהי אמצעי מנע שנועד להגביל את כמות הנתונים שאפשר לתקוף אם קובץ המפתח של חשבון השירות נפרץ.