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

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

חסרונות

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

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

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

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

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. נכנסים בתור המשתמש שבחרתם בשלבים הקודמים ומאמתים את הזהות באמצעות מפתח גישה. אם האפליקציה לא מאומתת, יכול להיות שיופיע מסך אזהרה. במקרים כאלה, אפשר ללחוץ על הקישור Advanced ואז על האפשרות Go to PROJECT_NAME (unsafe).

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"
}