תצורה

אזהרה: החל מגרסה 19.0.0, ספריית הלקוח של Google Ads API ל-‎ .NET כבר לא תתמוך ב-‎ .NET 5.0. כדי להבטיח תפעול חלק, מומלץ מאוד לשדרג את גרסת ה-NET .‎ לפני סוף שנת 2024.

ספריית הלקוח של 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, צריך להפעיל את השיטה 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

לבסוף, כוללים את קובץ התצורה החדש בפרויקט. משנים את המאפיינים של הקובץ הזה ל-Always copy to output folder.

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

הגדרה באמצעות קובץ 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: מגדירים את השדה הזה לכתובת ה-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.

שימו לב שהשגיאה מציינת גם שהקוד שלכם טיפל באובייקט Response גדול במיוחד (למשל SearchGoogleAdsResponse גדול). לכך יכולות להיות השלכות על הביצועים של הקוד בגלל Large Object 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. ההגדרה הזו היא אופציונלית.

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

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

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