הגדרת רישום ביומן

ספריית הלקוח של ‎ .NET רושמת ביומן בקשות, תגובות והודעות סיכום שנשלחות אל Google Ads API. אפשר לכתוב את היומנים ל-TraceListener בהתאמה אישית או למופע ILogger בהתאמה אישית.

TraceListener

כדי להפעיל את הרישום ביומן ב-TraceListener, מוסיפים את השורות הבאות ל-method‏ Main לפני שמבצעים קריאות ל-API:

using Google.Ads.GoogleAds.Util;

// Detailed logs.
TraceUtilities.Configure(
    TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "logs/details.log",
    System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "logs/summary.log",
    System.Diagnostics.SourceLevels.All);

ILogger

אם אתם כבר משתמשים ב-ILogger ליומני האפליקציות שלכם, הפתרון הזה מאפשר לכם לשלב יומנים של Google Ads API בתשתית הרישום הקיימת שלכם.

קודם צריך ליצור LoggerFactory. אם כבר יש לכם כזה, צריך להוסיף את המסננים ליומני Google Ads API:

var loggerFactory = LoggerFactory.Create(builder =>
{
    // Log to stdout.
    builder.AddConsole();
    builder.AddFilter(
        TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE, LogLevel.Trace);
    builder.AddFilter(
        TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE, LogLevel.Trace);
});

לאחר מכן, משתמשים ב-LoggerFactory כדי ליצור כלי לרישום ביומן לסיכומים ולפרטים של בקשות ותגובות:

ILogger summaryLogger = loggerFactory.CreateLogger(
    TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE);
ILogger detailLogger = loggerFactory.CreateLogger(
    TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE);

לבסוף, מגדירים את ספריית הלקוח כך שהיא תפנה את העקבות שלה למופעים של ILogger:

TraceUtilities.ConfigureSummaryLogger(summaryLogger);
TraceUtilities.ConfigureDetailLogger(detailLogger);

הפתרון הזה מאפשר לכם לשלב יומנים של בקשות ותגובות של Google Ads API במסגרות רישום קיימות, כמו Log4Net,‏ NLog ו-Serilog.

רמות הרישום ביומן

הספרייה מתעדת סוגים שונים של אירועים ברמות שונות של יומנים:

• תגובה מוצלחת מה-API: סיכום נרשם ביומן ב-INFO; בקשה ותגובה מלאות נרשמות ביומן ב-DEBUG.
• תגובת שגיאה של API: הודעת סיכום נרשמת ביומן ב-WARN; בקשה מלאה ותגובה נרשמות ביומן ב-INFO.
• כשלים חלקיים: נרשמו ביומן ב-DEBUG.

מזהה בקשה

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

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

חילוץ מקריאות רגילות ל-API מסוג unary

אפשר להשתמש ב-CallSettings בהתאמה אישית עם TrailingMetadataHandler כדי לתעד מזהי בקשות משיחות רגילות מסוג unary:

CallSettings callSettings = CallSettings.FromTrailingMetadataHandler(
    metadata =>
    {
        // Extract and log the request ID from the trailing metadata.
        string requestId = metadata.Get("request-id")?.Value;
        Console.WriteLine($"Request ID: {requestId}");
    });
// Add the campaigns.
MutateCampaignsResponse retVal = campaignService.MutateCampaigns(
    customerId.ToString(), operations.ToArray(), callSettings);

חילוץ מקריאות ל-API של סטרימינג

מזהה הבקשה מוחזר כחלק מאובייקט התגובה לקריאות של Streaming API. לדוגמה, אפשר לקבל את מזהה הבקשה של קריאה ל-SearchStream באופן הבא:

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V25.GoogleAdsService);

// Retrieve all campaigns.
string query = @"SELECT
                campaign.id,
                campaign.name,
                campaign.network_settings.target_content_network
            FROM campaign
            ORDER BY campaign.id";

// Issue a search request.
googleAdsService.SearchStream(
    customerId.ToString(),
    query,
    (SearchGoogleAdsStreamResponse resp) =>
    {
        // Extract the request ID from the response.
        string requestId = resp.RequestId;
        Console.WriteLine($"Request ID: {requestId}");
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            Console.WriteLine(
                "Campaign with ID {0} and name '{1}' was found.",
                googleAdsRow.Campaign.Id,
                googleAdsRow.Campaign.Name);
        }
    }
);

חריגים

מזהה הבקשה מוחזר כחלק מהחריגה GoogleAdsException בכל פעם שקריאה ל-API נכשלת:

try
{
    // Make an API call.
}
catch (GoogleAdsException e)
{
    string requestId = e.RequestId;
    Console.WriteLine($"Failed Request ID: {requestId}");
}

הגדרת רישום מתקדם ביומן

אם יומן ה-API לא מספק לכם מספיק פרטים, אתם יכולים להפעיל רישום ביומן ברמה נמוכה יותר ברמת התעבורה של gRPC. חשוב לזכור שהפלט יכול להיות גדול.

כשמשתמשים בהעברה Grpc.Net.Client שמוגדרת כברירת מחדל, צריך להגדיר יומנים ברמת ההעברה באמצעות הספק ILogger של ‎ .NET, על ידי הוספת מסנן לקטגוריה Grpc (לדוגמה, builder.AddFilter("Grpc", LogLevel.Debug)).

אם אתם משתמשים בשיטת ההעברה מדור קודם Grpc.Core (UseGrpcCore = true), יומני gRPC נכתבים ל-stderr כברירת מחדל, או שאתם יכולים לצרף כלי משלכם לרישום ביומן כמו בדוגמה הבאה. פרטים נוספים זמינים במאמר בנושא משתני סביבה נתמכים של gRPC.

Environment.SetEnvironmentVariable("GRPC_VERBOSITY", "DEBUG");
Environment.SetEnvironmentVariable("GRPC_TRACE", "http");
GrpcEnvironment.SetLogger(new ConsoleLogger());

הגדרת TraceListener באמצעות App.config (גרסה קודמת)

אם האפליקציה שלכם מיועדת ל-‎ .NET Framework, אתם יכולים לטעון את הגדרות הרישום ביומן מהקובץ App.config או Web.config של האפליקציה. זו פונקציונליות מדור קודם של ‎ .NET שלא נתמכת באפליקציות שנוצרו עבור יעדי ‎ .NET מודרניים.

כדי להשתמש בתכונה הזו, מוסיפים את השינויים הבאים לקובץ התצורה:

1. מוסיפים את קטע הקוד הבא מתחת לקטע <configuration>:

   <system.diagnostics>
     <sources>
       <source name="GoogleAds.DeprecationMessages"
           switchName="GoogleAds.DeprecationMessages"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="myListener"
                type="System.Diagnostics.EventLogTraceListener"
                initializeData="Application" />
         </listeners>
       </source>
       <source name="GoogleAds.DetailedRequestLogs"
           switchName="GoogleAds.DetailedRequestLogs"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="detailedRequestLogListener"
                type="System.Diagnostics.ConsoleTraceListener"
                initializeData="true" />
           <!-- Use the following to log to a file. Modify the initializeData
                attribute to control the path to the detailed request log
                file. -->
           <!--
           <add name="detailedRequestLogListener"
                type="System.Diagnostics.TextWriterTraceListener"
                initializeData="C:\Logs\detailed_logs.log" />
           <remove name="Default" />
           -->
         </listeners>
       </source>
       <source name="GoogleAds.SummaryRequestLogs"
           switchName="GoogleAds.SummaryRequestLogs"
           switchType="System.Diagnostics.SourceSwitch">
         <listeners>
           <add name="summaryRequestLogListener"
                type="System.Diagnostics.ConsoleTraceListener"
                initializeData="true" />
           <!-- Use the following to log to a file. Modify the initializeData
                attribute to control the path to the summary request log
                file. -->
           <!--
           <add name="summaryRequestLogListener"
                type="System.Diagnostics.TextWriterTraceListener"
                initializeData="C:\Logs\summary_logs.log" />
           -->
           <remove name="Default" />
         </listeners>
       </source>
     </sources>
     <switches>
       <!-- Use this trace switch to control the deprecation trace messages
            written by Google Ads .NET libraries. The default level is set to
            Warning. To disable all messages, set this value to Off. -->
       <add name="GoogleAds.DeprecationMessages" value="Warning" />
       <!-- Use this trace switch to control the detailed request logs written
            by Google Ads .NET libraries. The default level is set to Off.
            Logs are generated at both the Error and Information levels. -->
       <add name="GoogleAds.DetailedRequestLogs" value="Off" />
       <!-- Use this trace switch to control the summary request logs written
            by Google Ads .NET libraries. The default level is set to Off.
            Logs are generated at both the Error and Information levels. -->
       <add name="GoogleAds.SummaryRequestLogs" value="Off" />
     </switches>
     <trace autoflush="true" />
   </system.diagnostics>
   

2. מוסיפים את קטע הקוד הבא מתחת לקטע <configSections>:

   <section name="system.diagnostics"
            type="System.Diagnostics.SystemDiagnosticsSection" />
   

   ה-App.config שלכם ייראה כך:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
       <section name="system.diagnostics"
                type="System.Diagnostics.SystemDiagnosticsSection" />
     </configSections>
     <GoogleAdsApi>
       <!-- Google Ads API settings. -->
     </GoogleAdsApi>
     <system.diagnostics>
       <!-- Logging settings. -->
     </system.diagnostics>
   </configuration>