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

הערה: המדריך הזה מתבסס על ההנחה שאתם מכירים את מודל הגישה של Google Ads. אם לא, מומלץ לקרוא את המדריך בנושא מודל הגישה של Google Ads כדי להכיר את המושגים. כדי ש-Google Ads API יפעל כמו שצריך, צריך גם להגדיר את פרטי הכניסה ל-OAuth באמצעות אותו פרויקט בענן ב-Google Cloud שבו הפעלתם את Google Ads API וביקשתם רמת גישה מתאימה ל-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 הוא אפליקציה למחשב, כי היא פועלת הכי טוב עם ה-CLI של gcloud. כשמשתמשים בתהליך אימות של משתמש יחיד, אפשר להשתמש בסוג הזה של אפליקציית OAuth בלי קשר לסוג האפליקציה שאתם יוצרים. אם בוחרים באפשרות Web application (אפליקציית אינטרנט), צריך להשתמש ב-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, ולא בפרויקט ברירת המחדל של ה-CLI של gcloud:

   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. אחרי שמאמתים את היקפי ההרשאות, לוחצים על הכפתור Continue כדי לתת הרשאה. הדפדפן עובר לכתובת 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"
   }
   

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

בוחרים את הכרטיסייה שמתאימה לשפת התכנות כדי לקבל הוראות להגדרת ספריית הלקוח. אם המשתמש המורשה שלכם ניגש לחשבונות לקוח דרך חשבון ניהול ב-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/v26/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"
}