Authentication

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

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

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

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

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

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

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

כך מגדירים את ספריית ה-PHP:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

מידע נוסף מופיע במדריך לתהליך העבודה עם חשבונות שירות.

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

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

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

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

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

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

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

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

במדריך לתהליך העבודה של אימות משתמשים מרובים מפורט מידע נוסף.

Application Default Credentials

ספריית הלקוח של PHP תומכת גם באימות באמצעות Application Default Credentials ‏ (ADC). כשלא מוגדרים ב-OAuth2TokenBuilder פרטי כניסה במצב אפליקציה (clientId, ‏ clientSecret, ‏ refreshToken) או במצב חשבון שירות (jsonKeyFilePath), הקריאה ל-build() חוזרת באופן אוטומטי ל-Application Default Credentials:

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

ניהול חשבונות מרובים

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

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