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

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

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

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

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

GoogleAdsClient client = new GoogleAdsClient(config);

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

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

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

הגדרה באמצעות 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=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

    <!-- OAuth2 settings -->
    <add key = "OAuth2Mode" value="APPLICATION"/>
    <add key = "OAuth2ClientId" value = "******.apps.googleusercontent.com" />
    <add key = "OAuth2ClientSecret" value = "******" />
    <add key = "OAuth2RefreshToken" value = "******" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.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, ומעבירים את הצומת של התצורה מה-App.config לקובץ הבא:

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

שלב 3: תיקון כללי ה-build ב-csproj

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

עכשיו אפשר ליצור ולהפעיל את הפרויקט. האפליקציה תתחיל לאסוף ערכים מקובץ התצורה החדש.

הגדרה באמצעות קובץ JSON בהתאמה אישית

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

יצירת קובץ JSON

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

{
    "Timeout": "2000",

    "ProxyServer": "http://localhost:8888",
    "ProxyUser": "",
    "ProxyPassword": "",
    "ProxyDomain": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

טעינת התצורה

בשלב הבא, טוענים את קובץ ה-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":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

בשלב הבא אפשר להשתמש במופע IConfiguration בדף:

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

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

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

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

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

שדות ההגדרה

בהמשך מופיעה רשימת ההגדרות שנתמכות על ידי ספריית .NET של Google Ads.

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

  • 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.

צריך לשנות את ההגדרות של MaxReceiveMessageLengthInBytes ו-MaxMetadataSizeInBytes כדי לתקן שגיאות ResourceExhausted מסוימות. ההגדרות האלה מטפלות בשגיאות בטופס Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

בדוגמה הזו, השגיאה נובעת מכך שההודעה (423184132 bytes) גדולה יותר ממה שהספרייה יכולה לטפל בה (67108864 bytes). כדי להימנע מהשגיאה הזו, צריך להגדיל את הערך MaxReceiveMessageLengthInBytes ל-500000000.

שימו לב שהבעיה גם מציינת שהקוד טיפל באובייקט תגובה גדול במיוחד (כמו SearchGoogleAdsResponse). יכולות להיות לכך השלכות על הביצועים של הקוד בגלל ה-Heap (Heap) גדול של אובייקט ב- .NET. אם זה מתעורר בעיה בביצועים, יכול להיות שתצטרכו לבדוק איך לארגן מחדש את הקריאות ל-API או לעצב מחדש חלקים באפליקציה.

הגדרות OAuth2

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

  • AuthorizationMethod: מוגדר ל-OAuth2.
  • OAuth2Mode: מוגדר ל-APPLICATION או ל-SERVICE_ACCOUNT.
  • OAuth2ClientId: מגדירים את הערך הזה למזהה הלקוח ב-OAuth2.
  • OAuth2ClientSecret: מגדירים את הערך הזה כסוד הלקוח ב-OAuth2.
  • OAuth2Scope: צריך להגדיר את הערך הזה להיקפים שונים אם רוצים לאשר אסימוני OAuth2 לכמה ממשקי API. ההגדרה הזו היא אופציונלית.

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

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

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

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

  • OAuth2PrnEmail: מגדירים את הערך הזה לכתובת האימייל של החשבון שאליו רוצים להתחזות.
  • OAuth2SecretsJsonPath: מגדירים את הערך הזה לנתיב הקובץ של תצורת OAuth2 JSON.

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

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

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

הגדרות Google Ads API

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

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