التسجيل

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