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

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

سطوح گزارش

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

  • پاسخ موفقیت‌آمیز میانای برنامه‌سازی کاربردی: خلاصه در 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 برگردانده می‌شود. برای مثال، می‌توانید شناسه درخواست را برای تماس 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 هرگاه فراخوانی API ناموفق باشد برگردانده می‌شود:

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

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

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