רישום

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

TraceListener

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

using Google.Ads.GoogleAds.Util;
...

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

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "C:\\logs\\details.log", System.Diagnostics.SourceLevels.All);

חשוב לזכור שצריך לקרוא ל-TraceListeners.Configure רק פעם אחת במהלך מחזור החיים של האפליקציה, כי המופע של TraceListener שנוצר ישמש אוטומטית לכל הבקשות ל-API שהאפליקציה שולחת. אין צורך ליצור מופע חדש לכל בקשה ל-API.

ILogger

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

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

var loggerFactory = LoggerFactory.Create(delegate (ILoggingBuilder 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

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

CallSettings callSettings = CallSettings.FromTrailingMetadataHandler(
    delegate (Metadata metadata) {
        // Extract the request ID from the trailing metadata.
        string requestId = metadata.Get("request-id").Value;
    });
// Add the campaigns.
MutateCampaignsResponse retVal = campaignService.MutateCampaigns(
    customerId.ToString(), operations.ToArray(), callSettings);

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

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

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V21.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,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        // Extract the request ID from the response.
        string requestId = resp.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;
}

רישום מתקדם

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

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 Core.

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

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 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 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 Ads* .NET libraries. The default is level is set to
            Warning. To disable all messages, set this value to Off. See
            msdn.microsoft.com/en-us/library/system.diagnostics.sourcelevels.aspx
            for all possible values this key can take. -->
       <add name="GoogleAds.DeprecationMessages" value="Warning"/>
       <!-- Use this trace switch to control the detailed request logs written by 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
            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>