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

ספריית הלקוח של 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

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

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

הגדרה באמצעות קובץ 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). הזה עשויות להיות השלכות על הביצועים של הקוד עקב אובייקט גדול של .NET ערימה (heap). אם כל זה יפגע בביצועים, אולי יהיה צורך לבדוק איך לארגן מחדש את הקריאות ל-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: הגדרת הערך הזה בהגדרת ה-JSON של OAuth2 נתיב לקובץ.

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

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

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

הגדרות Google Ads API

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

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