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

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

הגדרת הספרייה בזמן הריצה

הדרך המועדפת להגדיר את ספריית הלקוח היא לאתחל אובייקט GoogleAdsConfig בזמן הריצה:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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

הספרייה מספקת גם אפשרויות נוספות לטעינת הגדרות התצורה. כדי להפעיל אותם, מוסיפים הפניה ל-NuGet אל חבילת Google.Ads.GoogleAds.Extensions בפרויקט.

אם משתמשים באחת מהאפשרויות האלה, הגדרות התצורה לא נטענות אוטומטית. צריך לטעון אותן באופן מפורש כמו שמוסבר בקטעים הבאים. חשוב לטפל בחריגות של קלט/פלט של קבצים (כמו FileNotFoundException או UnauthorizedAccessException) כשמעלים הגדרות מקבצים או מזרמים חיצוניים.

שימוש בקובץ App.config

כל ההגדרות שספציפיות ל-Google Ads API מאוחסנות בצומת GoogleAdsApi של הקובץ App.config. הגדרות אופייניות App.config נראות כך:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

כדי לטעון הגדרות מקובץ App.config, קוראים ל-method‏ LoadFromDefaultAppConfigSection באובייקט GoogleAdsConfig:

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

ציון קובץ App.config נפרד

אם אתם לא רוצים שהספרייה App.config תהיה עמוסה מדי, אתם יכולים להעביר את ההגדרות הספציפיות לספרייה לקובץ הגדרות משלה באמצעות המאפיין configSource:

1. מציינים configSource בApp.config. משנים את קובץ App.config כדי שיפנה לקובץ תצורה חיצוני:

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
     </configSections>
     <GoogleAdsApi configSource="GoogleAdsApi.config" />
   </configuration>
   

2. מציינים את התוכן של קובץ התצורה. יוצרים קובץ תצורה נוסף עם השם שציינתם ב-configSource (GoogleAdsApi.config), ומעבירים את צומת התצורה GoogleAdsApi מהקובץ App.config לקובץ הזה:

   <?xml version="1.0" encoding="utf-8" ?>
   <GoogleAdsApi>
     <!-- More settings. -->
   </GoogleAdsApi>
   

3. מעדכנים את כללי הבנייה ב-.csproj. כוללים את קובץ ההגדרות החדש בפרויקט ומגדירים את המאפיין העתקה לספריית הפלט שלו לערך העתקה תמיד. מבצעים build מחדש של הפרויקט ומריצים אותו כדי שהאפליקציה תאחזר ערכים מקובץ ההגדרות החדש.

שימוש בקובץ JSON בהתאמה אישית

אפשר להשתמש במופע IConfigurationRoot כדי להגדיר את ספריית הלקוח.

יצירת קובץ JSON

יוצרים קובץ JSON בשם GoogleAdsApi.json עם מבנה דומה לקובץ App.config:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

טעינת ההגדרות

לאחר מכן, טוענים את קובץ ה-JSON לתוך IConfigurationRoot:

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

שימוש בקובץ settings.json

התהליך כאן דומה לשימוש בקובץ JSON מותאם אישית, אלא שהמפתחות צריכים להיות בתוך קטע בשם GoogleAdsApi:

{
  "GoogleAdsApi": {
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

לאחר מכן, מחלצים את הקטע GoogleAdsApi מהמופע IConfiguration של האפליקציה (לדוגמה, מוזרק על ידי ASP.NET Core או נוצר באמצעות ConfigurationBuilder):

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

אפשרות אחרת היא לטעון קובץ settings.json ישירות לפי נתיב באמצעות config.LoadFromSettingsJson(filePath, "GoogleAdsApi"), או ממשתנה הסביבה GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) באמצעות config.TryLoadFromEnvironmentFilePath.

שימוש במשתני סביבה

אפשר גם לאתחל את GoogleAdsClient באמצעות משתני סביבה:

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

הערה: ערך ברירת המחדל של GoogleAdsConfig.OAuth2Mode הוא APPLICATION, לכן כשמבצעים אימות באמצעות חשבון שירות באמצעות GOOGLE_ADS_JSON_KEY_FILE_PATH, חשוב להגדיר גם את GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT.

הרשימה המלאה של משתני הסביבה הנתמכים

שימוש בזרם כללי

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

שדות הגדרה

בקטעים הבאים מפורטות ההגדרות שנתמכות בספריית Google Ads .NET.

הגדרות הקישוריות

• ‫Timeout: משתמשים במפתח הזה כדי להגדיר את פסק הזמן של השירות באלפיות השנייה. ערך ברירת המחדל מוגדר על סמך ההגדרה method_config/timeout ב-googleads_grpc_service_config.json. אם רוצים להגביל את הזמן המקסימלי לקריאה ל-API, צריך להגדיר ערך נמוך יותר. אפשר להגדיר את הזמן הקצוב לתפוגה לשעתיים או יותר, אבל יכול להיות שה-API עדיין יגרום לפסק זמן בבקשות שפועלות זמן רב מאוד ויחזיר שגיאה DEADLINE_EXCEEDED.
• ‫ProxyServer: מגדירים את כתובת ה-URL של שרת ה-proxy של HTTP אם משתמשים ב-proxy כדי להתחבר לאינטרנט.
• ‫ProxyUser: מגדירים את שם המשתמש שנדרש לאימות מול שרת ה-proxy. אם לא נדרש שם משתמש, משאירים את השדה הזה ריק.
• ‫ProxyPassword: אם הגדרתם ערך לפרמטר ProxyUser, צריך להגדיר כאן את הסיסמה של ProxyUser.
• ‫ProxyDomain: מגדירים את זה לדומיין של ProxyUser אם שרת ה-proxy דורש הגדרה כזו.
• ‫MaxReceiveMessageLengthInBytes: משתמשים בהגדרה הזו כדי להגדיל את הגודל המקסימלי של תגובת ה-API שספריית הלקוח יכולה לטפל בה. ערך ברירת המחדל הוא 64MB.
• ‫MaxMetadataSizeInBytes: משתמשים בהגדרה הזו כדי להגדיל את הגודל המקסימלי של תגובת השגיאה של ה-API שספריית הלקוח יכולה לטפל בה. ערך ברירת המחדל הוא 16MB.

כדי לתקן שגיאות מסוימות של ResourceExhausted, משנים את ההגדרות של MaxReceiveMessageLengthInBytes ושל MaxMetadataSizeInBytes. ההגדרות האלה מתייחסות לשגיאות מהסוג הבא:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

בדוגמה הזו, השגיאה נובעת מגודל ההודעה (423184132 bytes) שהוא גדול יותר ממה שהספרייה יכולה לטפל בו (67108864 bytes). כדי להימנע מהשגיאה הזו, צריך להגדיל את MaxReceiveMessageLengthInBytes ל-500000000. הערה: השגיאה מציינת גם שהקוד טיפל באובייקט תגובה גדול במיוחד (כמו SearchGoogleAdsResponse גדול). יכולות להיות לכך השלכות על הביצועים של הקוד בגלל Large Object Heap של ‎ .NET. אם זה משפיע על הביצועים, יכול להיות שתצטרכו לבדוק איך לארגן מחדש את הקריאות ל-API או לעצב מחדש חלקים מהאפליקציה.

הגדרות OAuth2

כשמשתמשים ב-OAuth 2.0 כדי להעניק הרשאה לקריאות לשרתי Google Ads API, צריך להגדיר את מפתחות ההגדרה הבאים:

• ‫AuthorizationMethod: מוגדר ל-OAuth2.
• ‫OAuth2Mode: מוגדר לערך APPLICATION או SERVICE_ACCOUNT.
• ‫OAuth2ClientId: מגדירים את הערך הזה למזהה הלקוח של OAuth 2.0.
• ‫OAuth2ClientSecret: מגדירים את הערך הזה לסוד הלקוח של OAuth 2.0.
• ‫OAuth2Scope: אם רוצים לאשר אסימוני OAuth 2.0 למספר ממשקי API, צריך להגדיר ערכים שונים להיקפי ההרשאות. ההגדרה הזו היא אופציונלית.
• ‫UseApplicationDefaultCredentials: מגדירים את הערך הזה ל-true כדי לבצע אימות באמצעות Application Default Credentials (נתמך ב-Google.Ads.GoogleAds v24.1.0 ואילך; config.LoadFromEnvironmentVariables() קורא את משתנה הסביבה USE_APPLICATION_DEFAULT_CREDENTIALS ללא הקידומת).
• ‫Credentials: (זמן ריצה בלבד, נתמך ב-v27.0.0 ואילך) הוספת מופע של ICredential או GoogleCredential שנבנה מראש ישירות ל-GoogleAdsConfig בזמן הריצה.

אם אתם משתמשים ב-OAuth2Mode == APPLICATION, אתם צריכים להגדיר את מפתחות ההגדרה הנוספים הבאים:

• ‫OAuth2RefreshToken: אם רוצים לעשות שימוש חוזר באסימוני OAuth 2.0, צריך להגדיר את הערך הזה לאסימון רענון מסוג OAuth 2.0 שנוצר מראש. ההגדרה הזו היא אופציונלית.
• ‫OAuth2RedirectUri: מגדירים את הערך הזה לכתובת ה-URL להפניה אוטומטית של OAuth 2.0. ההגדרה הזו היא אופציונלית.

פרטים נוספים מופיעים במדריכים הבאים:

• תהליך הרשאה של אפליקציית OAuth למחשב
• תהליך הרשאה של אפליקציית אינטרנט באמצעות OAuth

אם אתם משתמשים ב-OAuth2Mode == SERVICE_ACCOUNT, אתם צריכים להגדיר את מפתחות התצורה הנוספים הבאים:

• ‫OAuth2SecretsJsonPath: מגדירים את הערך הזה לנתיב של קובץ מפתח ה-JSON של OAuth 2.0.
• ‫OAuth2PrnEmail: מגדירים את הערך הזה לכתובת האימייל של החשבון שאתם מתחזים לו כשאתם משתמשים בהענקת גישה ברמת הדומיין ב-Google Workspace. ההגדרה הזו היא אופציונלית.

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

הגדרות תחבורה

• ‫UseGrpcCore: מגדירים את ההגדרה הזו ל-true כדי להשתמש בספרייה Grpc.Core כשכבת התעבורה הבסיסית. איך משתמשים בספרייה של Grpc.Core

הגדרות Google Ads API

ההגדרות הבאות ספציפיות ל-Google Ads API:

• ‫LoginCustomerId: זהו מספר הלקוח של הלקוח המורשה לשימוש בבקשה, ללא מקפים (-).
• ‫LinkedCustomerId: הכותרת הזו נדרשת רק לשיטות שמעדכנות את המשאבים של ישות כשההרשאה ניתנת דרך חשבונות מקושרים בממשק המשתמש של Google Ads (משאב AccountLink ב-Google Ads API). הערך הזה צריך להיות מוגדר כמזהה הלקוח של ספק הנתונים שמעדכן את המשאבים של מזהה הלקוח שצוין. צריך להגדיר אותו בלי מקפים (-). מידע נוסף על חשבונות מקושרים