תהליך עבודה לאימות משתמש יחיד

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

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

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

• אתם מעניקים למשתמש אחד גישה לכל חשבונות Google Ads שהאפליקציה אמורה לנהל.
• המשתמש מאשר לאפליקציה שלכם לנהל את חשבונות Google Ads שלו בשמו, וכך מעניק לאפליקציה גישה לכל חשבונות Google Ads.

מכיוון שמדובר רק במשתמש אחד, אפשר להסתמך על כלים כמו CLI של gcloud או על דוגמת הקוד GenerateUserCredential במקום ליצור תהליך אימות משתמשים משלכם באמצעות OAuth 2.0.

תרחיש שימוש קשור לתהליך העבודה הזה הוא כשניתן לגשת לחשבונות שלכם באמצעות מספר קטן של התחברויות של משתמשים (לדוגמה, 3 עד 4 משתמשים), ולכן מאמץ הפיתוח לבניית תהליך עבודה מלא של אימות OAuth למשתמשים מרובים לא מוצדק בהשוואה למאמץ שנדרש כדי לקבל הרשאה ל-3 עד 4 משתמשים באמצעות כלי שורת פקודה, כמו ה-CLI של gcloud.

חסרונות

יש כמה חסרונות בתהליך הזה בהשוואה לתהליך העבודה של חשבון שירות:

1. תהליך העבודה של אימות המשתמש מחייב יצירה של מזהה לקוח וסוד לקוח ב-OAuth 2.0 במסוף Google Cloud, ולכן הוא כולל יותר שלבי הגדרה מאשר יצירה של חשבון שירות ומפתח.
2. אם המשתמש המורשה עוזב את הצוות או החברה, יכול להיות שהאפליקציה תפסיק לפעול אם תסירו את המשתמש מהחשבונות שלכם או תשביתו את חשבון המשתמש. חשבונות שירות לא מקושרים למשתמשים ספציפיים, ולכן הסיכון הזה לא קיים.
3. המשתמש שמאשר את הגישה לחשבון Google Ads צריך להפעיל מפתחות גישה בחשבון Google שלו כדי להגן על החשבון מפני פריצה בגלל אבטחה לקויה, תוכנות זדוניות או פישינג. לא צריך חשבונות שירות כדי להפעיל מפתחות גישה, והם פחות פגיעים לבעיה הזו כי חלק משיטות ההתקפה האלה לא חלות עליהם ישירות.

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

הערה: במדריך הזה משתמשים באפליקציה למחשב כסוג אפליקציית OAuth כשיוצרים את פרטי הכניסה של OAuth, כי זה עובד הכי טוב עם ה-CLI של gcloud. כשמשתמשים בתהליך אימות של משתמש יחיד, אפשר להשתמש בסוג הזה של אפליקציית OAuth בלי קשר לסוג האפליקציה שאתם יוצרים. אם בוחרים באפשרות אפליקציית אינטרנט, צריך להשתמש ב-OAuth 2.0 Playground כדי ליצור טוקן רענון. הוראות מפורטות מופיעות בסרטון.

1. מגדירים מסך הסכמה ל-OAuth לאפליקציה ומוסיפים את https://www.googleapis.com/auth/adwords כהיקף הרשאות של OAuth 2.0. פרטים נוספים מופיעים במאמר בנושא הגדרת מסך ההסכמה ל-OAuth.

2. יוצרים מזהה לקוח וסוד לקוח לפי ההוראות. אחרי שיוצרים את לקוח OAuth 2.0, מורידים את קובץ ה-JSON של הלקוח בלחיצה על הלחצן Download JSON בתיבת הדו-שיח לאישור. שומרים את הקובץ בשם credentials.json.

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

4. מורידים ומתקינים את ה-CLI של gcloud. אחרי ההתקנה, מריצים את הפקודה gcloud version משורת הפקודה כדי לוודא שהכלי פועל בצורה תקינה. הפלט אמור להיראות כך:

   gcloud version

   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   

5. מריצים את כלי ה-CLI של gcloud עם הקובץ credentials.json מהשלב הקודם כדי ליצור אסימון רענון ל-OAuth 2.0. חובה להעביר את --client-id-file כדי שטוקן הרענון יונפק במסגרת הפרויקט שלכם ב-Google API Console ולא במסגרת פרויקט ברירת המחדל של gcloud CLI:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CREDENTIALS_JSON

6. הפקודה gcloud פותחת חלון כניסה לחשבון Google בחלון דפדפן חדש, ומנחה אתכם בתהליך האימות של OAuth 2.0. חשוב להיכנס לחשבון של המשתמש שבחרתם בשלבים הקודמים. אם האפליקציה לא מאומתת, יכול להיות שיוצג מסך אזהרה. במקרים כאלה, אפשר ללחוץ על הקישור מתקדם ואז על האפשרות מעבר אל PROJECT_NAME (לא בטוח).

7. אחרי שמאמתים את היקפי ההרשאות, לוחצים על הלחצן המשך כדי להעניק הרשאה. הדפדפן עובר אל https://cloud.google.com/sdk/auth_success, מה שמצביע על כך שהאימות בוצע בהצלחה. בדף מוצגת ההודעה הבאה:

   Authorization code granted. Close this tab.

   הפקודה gcloud מדפיסה את ההודעה הבאה:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
   

   פותחים את הקובץ application_default_credentials.json. התוכן שלה אמור להיראות כך:

   {
     "account": "",
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "refresh_token": "******",
     "type": "authorized_user",
     "universe_domain": "googleapis.com"
   }
   

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

בוחרים את הכרטיסייה שמתאימה לשפת התכנות כדי לקבל הוראות להגדרת ספריית הלקוח. אם המשתמש המורשה שלכם ניגש לחשבונות לקוח דרך חשבון ניהול (MCC) ב-Google Ads, צריך להגדיר את login-customer-id (או loginCustomerId) למזהה הלקוח בן 10 הספרות של חשבון הניהול הזה, ללא מקפים.

Java

מגדירים את המפתחות הבאים בקובץ ads.properties.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

אפשרויות נוספות זמינות במדריך ההגדרה.

‎.NET

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

אפשרויות נוספות זמינות במדריך ההגדרה.

Python

מגדירים את המפתחות הבאים בקובץ google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

אפשרויות נוספות זמינות במדריך ההגדרה.

PHP

מגדירים את המפתחות הבאים ב-google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

אפשרויות נוספות זמינות במדריך ההגדרה.

Ruby

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

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

אפשרויות נוספות זמינות במדריך ההגדרה.

Perl

מגדירים את המפתחות הבאים בקובץ googleads.properties.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

אפשרויות נוספות זמינות במדריך ההגדרה.

curl

מתחילים בשימוש בלקוח HTTP כדי לאחזר אסימון גישה מסוג OAuth 2.0. במדריך הזה נעשה שימוש בפקודה curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://oauth2.googleapis.com/token

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

curl -i -X POST \
  https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

התוכן של query.json הוא:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}