پیکربندی ثبت گزارش

کتابخانه کارخواه .NET درخواست‌ها، پاسخ‌ها، و پیام‌های خلاصه‌ای را که به Google Ads API ارسال شده است ثبت می‌کند. گزارش‌های رویداد را می‌توان در TraceListener سفارشی یا در نمونه ILogger سفارشی نوشت.

TraceListener

با افزودن خطوط زیر در روش Main خود قبل‌از برقراری هرگونه تماس با میانای برنامه‌سازی کاربردی، می‌توانید ثبت گزارش در TraceListener را فعال کنید:

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» را در زیرساخت گزارش‌گیری موجودتان ادغام کنید.

ابتدا 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 ادغام کنید.

سطوح گزارش

کتابخانه انواع مختلف رویدادها را در سطوح گزارش مختلف ثبت می‌کند:

• پاسخ موفقیت‌آمیز میانای برنامه‌سازی کاربردی: خلاصه در INFO ثبت شده است؛ درخواست و پاسخ کامل در DEBUG ثبت شده است.
• پاسخ خطای میانای برنامه‌سازی کاربردی: پیام خلاصه در WARN ثبت شده است؛ درخواست و پاسخ کامل در INFO ثبت شده است.
• موارد ناقص ناموفق: در DEBUG ثبت شد.

شناسه درخواست

در بیشتر موارد، گزارش‌های تولیدشده توسط کتابخانه مشتری جزئیات کافی برای عیب‌یابی مشکلات شما ارائه می‌دهند. وقتی با پشتیبانی تماس می‌گیرید، یا گزارش‌ها را ارائه دهید (که به‌طور پیش‌فرض فیلدهای اصالت‌سنجی حساس را ویرایش می‌کند) یا شناسه درخواست را هم‌رسانی کنید که به‌عنوان بخشی از گزارش پاسخ ثبت شده است.

اگر ترجیح می‌دهید شناسه درخواست را به‌صورت برنامه‌نویسی‌شده ضبط کنید، از یکی از رویکردهای زیر استفاده کنید.

استخراج از فراخوانی‌های معمولی میانای برنامه‌سازی کاربردی یک‌تایی

می‌توانید از CallSettings سفارشی با TrailingMetadataHandler برای ضبط شناسه‌های درخواست از تماس‌های یک‌تایی معمولی استفاده کنید:

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

شناسه درخواست به‌عنوان بخشی از شیء پاسخ برای تماس‌های API جاری‌سازی برگردانده می‌شود. برای مثال، می‌توانید شناسه درخواست برای تماس SearchStream را به‌صورت زیر دریافت کنید:

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

استثناها

هرگاه فراخوانی میانای برنامه‌سازی کاربردی ناموفق باشد، شناسه درخواست به‌عنوان بخشی از استثنای GoogleAdsException برگردانده می‌شود:

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

پیکربندی گزارش‌گیری پیشرفته

اگر گزارش میانای برنامه‌سازی کاربردی جزئیات کافی به شما نمی‌دهد، ثبت گزارش سطح پایین‌تر را در سطح انتقال 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 ساخته شده است، می‌توانید پیکربندی ثبت گزارش را از فایل 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>