設定記錄功能

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

例外狀況

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>