אימות והרשאה

כמו ממשקי Google API אחרים, Google Ads API משתמש בפרוטוקול OAuth 2.0 לאימות ולהרשאה. פרוטוקול OAuth 2.0 מאפשר לאפליקציית הלקוח של Google Ads API ב-‎ .NET לגשת לחשבון Google Ads של המשתמש בלי לטפל בפרטי ההתחברות של המשתמש או לאחסן אותם.

הסבר על מודל הגישה של Google Ads

כדי לעבוד ביעילות עם Google Ads API, חשוב להבין איך פועל מודל הגישה של Google Ads. מדריך למודל הגישה של Google Ads

תהליכי עבודה של OAuth

יש שלושה תהליכי עבודה נפוצים כשעובדים עם Google Ads API.

תהליך של חשבון שירות

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

מגדירים את הספרייה באופן הבא:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

למידע נוסף, קראו את המדריך לתהליך העבודה של חשבון שירות.

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

אפשר להשתמש בתהליך העבודה הזה אם אתם לא יכולים להשתמש בחשבונות שירות. תהליך העבודה הזה דורש שני שלבי הגדרה:

1. לתת למשתמש אחד גישה לכל החשבונות שצריך לנהל באמצעות Google Ads API. גישה נפוצה היא לתת למשתמש גישה לחשבון ניהול ב-Google Ads API, ולקשר את כל חשבונות Google Ads לחשבון הניהול הזה.
2. המשתמש מפעיל כלי שורת פקודה כמו gcloud או דוגמת הקוד של GenerateUserCredentials כדי לתת לאפליקציה הרשאה לנהל את כל חשבונות Google Ads שלו בשמו.

מפעילים את הספרייה באמצעות פרטי הכניסה של המשתמש ב-OAuth 2.0 באופן הבא:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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

תהליך אימות של משתמשים מרובים

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

החל מגרסה Google.Ads.GoogleAds v27.0.0, אפשר גם להוסיף אובייקט ICredential או GoogleCredential שהוגדר מראש ישירות אל GoogleAdsConfig באמצעות המאפיין Credentials.

מידע נוסף זמין במדריך לתהליך העבודה של אימות משתמשים מרובים. ספריית הלקוח של ‎ .NET כוללת שתי דוגמאות קוד לעיון:

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

מה קורה אם המשתמש שלי מנהל כמה חשבונות?

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

1. בדוגמת הקוד של GetAccountHierarchy מוסבר איך לאחזר את רשימת כל החשבונות שמשויכים לחשבון ניהול ב-Google Ads.
2. דוגמת הקוד של ListAccessibleCustomers מראה איך לאחזר את רשימת כל החשבונות שלמשתמש יש גישה ישירה אליהם. אפשר להשתמש בחשבונות האלה כערכים תקינים להגדרה LoginCustomerId.

Application Default Credentials

ספריית הלקוח של ‎ .NET (גרסה v24.1.0 ואילך) תומכת גם באימות באמצעות Application Default Credentials.

האפשרות הזו שימושית במיוחד לפיתוח מקומי או לפיתוח מול ממשקי Google API שונים, כי אפשר להשתמש שוב באותם פרטי כניסה, בתנאי שהם יכולים לגשת להיקפי ההרשאות הנדרשים של OAuth 2.0.

ב-Google Ads API, ודאו של-Application Default Credentials יש גישה להיקף ההרשאות של OAuth 2.0 ב-https://www.googleapis.com/auth/adwords.

כדי להשתמש ב-Application Default Credentials, מגדירים את האפשרות UseApplicationDefaultCredentials לערך true ב-GoogleAdsConfig (או מגדירים את משתנה הסביבה USE_APPLICATION_DEFAULT_CREDENTIALS=true כשמגדירים את התצורה באמצעות config.LoadFromEnvironmentVariables()):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

בדף ההגדרות מפורטות האפשרויות הזמינות להגדרת ספריית הלקוח של ‎ .NET.