設定記錄功能

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

TraceListener

如要啟用記錄功能，將記錄檔寫入 TraceListener，請在 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。

要求 ID

在多數情況下，用戶端程式庫產生的記錄檔，足以提供詳細資訊來排解問題。與支援團隊聯絡時，請提供記錄 (預設會遮蓋機密驗證欄位)，或提供要求 ID (記錄在回應記錄中)。

如要透過程式輔助方式擷取要求 ID，請使用下列其中一種方法。

從一般一元 API 呼叫中擷取

您可以搭配 TrailingMetadataHandler 使用自訂 CallSettings，從一般一元呼叫擷取要求 ID：

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

系統會將要求 ID 做為串流 API 呼叫的回應物件傳回。舉例來說，您可以按照下列方式取得 SearchStream 呼叫的要求 ID：

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

例外狀況

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

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

設定進階記錄功能

如果 API 記錄提供的詳細資料不足，請在 gRPC 傳輸層啟用較低層級的記錄。請注意，輸出內容可能相當龐大。

使用預設 Grpc.Net.Client 傳輸時，請透過 .NET 的 ILogger 提供者新增 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());

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

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