نموذج التعليمات البرمجية لإرسال البيانات إلى Azure Monitor باستخدام واجهة برمجة تطبيقات استيعاب السجلات

توفر هذه المقالة نموذج التعليمات البرمجية باستخدام واجهة برمجة تطبيقات استيعاب السجلات. يتطلب كل نموذج إنشاء المكونات التالية قبل تشغيل التعليمات البرمجية. راجع البرنامج التعليمي: إرسال البيانات إلى Azure Monitor باستخدام واجهة برمجة تطبيقات استيعاب السجلات (قوالب Resource Manager) للحصول على معاينة كاملة لإنشاء هذه المكونات المكونة لدعم كل عينة من هذه العينات.

• جدول مخصص في مساحة عمل Log Analytics
• قاعدة جمع البيانات (DCR) لتوجيه البيانات إلى الجدول الهدف
• تطبيق Microsoft Entra مع الوصول إلى DCR
• نقطة نهاية جمع البيانات (DCE) إذا كنت تستخدم رابطا خاصا. وإلا، استخدم نقطة نهاية سجلات DCR.

التعليمة البرمجية العينة

NET.

يستخدم البرنامج النصي التالي مكتبة عميل Azure Monitor Ingestion ل .NET.

1. تثبيت مكتبة عميل Azure Monitor Ingestion ومكتبة Azure Identity. مكتبة هوية Azure مطلوبة للمصادقة المستخدمة في هذا النموذج.

   dotnet add package Azure.Identity
   dotnet add package Azure.Monitor.Ingestion
   

2. إنشاء متغيرات البيئة التالية مع قيم لتطبيق Microsoft Entra الخاص بك. يتم استخدام هذه القيم من قبل DefaultAzureCredential في مكتبة Azure Identity.

   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET

3. استبدل المتغيرات في نموذج التعليمات البرمجية التالي بقيم من DCR الخاص بك. قد تحتاج أيضا إلى استبدال نموذج البيانات بالبيانات الخاصة بك.

   using Azure;
   using Azure.Core;
   using Azure.Identity;
   using Azure.Monitor.Ingestion;
   
   // Initialize variables
   var endpoint = new Uri("https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com");
   var ruleId = "dcr-00000000000000000000000000000000";
   var streamName = "Custom-MyTableRawData";
   
   // Create credential and client
   var credential = new DefaultAzureCredential();
   LogsIngestionClient client = new(endpoint, credential);
   
   DateTimeOffset currentTime = DateTimeOffset.UtcNow;
   
   // Use BinaryData to serialize instances of an anonymous type into JSON
   BinaryData data = BinaryData.FromObjectAsJson(
       new[] {
           new
           {
               Time = currentTime,
               Computer = "Computer1",
               AdditionalContext = new
               {
                   InstanceName = "user1",
                   TimeZone = "Pacific Time",
                   Level = 4,
                   CounterName = "AppMetric1",
                   CounterValue = 15.3
               }
           },
           new
           {
               Time = currentTime,
               Computer = "Computer2",
               AdditionalContext = new
               {
                   InstanceName = "user2",
                   TimeZone = "Central Time",
                   Level = 3,
                   CounterName = "AppMetric1",
                   CounterValue = 23.5
               }
           },
       });
   
   // Upload logs
   try
   {
       Response response = client.Upload(ruleId, streamName, RequestContent.Create(data));
   }
   catch (Exception ex)
   {
       Console.WriteLine("Upload failed with Exception " + ex.Message);
   }
   
   // Logs can also be uploaded in a List
   var entries = new List<Object>();
   for (int i = 0; i < 10; i++)
   {
       entries.Add(
           new {
               Time = recordingNow,
               Computer = "Computer" + i.ToString(),
               AdditionalContext = i
           }
       );
   }
   
   // Make the request
   LogsUploadOptions options = new LogsUploadOptions();
   bool isTriggered = false;
   options.UploadFailed += Options_UploadFailed;
   await client.UploadAsync(TestEnvironment.DCRImmutableId, TestEnvironment.StreamName, entries, options).ConfigureAwait(false);
   
   Task Options_UploadFailed(LogsUploadFailedEventArgs e)
   {
       isTriggered = true;
       Console.WriteLine(e.Exception);
       foreach (var log in e.FailedLogs)
       {
           Console.WriteLine(log);
       }
       return Task.CompletedTask;
   }
   

4. قم بتنفيذ التعليمات البرمجية، ويجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

الذهاب

يستخدم نموذج التعليمات البرمجية التالي وحدة عميل Azure Monitor Ingestion Logs ل Go.

1. استخدم go get لتثبيت وحدات عميل Azure Monitor Ingestion Logs وAzure Identity ل Go. الوحدة النمطية Azure Identity مطلوبة للمصادقة المستخدمة في هذا النموذج.

   go get github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs
   go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
   

2. إنشاء متغيرات البيئة التالية مع قيم لتطبيق Microsoft Entra الخاص بك. يتم استخدام هذه القيم من قبل DefaultAzureCredential في الوحدة النمطية Azure Identity.

   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET

3. استبدل المتغيرات في نموذج التعليمات البرمجية التالي بقيم من DCR الخاص بك. قد تحتاج أيضا إلى استبدال بيانات العينة بالبيانات الخاصة بك.

   package main
   
   import (
       "context"
       "encoding/json"
       "strconv"
       "time" 
   
       "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
       "github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs"
   )
   
   // logs ingestion URI 
   const endpoint = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com"
   // data collection rule (DCR) immutable ID
   const ruleID = "dcr-00000000000000000000000000000000"
   // stream name in the DCR that represents the destination table
   const streamName = "Custom-MyTableRawData"                 
   
   type Computer struct {
       Time              time.Time
       Computer          string
       AdditionalContext string
   }
   
   func main() {
       // creating the client using DefaultAzureCredential
       cred, err := azidentity.NewDefaultAzureCredential(nil)
   
       if err != nil {
           //TODO: handle error
       }
   
       client, err := azlogs.NewClient(endpoint, cred, nil)
   
       if err != nil {
           //TODO: handle error
       }
   
       // generating logs
       // logs should match the schema defined by the provided stream
       var data []Computer
   
       for i := 0; i < 10; i++ {
           data = append(data, Computer{
               Time:              time.Now().UTC(),
               Computer:          "Computer" + strconv.Itoa(i),
               AdditionalContext: "context",
           })
       }
   
       // marshal data into []byte
       logs, err := json.Marshal(data)
   
       if err != nil {
           panic(err)
       }
   
       // upload logs
       _, err = client.Upload(context.TODO(), ruleID, streamName, logs, nil)
   
       if err != nil {
           //TODO: handle error
       }
   }
   

4. قم بتنفيذ التعليمات البرمجية، ويجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

Java

يستخدم نموذج التعليمات البرمجية التالي مكتبة عميل Azure Monitor Ingestion ل Java.

1. قم بتضمين حزمة استيعاب السجلات والحزمة azure-identityمن مكتبة Azure Identity. مكتبة هوية Azure مطلوبة للمصادقة المستخدمة في هذا النموذج.

   إشعار

   راجع مستودعات Maven لمكتبة عميل Microsoft Azure للهوية وMicrosoft Azure SDK لاستيعاب بيانات Azure Monitor للحصول على أحدث الإصدارات.

   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-monitor-ingestion</artifactId>
       <version>{get-latest-version}</version>    
   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-identity</artifactId>
       <version>{get-latest-version}</version>
   </dependency>
   

2. إنشاء متغيرات البيئة التالية مع قيم لتطبيق Microsoft Entra الخاص بك. يتم استخدام هذه القيم من قبل DefaultAzureCredential في مكتبة Azure Identity.

   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET

3. استبدل المتغيرات في نموذج التعليمات البرمجية التالي بقيم من DCR الخاص بك. قد تحتاج أيضا إلى استبدال نموذج البيانات بالبيانات الخاصة بك.

   import com.azure.identity.DefaultAzureCredentialBuilder; 
   import com.azure.monitor.ingestion.models.LogsUploadException;
   
   import java.time.OffsetDateTime; 
   import java.util.Arrays; 
   import java.util.List; 
   
   public class LogsUploadSample {
       public static void main(String[] args) { 
   
           LogsIngestionClient client = new LogsIngestionClientBuilder()
               .endpoint("https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com") 
               .credential(new DefaultAzureCredentialBuilder().build()) 
               .buildClient(); 
   
           List<Object> dataList = Arrays.asList( 
               new Object() { 
                   OffsetDateTime time = OffsetDateTime.now(); 
                   String computer = "Computer1"; 
                   Object additionalContext = new Object() { 
                       String instanceName = "user4"; 
                       String timeZone = "Pacific Time"; 
                       int level = 4; 
                       String counterName = "AppMetric1"; 
                       double counterValue = 15.3; 
                   }; 
               }, 
               new Object() { 
                   OffsetDateTime time = OffsetDateTime.now(); 
                   String computer = "Computer2"; 
                   Object additionalContext = new Object() { 
                       String instanceName = "user2"; 
                       String timeZone = "Central Time"; 
                       int level = 3; 
                       String counterName = "AppMetric2"; 
                       double counterValue = 43.5; 
                   }; 
               }); 
   
           try { 
               client.upload("dcr-00000000000000000000000000000000", "Custom-MyTableRawData", dataList);  
               System.out.println("Logs uploaded successfully"); 
           } catch (LogsUploadException exception) { 
               System.out.println("Failed to upload logs "); 
               exception.getLogsUploadErrors() 
                   .forEach(httpError -> System.out.println(httpError.getMessage())); 
           } 
       }
   }
   

4. قم بتنفيذ التعليمات البرمجية، ويجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

جافا سكريبت

يستخدم نموذج التعليمات البرمجية التالي مكتبة عميل Azure Monitor Ingestion ل JavaScript.

1. استخدم npm لتثبيت مكتبات عميل Azure Monitor Ingestion وAzure Identity ل JavaScript. مكتبة هوية Azure مطلوبة للمصادقة المستخدمة في هذا النموذج.

   npm install --save @azure/monitor-ingestion
   npm install --save @azure/identity
   

2. إنشاء متغيرات البيئة التالية مع قيم لتطبيق Microsoft Entra الخاص بك. يتم استخدام هذه القيم من قبل DefaultAzureCredential في مكتبة Azure Identity.

   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET

3. استبدل المتغيرات في نموذج التعليمات البرمجية التالي بقيم من DCR الخاص بك. قد تحتاج أيضا إلى استبدال بيانات العينة بالبيانات الخاصة بك.

   const { DefaultAzureCredential } = require("@azure/identity");
   const { LogsIngestionClient, isAggregateLogsUploadError } = require("@azure/monitor-ingestion");
   
   require("dotenv").config();
   
   async function main() {
     const logsIngestionEndpoint = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com";
     const ruleId = "dcr-00000000000000000000000000000000";
     const streamName = "Custom-MyTableRawData";
     const credential = new DefaultAzureCredential();
     const client = new LogsIngestionClient(logsIngestionEndpoint, credential);
     const logs = [
       {
         Time: "2021-12-08T23:51:14.1104269Z",
         Computer: "Computer1",
         AdditionalContext: {
             "InstanceName": "user1",
             "TimeZone": "Pacific Time",
             "Level": 4,
             "CounterName": "AppMetric2",
             "CounterValue": 35.3    
         }
       },
       {
         Time: "2021-12-08T23:51:14.1104269Z",
         Computer: "Computer2",
         AdditionalContext: {
             "InstanceName": "user2",
             "TimeZone": "Pacific Time",
             "Level": 4,
             "CounterName": "AppMetric2",
             "CounterValue": 43.5    
         }
       },
     ];
     try{
       await client.upload(ruleId, streamName, logs);
     }
     catch(e){
       let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
       if (aggregateErrors.length > 0) {
         console.log("Some logs have failed to complete ingestion");
         for (const error of aggregateErrors) {
           console.log(`Error - ${JSON.stringify(error.cause)}`);
           console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
         }
       } else {
         console.log(e);
       }
     }
   }
   
   main().catch((err) => {
     console.error("The sample encountered an error:", err);
     process.exit(1);
   });
   

4. قم بتنفيذ التعليمات البرمجية، ويجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

بوويرشيل

يرسل رمز PowerShell التالي البيانات إلى نقطة النهاية باستخدام أساسيات HTTP REST.

إشعار

يتطلب هذا النموذج PowerShell v7.0 أو أحدث.

1. قم بتشغيل نموذج أمر PowerShell التالي، الذي يضيف تجميعا مطلوبا للبرنامج النصي.

   Add-Type -AssemblyName System.Web
   

2. استبدل المعلمات في قسم الخطوة 0 بقيم من التطبيق الخاص بك وDCR. قد تحتاج أيضا إلى استبدال نموذج البيانات في قسم الخطوة 2 بالبيانات الخاصة بك.

   ### Step 0: Set variables required for the rest of the script.
   
   # information needed to authenticate to AAD and obtain a bearer token
   $tenantId = "00000000-0000-0000-00000000000000000" #Tenant ID the data collection endpoint resides in
   $appId = " 000000000-0000-0000-00000000000000000" #Application ID created and granted permissions
   $appSecret = "0000000000000000000000000000000000000000" #Secret created for the application
   
   # information needed to send data to the DCR endpoint
   $endpoint_uri = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com" #Logs ingestion URI for the DCR
   $dcrImmutableId = "dcr-00000000000000000000000000000000" #the immutableId property of the DCR object
   $streamName = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table
   
   
   ### Step 1: Obtain a bearer token used later to authenticate against the DCR.
   
   $scope= [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")   
   $body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";
   $headers = @{"Content-Type"="application/x-www-form-urlencoded"};
   $uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
   
   $bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token
   
   
   ### Step 2: Create some sample data. 
   
   $currentTime = Get-Date ([datetime]::UtcNow) -Format O
   $staticData = @"
   [
   {
       "Time": "$currentTime",
       "Computer": "Computer1",
       "AdditionalContext": {
           "InstanceName": "user1",
           "TimeZone": "Pacific Time",
           "Level": 4,
           "CounterName": "AppMetric1",
           "CounterValue": 15.3    
       }
   },
   {
       "Time": "$currentTime",
       "Computer": "Computer2",
       "AdditionalContext": {
           "InstanceName": "user2",
           "TimeZone": "Central Time",
           "Level": 3,
           "CounterName": "AppMetric1",
           "CounterValue": 23.5     
       }
   }
   ]
   "@;
   
   
   ### Step 3: Send the data to the Log Analytics workspace.
   
   $body = $staticData;
   $headers = @{"Authorization"="Bearer $bearerToken";"Content-Type"="application/json"};
   $uri = "$endpoint_uri/dataCollectionRules/$dcrImmutableId/streams/$($streamName)?api-version=2023-01-01"
   
   $uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers
   

   إشعار

   إذا تلقيت خطأ Unable to find type [System.Web.HttpUtility]. ، فقم بتشغيل السطر الأخير في القسم 1 من البرنامج النصي لإصلاحه وتنفيذه. لن يؤدي تنفيذه دون تعليق كجزء من البرنامج النصي إلى حل المشكلة. يجب تنفيذ الأمر بشكل منفصل.

3. تنفيذ البرنامج النصي، ويجب أن تشاهد استجابة HTTP - 204 . يجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

Python

يستخدم نموذج التعليمات البرمجية التالي مكتبة عميل Azure Monitor Ingestion ل Python.

1. استخدم pip لتثبيت مكتبات عميل Azure Monitor Ingestion وAzure Identity ل Python. مكتبة هوية Azure مطلوبة للمصادقة المستخدمة في هذا النموذج.

   pip install azure-monitor-ingestion
   pip install azure-identity
   

2. إنشاء متغيرات البيئة التالية مع قيم لتطبيق Microsoft Entra الخاص بك. يتم استخدام هذه القيم من قبل DefaultAzureCredential في مكتبة Azure Identity.

   • AZURE_TENANT_ID
   • AZURE_CLIENT_ID
   • AZURE_CLIENT_SECRET

3. استبدل المتغيرات في نموذج التعليمات البرمجية التالي بقيم من DCR الخاص بك. قد تحتاج أيضا إلى استبدال نموذج البيانات في قسم الخطوة 2 بالبيانات الخاصة بك.

   # information needed to send data to the DCR endpoint
   endpoint_uri = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com" # logs ingestion endpoint of the DCR
   dcr_immutableid = "dcr-00000000000000000000000000000000" # immutableId property of the Data Collection Rule
   stream_name = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table
   
   # Import required modules
   import os
   from azure.identity import DefaultAzureCredential
   from azure.monitor.ingestion import LogsIngestionClient
   from azure.core.exceptions import HttpResponseError
   
   credential = DefaultAzureCredential()
   client = LogsIngestionClient(endpoint=endpoint_uri, credential=credential, logging_enable=True)
   
   body = [
           {
           "Time": "2023-03-12T15:04:48.423211Z",
           "Computer": "Computer1",
               "AdditionalContext": {
                   "InstanceName": "user1",
                   "TimeZone": "Pacific Time",
                   "Level": 4,
                   "CounterName": "AppMetric2",
                   "CounterValue": 35.3    
               }
           },
           {
               "Time": "2023-03-12T15:04:48.794972Z",
               "Computer": "Computer2",
               "AdditionalContext": {
                   "InstanceName": "user2",
                   "TimeZone": "Central Time",
                   "Level": 3,
                   "CounterName": "AppMetric2",
                   "CounterValue": 43.5     
               }
           }
       ]
   
   try:
       client.upload(rule_id=dcr_immutableid, stream_name=stream_name, logs=body)
   except HttpResponseError as e:
       print(f"Upload failed: {e}")
   

4. قم بتنفيذ التعليمات البرمجية، ويجب أن تصل البيانات إلى مساحة عمل Log Analytics في غضون بضع دقائق.

استكشاف الأخطاء وإصلاحها

يصف هذا القسم حالات الخطأ المختلفة التي قد تتلقاها وكيفية تصحيحها.

البرنامج النصي يرجع رمز الخطأ 403

تأكد من أن لديك الأذونات الصحيحة لتطبيقك إلى DCR. قد تحتاج أيضا إلى الانتظار لمدة تصل إلى 30 دقيقة حتى يتم نشر الأذونات.

يقوم البرنامج النصي بإرجاع رمز الخطأ 413 أو تحذير من TimeoutExpired مع الرسالة ReadyBody_Client الاتصال ionAbort في الاستجابة

الرسالة كبيرة جداً. يبلغ الحد الأقصى لحجم الرسالة حاليا 1 ميغابايت لكل مكالمة.

البرنامج النصي يرجع رمز الخطأ 429

تم تجاوز حدود معدل واجهة برمجة التطبيقات. يتم تعيين الحدود حاليا إلى 500 ميغابايت من البيانات في الدقيقة لكل من البيانات المضغوطة وغير المضغوطة و300000 طلب في الدقيقة. أعِد المحاولة بعد المدة المدرجة في العنوان Retry-After في الاستجابة.

البرنامج النصي يرجع رمز الخطأ 503

تأكد من أن لديك الأذونات الصحيحة لتطبيقك إلى DCR. قد تحتاج أيضا إلى الانتظار لمدة تصل إلى 30 دقيقة حتى يتم نشر الأذونات.

لا تتلقى خطأ، ولكن البيانات لا تظهر في مساحة العمل

قد يستغرق استيعاب البيانات بعض الوقت، خاصة في المرة الأولى التي يتم فيها إرسال البيانات إلى جدول معين. لا ينبغي أن يستغرق الأمر أكثر من 15 دقيقة.

لا يتعرف IntelliSense في Log Analytics على الجدول الجديد

قد يستغرق تحديث ذاكرة التخزين المؤقت التي تقود IntelliSense ما يصل إلى 24 ساعة.

الخطوات التالية

• تعرف على المزيد حول قواعد جمع البيانات
• تعرف على المزيد بشأن كتابة استعلامات التحويل