אפשרויות הגדרה

ספריית הלקוח של Google Ads API ל-PHP כוללת כמה הגדרות אישיות שמאפשרות להתאים אישית את אופן הפעולה של הספרייה.

קובץ תצורה

אתם יכולים לאחסן את רוב הגדרות התצורה האלה בקובצי תצורה מסוג INI ולהשתמש בהן כשאתם יוצרים לקוחות, לדוגמה, google_ads_php.ini.

גם ב-credential builder וגם ב-client builder יש שיטות fromFile לטעינת הגדרות מקבצים כאלה:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

אם לא צוין נתיב הגדרה כארגומנט, השיטות של fromFile נטענות מנתיב ההגדרה שמוגדר כברירת מחדל:

1. הערך של משתנה הסביבה שנקרא GOOGLE_ADS_CONFIGURATION_FILE_PATH, אם הוא מוגדר.
2. אם לא, הקובץ google_ads_php.ini בספרייה HOME.

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

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

הגדרה דינמית

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

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

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

משתני סביבה של הגדרות אישיות

אתם יכולים להגדיר חלק מההגדרות האישיות ממשתני סביבה כשאתם יוצרים מופעים של לקוחות (ראו משתני סביבה סטנדרטיים).

גם ב-credential builder וגם ב-client builder יש שיטות fromEnvironmentVariables לטעינת הגדרות ממשתני סביבה.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

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

שדות תצורה

הגדרות התצורה תומכות בכמה שדות שמסודרים בקטגוריות:

1. שדות שמשמשים את OAuth2TokenBuilder:
   • מצב אפליקציה:
     • ‫[OAUTH2] clientId: מזהה הלקוח ב-OAuth2.
     • ‫[OAUTH2] clientSecret: סוד הלקוח ב-OAuth2.
     • ‫[OAUTH2] refreshToken: טוקן הרענון של OAuth2.
   • מצב חשבון שירות:
     • ‫[OAUTH2] jsonKeyFilePath: הנתיב של מפתח ה-JSON.
     • ‫[OAUTH2] scopes: היקפי ההרשאות של OAuth2 (ברירת המחדל היא https://www.googleapis.com/auth/adwords בגרסה v32.1.0 ואילך; נדרש בגרסאות שקדמו ל-v32.1.0 או כשמשתמשים בהיקפי הרשאות בהתאמה אישית; לא נקרא ממשתנה סביבה על ידי fromEnvironmentVariables()).
     • ‫[OAUTH2] impersonatedEmail: כתובת אימייל אופציונלית להתחזות כשמשתמשים בהקצאת הרשאות ברמת הדומיין ב-Google Workspace.
   • מצב Application Default Credentials:
     • אם לא מגדירים את השדות של מצב האפליקציה או של מצב חשבון השירות, OAuth2TokenBuilder חוזר באופן אוטומטי ל-Application Default Credentials (‏ADC).
2. שדות שמשמשים את GoogleAdsClientBuilder:
   • ‫[GOOGLE_ADS] loginCustomerId: המזהה של הלקוח המורשה שבו צריך להשתמש בבקשה.
   • ‫[GOOGLE_ADS] linkedCustomerId: מספר הלקוח המקושר.
   • ‫[GOOGLE_ADS] endpoint: נקודת קצה חלופית אופציונלית של שרת Google Ads API.
   • ‫[LOGGING] logFilePath: הנתיב לפלט של רישום ביומן.
   • ‫[LOGGING] logLevel: רמת הרישום ביומן.
   • ‫[CONNECTION] proxy: כתובת ה-URL של שרת ה-proxy שמשמש לחיבור לאינטרנט.
   • ‫[CONNECTION] transport: פרוטוקול התעבורה ברשת (grpc או rest).
   • ‫[CONNECTION] grpcChannelIsSecure: אם ערוץ ה-gRPC מאובטח.
   • ‫[CONNECTION] grpcChannelCredential: פרטי הכניסה לערוץ gRPC.
   • ‫[CONNECTION] unaryMiddlewares: תוכנות הביניים החד-ערכיות.
   • ‫[CONNECTION] streamingMiddlewares: תוכנות הביניים של הסטרימינג.
   • ‫[CONNECTION] grpcInterceptors: רכיבי ה-interceptor של gRPC.

אימות ההגדרות האישיות

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

1. אסור להגדיר את השדות של [OAUTH2] גם למצב אפליקציה וגם למצב חשבון שירות בו-זמנית.
2. צריך להגדיר את [OAUTH2] jsonKeyFilePath כשמשתמשים במצב חשבון שירות (בגרסאות שקודמות ל-v32.1.0, צריך להגדיר גם את [OAUTH2] scopes. בגרסה v32.1.0 ואילך, ברירת המחדל של scopes היא https://www.googleapis.com/auth/adwords).
3. כשמשתמשים במצב אפליקציה, צריך להגדיר את [OAUTH2] clientId, [OAUTH2] clientSecret ו-[OAUTH2] refreshToken.
4. אם מגדירים את [GOOGLE_ADS] loginCustomerId ו-[GOOGLE_ADS] linkedCustomerId, הם חייבים להיות מספרים חיוביים.
5. אם המדיניות מוגדרת, הערך של [CONNECTION] proxy חייב להיות כתובת URL תקינה (ראו המסנן FILTER_VALIDATE_URL).
6. אם מגדירים את [LOGGING] logLevel, צריך להזין רמת יומן PSR תקינה באותיות רישיות, כמו INFO.
7. אם המדיניות מוגדרת, הערך של [CONNECTION] transport צריך להיות grpc או rest.
8. אם [CONNECTION] transport מוגדר ל-grpc, הסביבה חייבת לתמוך בהעברת gRPC (ראו מדריך ההעברה).
9. הערך של [CONNECTION] grpcChannelIsSecure חייב להיות true כשלא מגדירים את [CONNECTION] transport כ-grpc (חיבורי REST תמיד דורשים HTTPS).
10. אפשר להגדיר את [CONNECTION] grpcChannelCredential רק כש-[CONNECTION] transport מוגדר כ-grpc.
11. אפשר להגדיר את [CONNECTION] grpcChannelCredential רק אם [CONNECTION] grpcChannelIsSecure הוא true.