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

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

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

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

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

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

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

GoogleAdsClient client = new GoogleAdsClient(config);

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

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

אם אתם משתמשים באחת מהאפשרויות האלה, הגדרות התצורה לא נטענות באופן אוטומטי. צריך לטעון אותן באופן מפורש, כמו שמוסבר בקטעים הבאים. חשוב לטפל בחריגות קלט/פלט של קבצים (כמו FileNotFoundException או UnauthorizedAccessException) כשאתם טוענים הגדרות מקבצים או מסטרימינג חיצוניים.

שימוש ב-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="" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

כדי לטעון הגדרות מקובץ App.config, צריך להפעיל את ה-method‏ LoadFromDefaultAppConfigSection באובייקט GoogleAdsConfig:

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

ציון קובץ תצורה נפרד

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

מציינים 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>

מציינים את התוכן של קובץ התצורה. יוצרים קובץ תצורה נוסף עם השם שציינתם ב-configSource (GoogleAdsApi.config), ומעבירים את צומת התצורה GoogleAdsApi מהקובץ App.config לקובץ הזה:
```
<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  
</GoogleAdsApi>
```
מעדכנים את כללי ה-build בקובץ .csproj. מוסיפים את קובץ התצורה החדש לפרויקט ומגדירים את המאפיין Copy to Output Directory שלו ל-Copy always. בונים מחדש את הפרויקט ומריצים אותו כדי שהאפליקציה תשתמש בערכים מקובץ התצורה החדש.

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

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

יצירת קובץ JSON

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

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

טעינת ההגדרות

לאחר מכן, טוענים את קובץ ה-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": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

לאחר מכן, מחלצים את הקטע GoogleAdsApi מהמופע IConfiguration של האפליקציה (לדוגמה, מוזרק על ידי ASP.NET Core או נוצר באמצעות ConfigurationBuilder):

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

אפשרות אחרת היא לטעון קובץ settings.json ישירות לפי נתיב באמצעות config.LoadFromSettingsJson(filePath, "GoogleAdsApi"), או ממשתנה הסביבה GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) באמצעות config.TryLoadFromEnvironmentFilePath.

שימוש במשתני סביבה

אפשר גם לאתחל את 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 and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

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: אם שרת ה-proxy דורש הגדרה של דומיין, מגדירים את הדומיין של 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

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

‫AuthorizationMethod: מוגדר ל-OAuth2.
‫OAuth2Mode: מוגדר לערך APPLICATION או SERVICE_ACCOUNT.
‫OAuth2ClientId: מגדירים את הערך הזה למזהה הלקוח של OAuth 2.0.
‫OAuth2ClientSecret: מגדירים את הערך הזה לסוד הלקוח של OAuth 2.0.
‫OAuth2Scope: אם רוצים לאשר אסימוני OAuth 2.0 למספר ממשקי API, צריך להגדיר ערכים שונים להיקפי ההרשאות. ההגדרה הזו היא אופציונלית.
‫UseApplicationDefaultCredentials: צריך להגדיר את הערך הזה ל-true כדי לבצע אימות באמצעות Application Default Credentials (נתמך ב-Google.Ads.GoogleAds v24.1.0 ואילך; config.LoadFromEnvironmentVariables() קורא את משתנה הסביבה USE_APPLICATION_DEFAULT_CREDENTIALS ללא קידומת).
‫Credentials: (זמן ריצה בלבד, נתמך בגרסה v27.0.0 ואילך) הוספת מופע של ICredential או GoogleCredential שנבנה מראש ישירות ל-GoogleAdsConfig בזמן ריצה.

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

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

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

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

OAuth2SecretsJsonPath: מגדירים את הערך הזה לנתיב של קובץ המפתח של OAuth 2.0 JSON.
‫OAuth2PrnEmail: מגדירים את הערך הזה לכתובת האימייל של החשבון שמתחזים אליו כשמשתמשים בהענקת גישה ברמת הדומיין ב-Google Workspace. ההגדרה הזו היא אופציונלית.

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

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

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

הגדרות Google Ads API

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

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