ضبط التسجيل

تسجّل مكتبة برامج ‎ .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.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 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>