כדאי להצטרף אלינו לשידור חי ב-Discord בשרת של קהילת הפרסום והמדידה של Google וב-YouTube ב-20 באוגוסט בשעה 10:00 (שעון החוף המזרחי)! במאמר הזה נסביר על התכונות החדשות שנוספו לגרסה 25.1 של Google Ads API.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    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"></section>
  </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=""/>

    <!-- 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"></section>
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config"/>
...
</configuration>

שלב 2: מציינים את התוכן של קובץ ההגדרות

עכשיו יוצרים עוד קובץ הגדרות בשם שצוין ב-configSource, ומעבירים את צומת ההגדרות מקובץ App.config לקובץ הזה:

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

שלב 3: מתקנים את כללי הבנייה בקובץ ה-csproj

לבסוף, מוסיפים את קובץ ההגדרות החדש לפרויקט. משנים את המאפיינים של הקובץ לAlways copy to output folder (העתקה תמיד לתיקיית הפלט).

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

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

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

יצירת קובץ JSON

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

{
    "Timeout": "2000",

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

    "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":
    {
        "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);

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

שימוש בזרם כללי

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file.

CryptoStream strm = ....

StreamReader rdr = new StreamReader(strm);
// Configure the OAuth credentials from the encrypted file.
config.LoadOAuth2SecretsFromStream(rdr);

GoogleAdsClient client = new GoogleAdsClient(config);

שדות להגדרת התצורה

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

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

‫Timeout: משתמשים במפתח הזה כדי להגדיר את פסק הזמן של השירות באלפיות השנייה. ערך ברירת המחדל מוגדר על סמך ההגדרה method_config/timeout בקובץ googleads_grpc_service_config.json. אם אתם רוצים להגביל את הזמן המקסימלי לקריאה ל-API, אתם יכולים להגדיר ערך נמוך יותר. אפשר להגדיר את פסק הזמן ל-2 שעות או יותר, אבל יכול להיות שה-API עדיין יפסיק בקשות שפועלות זמן רב מדי ויחזיר שגיאה DEADLINE_EXCEEDED.
‫ProxyServer: אם אתם משתמשים ב-proxy כדי להתחבר לאינטרנט, צריך להגדיר את כתובת ה-URL של שרת ה-proxy של HTTP.
‫ProxyUser: מגדירים את שם המשתמש שנדרש לאימות מול שרת ה-proxy. אם לא נדרש שם משתמש, משאירים את השדה הזה ריק.
‫ProxyPassword: אם הגדרתם ערך לפרמטר ProxyUser, צריך להגדיר כאן את הסיסמה של ProxyUser.
‫ProxyDomain: מגדירים את הערך הזה לדומיין של 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

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

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

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

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

הגדרות של Google Ads API

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

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

אפשרויות הגדרה קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.