الوصول إلى API Azure Monitor Log Analytics

يمكنك إرسال طلب استعلام إلى مساحة عمل باستخدام نقطة https://api.loganalytics.azure.comنهاية Azure Monitor Log Analytics . للوصول إلى نقطة النهاية، يجب المصادقة من خلال معرف Microsoft Entra.

المصادقة باستخدام مفتاح واجهة برمجة التطبيقات التجريبي

لاستكشاف واجهة برمجة التطبيقات بسرعة دون مصادقة Microsoft Entra، استخدم مساحة عمل العرض التوضيحي مع عينة من البيانات، والتي تدعم مصادقة مفتاح واجهة برمجة التطبيقات.

لمصادقة الاستعلامات وتشغيلها مقابل نموذج مساحة العمل، استخدم DEMO_WORKSPACE كـ {workspace-id} ومرّر في مفتاح API DEMO_KEY.

إذا كان معرف التطبيق أو مفتاح API غير صحيح، فترجع خدمة واجهة برمجة التطبيقات خطأ 403 (ممنوع).

يمكن تمرير مفتاح DEMO_KEY API بثلاث طرق مختلفة، اعتمادا على ما إذا كنت تريد استخدام عنوان أو عنوان URL أو المصادقة الأساسية:

• العنوان المخصص: قم بتوفير مفتاح API في العنوان X-Api-Keyالمخصص .
• معلمة الاستعلام: توفير مفتاح API في معلمة api_keyعنوان URL .
• المصادقة الأساسية: قم بتوفير مفتاح API إما باسم المستخدم أو كلمة المرور. إذا قمت بتوفير كليهما، يتعين أن يكون مفتاح API في اسم المستخدم.

يستخدم هذا المثال معرف مساحة العمل ومفتاح API في العنوان:

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

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

نقطة نهاية واجهة برمجة التطبيقات العامة هي:

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

الموقع:

• نسخة-api: نسخة API. الإصدار الحالي هو "v1".
• workspaceId: معرف مساحة العمل الخاص بك.

يتم تمرير الاستعلام في نص الطلب.

على سبيل المثال:

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

إعداد المصادقة

للوصول إلى واجهة برمجة التطبيقات، يمكنك تسجيل تطبيق عميل باستخدام معرف Microsoft Entra وطلب رمز مميز.

1. تسجيل تطبيق في معرف Microsoft Entra.

2. في صفحة نظرة عامة على التطبيق، حدد أذونات واجهة برمجة التطبيقات.

3. حدد إضافة إذن.

4. في علامة التبويب واجهات برمجة التطبيقات التي تستخدمها مؤسستي، ابحث عن Log Analytics وحدد Log Analytics API من القائمة.

   

5. حدد الأذونات المفوضة.

6. حدد خانة الاختيار Data.Read .

7. حدد إضافة أذونات.

   

الآن بعد أن تم تسجيل تطبيقك ولديه أذونات لاستخدام واجهة برمجة التطبيقات، امنح تطبيقك حق الوصول إلى مساحة عمل Log Analytics.

1. من صفحة نظرة عامة على مساحة عمل Log Analytics، حدد Access control (IAM).

2. حدد Add role assignment.

   

3. حدد دور القارئ ثم حدد الأعضاء.

   

4. في علامة التبويب الأعضاء ، اختر تحديد أعضاء.

5. أدخل اسم تطبيقك في المربع تحديد .

6. حدد تطبيقك واختر تحديد.

7. حدد مراجعة + تعيين.

   

8. بعد الانتهاء من إعداد Active Directory وأذونات مساحة العمل، اطلب رمزا مميزا للتخويل.

طلب رمز تخويل مميز

قبل البدء، تأكد من أن لديك جميع القيم المطلوبة لإجراء الطلب بنجاح. تتطلب جميع الطلبات ما يلي:

• معرف مستأجر Microsoft Entra.
• معرف مساحة العمل الخاص بك.
• معرف عميل Microsoft Entra للتطبيق.
• سر عميل Microsoft Entra للتطبيق.

تدعم واجهة برمجة تطبيقات Log Analytics مصادقة Microsoft Entra مع ثلاثة تدفقات مختلفة من Microsoft Entra ID OAuth2 :

• بيانات اعتماد العميل
• التعليمة البرمجية للتخويل
• ضمني

تدفق بيانات اعتماد العميل

في تدفق بيانات اعتماد العميل، يتم استخدام الرمز المميز مع نقطة نهاية Log Analytics. يتم تقديم طلب واحد لتلقي رمز مميز باستخدام بيانات الاعتماد المتوفرة لتطبيقك في الخطوة السابقة عند تسجيل تطبيق في Microsoft Entra ID.

استخدم resource=https://api.loganalytics.azure.com.

احصل على رمز مصادقة باستخدام أي من الطرق التالية:

• CLI
• واجهة برمجة تطبيقات REST
• SDK

عند طلب رمز مميز، يجب توفير معلمة resource . resource المعلمة هي عنوان URL للمورد الذي تريد الوصول إليه.

وتشتمل الموارد على ما يلي:

• https://management.azure.com
• https://api.loganalytics.io
• https://monitoring.azure.com

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

az account get-access-token 

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

استخدم الرمز المميز في الطلبات إلى نقطة نهاية Log Analytics:

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

استجابة مثال:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

تدفق تعليمات التفويض البرمجية

تدفق OAuth2 الرئيسي المدعوم من خلال التعليمات البرمجية للتخويل. يتطلب هذا الأسلوب طلبين من طلبات HTTP للحصول على رمز مميز لاستدعاء واجهة برمجة تطبيقات Azure Monitor Log Analytics. هناك عنوانا URL، مع نقطة نهاية واحدة لكل طلب. يتم وصف تنسيقاتها في الأقسام التالية.

عنوان URL لرمز التخويل (طلب GET)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

عند تقديم طلب إلى عنوان URL للتخويل، فإن client_id هو معرف التطبيق من تطبيق Microsoft Entra، المنسخ من قائمة خصائص التطبيق. redirect_uri هو عنوان URL للصفحة الرئيسية/تسجيل الدخول من نفس تطبيق Microsoft Entra. عند نجاح الطلب، تعيد نقطة النهاية هذه توجيهك إلى صفحة تسجيل الدخول التي قدمتها عند التسجيل باستخدام رمز التخويل الملحق بعنوان URL. راجع المثال التالي:

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

عند هذه النقطة، حصلت على رمز تخويل، والذي تحتاج إليه الآن لطلب رمز مميز للوصول.

عنوان URL لرمز التخويل (طلب POST)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

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

مثال الاستجابة:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

جزء الرمز المميز للوصول من هذه الاستجابة هو ما تقدمه إلى واجهة برمجة تطبيقات Log Analytics في عنوان Authorization: Bearer. يمكنك أيضا استخدام الرمز المميز للتحديث في المستقبل للحصول على access_token جديد refresh_token عندما يكون رمز التحديث الخاص بك قديما. بالنسبة لهذا الطلب، يكون التنسيق ونقطة النهاية هما:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

مثال الاستجابة:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

تدفق التعليمات البرمجية الضمنية

تدعم واجهة برمجة تطبيقات Log Analytics التدفق الضمني OAuth2. لهذا التدفق، مطلوب طلب واحد فقط، ولكن لا يمكن الحصول على رمز تحديث مميز.

عنوان URL لتخويل التعليمات البرمجية الضمنية

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

ينتج عن الطلب الناجح إعادة توجيه إلى عنوان URI لإعادة التوجيه باستخدام الرمز المميز في عنوان URL:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

يمكن استخدام هذه access_token كقيمة Authorization: Bearer عنوان عند تمريرها إلى واجهة برمجة تطبيقات Log Analytics لتخويل الطلبات.

مزيد من المعلومات

يمكنك العثور على وثائق حول OAuth2 باستخدام Microsoft Entra هنا:

• تدفق رمز تخويل Microsoft Entra
• تدفق المنح الضمني ل Microsoft Entra
• تدفق بيانات اعتماد عميل Microsoft Entra S2S

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

• تنسيق الطلب
• تنسيق الاستجابة
• الاستعلام عن سجلات لموارد Azure
• استعلامات الدفعات