記錄

.NET 用戶端程式庫會記錄對 Google Ads API 發出的要求、回應和摘要訊息。記錄可以寫入自訂 TraceListener 或自訂 ILogger 執行個體。

TraceListener

在任何 API 呼叫之前，只要在 Main 方法中新增下列程式碼，即可啟用 TraceListener 記錄功能。

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);

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。

要求 ID

在大部分情況下，用戶端程式庫產生的記錄檔可提供充足的詳細資料，協助您排解問題。與支援論壇/別名聯絡時，您可以提供記錄 (預設會遮蓋機密資訊) 或直接分享要求 ID (系統會將要求 ID 記錄在回應記錄檔中)。

如果您想自行擷取要求 ID，可以使用下列其中一種方法：

透過一般 API 呼叫擷取

您可以使用自訂 CallSetting 搭配 TrailingMetadataHandler，擷取一般一元呼叫的要求 ID。

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 呼叫擷取

要求 ID 會在串流 API 呼叫的回應物件中傳回。舉例來說，您可以取得 SearchStream 呼叫的要求 ID，如下所示：

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.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);
        }
    }
);

例外狀況

每當 API 呼叫失敗時，要求 ID 就會做為 GoogleAdsException 例外狀況的一部分傳回。

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());

使用 App.config 的 TraceListener 設定 (舊版)

如果您的應用程式是針對 .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>