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

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "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);

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

שדות הגדרה

בהמשך מופיעה רשימת ההגדרות שנתמכות על ידי ספריית 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: מגדירים את הערך הזה לדומיין של 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). עלולות להיות לכך השלכות על הביצועים של הקוד בגלל Leap של .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). צריך להגדיר את הערך הזה למספר הלקוח של ספק הנתונים כדי לעדכן את המשאבים של מספר הלקוח שצוין. צריך להגדיר אותו ללא מקפים (-). מידע נוסף על חשבונות מקושרים