ضبط التسجيل

تسجّل مكتبة برامج .NET للعميل الطلبات والردود ورسائل الملخّص التي يتم إرسالها إلى Google Ads API. يمكن كتابة السجلات في TraceListener مخصّص أو في مثيل ILogger مخصّص.

TraceListener

يمكنك تفعيل التسجيل في TraceListener من خلال إضافة الأسطر التالية في طريقة Main قبل إجراء أي طلبات إلى واجهة برمجة التطبيقات:

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

الاستخراج من طلبات البيانات من واجهة برمجة التطبيقات الخاصة بالبث

يتم عرض رقم تعريف الطلب كجزء من عنصر الردّ على طلبات واجهة برمجة تطبيقات البث. على سبيل المثال، يمكنك الحصول على معرّف الطلب لمكالمة SearchStream باتّباع الخطوات التالية:

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

الاستثناءات

يتم عرض معرّف الطلب كجزء من الاستثناء 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 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>