التسجيل

تسجّل مكتبة عملاء .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 وSeralog.

مستويات السجلّ

وتسجّل المكتبة أنواعًا مختلفة من الأحداث بمستويات سجلّ مختلفة. لتحقيق استجابة ناجحة من واجهة برمجة التطبيقات، يتم تسجيل الملخص على 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.V16.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 بالخطأ القياسي، ولكن يمكنك إرفاق المسجل الخاص بك كما هو موضح أدناه. متغيرات البيئة المتوافقة.

Environment.SetEnvironmentVariable("GRPC_VERBOSITY", "DEBUG");
Environment.SetEnvironmentVariable("GRPC_TRACE", "http");
GrpcEnvironment.SetLogger(new ConsoleLogger());

إعداد TraceListener باستخدام App.config (الإصدار القديم)

إذا تم إنشاء تطبيقك لاستهداف إطار .NET، يمكنك تحميل إعدادات التسجيل من ملف 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>