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

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

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

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

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

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

GoogleAdsClient client = new GoogleAdsClient(config);

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

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

dotnet add package Google.Ads.GoogleAds.Extensions

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

שימוש ב-appsettings.json או ב-settings.json

באפליקציות .NET 8.0 ו-ASP.NET Core, ממקמים את מפתחות ההגדרות בקטע GoogleAdsApi ב-appsettings.json (או ב-settings.json):

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

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

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

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

לחלופין, אפשר לטעון קובץ appsettings.json או settings.json ישירות לפי הנתיב באמצעות LoadFromSettingsJson:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

אפשר גם לטעון את הנתיב ממשתנה הסביבה GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) על ידי קריאה ל-config.TryLoadFromEnvironmentFilePath.

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

אפשר גם להשתמש במכונה של IConfigurationRoot כדי לטעון קובץ JSON שטוח בלי קטע GoogleAdsApi ברמה העליונה.

יצירת קובץ JSON

יוצרים קובץ JSON בשם GoogleAdsApi.json שמגדיר את מפתחות ההגדרות ברמת הבסיס:

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

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

בשלב הבא, טוענים את קובץ ה-JSON ל-IConfigurationRoot:

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

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);

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

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

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

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.

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

שימוש ב-App.config

באפליקציות .NET Framework, כל ההגדרות הספציפיות ל-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="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- 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:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(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. מעדכנים את כללי ה-build בקובץ .csproj. מוסיפים את קובץ התצורה החדש לפרויקט ומגדירים את המאפיין Copy to Output Directory שלו ל-Copy always. בונים מחדש את הפרויקט ומריצים אותו כדי שהאפליקציה תשתמש בערכים מקובץ התצורה החדש.

שימוש בשידור גנרי

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

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: אם אתם משתמשים בשרת proxy כדי להתחבר לאינטרנט, הגדירו את כתובת ה-URL של שרת ה-proxy ל-HTTP.
• ‫ProxyUser: צריך להגדיר את שם המשתמש שנדרש לאימות מול שרת ה-proxy. אם לא נדרש שם משתמש, אפשר להשאיר את השדה הזה ריק.
• ‫ProxyPassword: אם הגדרתם ערך ל-ProxyUser, הגדירו את הסיסמה של ProxyUser.
• ‫ProxyDomain: אם שרת ה-proxy דורש הגדרה של דומיין, מגדירים את הדומיין של ProxyUser.
• ‫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: מגדירים את הערך הזה לנתיב של קובץ המפתח של OAuth 2.0 JSON.
• ‫OAuth2PrnEmail: מגדירים את הערך הזה לכתובת האימייל של החשבון שאתם מתחזים אליו כשאתם משתמשים בהענקת גישה ברמת הדומיין ב-Google Workspace. ההגדרה הזו היא אופציונלית.

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

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

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

הגדרות Google Ads API

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

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