التسجيل

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

TraceListener

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

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "C:\\logs\\details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "C:\\logs\\details.log", System.Diagnostics.SourceLevels.All);

ILogger

إذا كنت تستخدم حاليًا ILogger لسجلات تطبيقك، يتيح لك هذا الحلّ دمج سجلات Google Ads API في سجلاتك الحالية.

أولاً، أنشئ LoggerFactory، أو إذا كان لديك حساب، أضِف الفلاتر لسجلات Google Ads API باتّباع الخطوات التالية:

var loggerFactory = LoggerFactory.Create(delegate (ILoggingBuilder 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.

معرّف الطلب

في معظم الحالات، تقدّم السجلات التي تنشئها مكتبة البرامج تفاصيل كافية لتحديد المشاكل وحلّها. عند التواصل مع منتدى الدعم أو الأسماء المستعارة، يمكنك إما تقديم السجلّات (التي تخفي المعلومات الحساسة تلقائيًا) أو مشاركة معرّف الطلب فقط (الذي يتم تسجيله كجزء من سجلّ الاستجابة).

إذا كنت تفضّل تسجيل رقم تعريف الطلب بنفسك، يمكنك استخدام إحدى الطرق التالية:

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

يمكنك استخدام CallSetting مخصّص مع TrailingMetadataHandler لتسجيل معرّفات الطلبات من المكالمات الأحادية العادية.

CallSettings callSettings = CallSettings.FromTrailingMetadataHandler(
    delegate (Metadata metadata) {
        // Extract the request ID from the trailing metadata.
        string requestId = metadata.Get("request-id").Value;
    });
// Add the campaigns.
MutateCampaignsResponse retVal = campaignService.MutateCampaigns(
    customerId.ToString(), operations.ToArray(), callSettings);

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

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

// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V20.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,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        // Extract the request ID from the response.
        string requestId = resp.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;
}

التسجيل المتقدّم

إذا لم يقدّم لك سجلّ واجهة برمجة التطبيقات تفاصيل كافية، فعِّل المزيد من التسجيل على مستوى منخفض عند مستوى gRPC. يُرجى العِلم أنّ الناتج يمكن أن يكون كبيرًا. تتم كتابة سجلّات gRPC إلى stderr، ولكن يمكنك إرفاق أداة تسجيل خاصة بك كما هو موضّح أدناه. متغيرات البيئة المتوافقة

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 Core.

لاستخدام هذه الميزة، عليك إجراء التغييرات التالية على ملف الإعدادات:

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 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 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 Ads* .NET libraries. The default is level is set to
            Warning. To disable all messages, set this value to Off. See
            msdn.microsoft.com/en-us/library/system.diagnostics.sourcelevels.aspx
            for all possible values this key can take. -->
       <add name="GoogleAds.DeprecationMessages" value="Warning"/>
       <!-- Use this trace switch to control the detailed request logs written by 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
            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>