Az Azure Monitor Log Analytics API elérése

Cikk
10/15/2024

Lekérdezési kérelmet az Azure Monitor Log Analytics-végpont https://api.loganalytics.azure.comhasználatával küldhet egy munkaterületre. A végpont eléréséhez a Microsoft Entra-azonosítón keresztül kell hitelesítenie magát.

Feljegyzés

A api.loganalytics.io végpontot a következő váltja api.loganalytics.azure.comfel: . A api.loganalytics.io végpont továbbra is támogatott lesz az előre látható jövőben.

Hitelesítés demó API-kulccsal

Ha gyorsan szeretné megismerni az API-t a Microsoft Entra-hitelesítés nélkül, használja a bemutató munkaterületet mintaadatokkal, amelyek támogatják az API-kulcsok hitelesítését.

A lekérdezések a minta-munkaterületen való hitelesítéséhez és futtatásához használja DEMO_WORKSPACE {workspace-id} néven, és adja meg az API-kulcsot DEMO_KEY.

Ha az alkalmazásazonosító vagy az API-kulcs helytelen, az API-szolgáltatás 403-at (Tiltott) hibaüzenetet ad vissza.

Az API-kulcs DEMO_KEY három különböző módon adható át, attól függően, hogy fejlécet, URL-címet vagy alapszintű hitelesítést szeretne használni:

Egyéni fejléc: Adja meg az API-kulcsot az egyéni fejlécben X-Api-Key.
Lekérdezési paraméter: Adja meg az API-kulcsot az URL-paraméterben api_key.
Alapszintű hitelesítés: Adja meg az API-kulcsot felhasználónévként vagy jelszóként. Ha mindkettőt megadja, az API-kulcsnak a felhasználónévben kell lennie.

Ez a példa a fejléc munkaterület-azonosítóját és API-kulcsát használja:

    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"
    }

Nyilvános API-végpont

A nyilvános API-végpont a következő:

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

ahol:

api-version: Az API-verzió. Az aktuális verzió a "v1".
workspaceId: A munkaterület azonosítója.

A lekérdezés a kérelem törzsében lesz átadva.

Példa:

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

Hitelesítés beállítása

Az API eléréséhez regisztrálnia kell egy ügyfélalkalmazást a Microsoft Entra-azonosítóval, és jogkivonatot kell kérnie.

Alkalmazás regisztrálása a Microsoft Entra-azonosítóban.
Az alkalmazás áttekintő lapján válassza ki az API-engedélyeket.
Válassza az Engedély hozzáadása lehetőséget.
A szervezetem által használt API-kban keresse meg a Log Analyticset, és válassza a Log Analytics API-t a listából.
Válassza a Delegált engedélyek lehetőséget.
Jelölje be a Data.Read jelölőnégyzetet.
Jelölje be az Engedélyek hozzáadása lehetőséget.

Most, hogy az alkalmazás regisztrálva lett, és rendelkezik az API használatára vonatkozó engedélyekkel, hozzáférést kell adnia az alkalmazásnak a Log Analytics-munkaterülethez.

A Log Analytics-munkaterület áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget.
Válassza a Szerepkör-hozzárendelés hozzáadása lehetőséget.
Válassza ki az Olvasó szerepkört, majd válassza a Tagok lehetőséget.
A Tagok lapon válassza a Tagok kijelölése lehetőséget.
Írja be az alkalmazás nevét a Kiválasztás mezőbe.
Válassza ki az alkalmazást, és válassza a Kiválasztás lehetőséget.
Válassza az Áttekintés + hozzárendelés lehetőséget.
Miután befejezte az Active Directory beállítási és munkaterületi engedélyeit, kérjen egy engedélyezési jogkivonatot.

Feljegyzés

Ebben a példában az Olvasó szerepkört alkalmaztuk. Ez a szerepkör egyike a számos beépített szerepkörnek, és a szükségesnél több engedélyt is tartalmazhat. Részletesebb szerepkörök és engedélyek hozhatók létre. További információ: Log Analytics-munkaterületek hozzáférésének kezelése.

Engedélyezési jogkivonat kérése

Mielőtt hozzákezdene, győződjön meg arról, hogy rendelkezik a kérés sikeres végrehajtásához szükséges összes értékkel. Minden kéréshez a következőre van szükség:

A Microsoft Entra-bérlő azonosítója.
A munkaterület azonosítója.
Az alkalmazás Microsoft Entra-ügyfélazonosítója.
Az alkalmazás Microsoft Entra-ügyfélkódja.

A Log Analytics API három különböző Microsoft Entra ID OAuth2-folyamattal támogatja a Microsoft Entra-hitelesítést:

Ügyfél-hitelesítő adatok
Engedélyezési kód
Implicit

Ügyfél hitelesítő adatainak folyamata

Az ügyfél hitelesítő adatainak folyamatában a jogkivonatot a Log Analytics-végpont használja. Az alkalmazás Microsoft Entra-azonosítóban való regisztrálásakor az előző lépésben megadott hitelesítő adatokkal egyetlen kérés érkezik a jogkivonat fogadásához.

Használja az resource=https://api.loganalytics.azure.com parancsot.

Hitelesítési jogkivonat lekérése az alábbi módszerek bármelyikével:

parancssori felület
REST API
SDK

Jogkivonat kérésekor meg kell adnia egy paramétert resource . A resource paraméter a elérni kívánt erőforrás URL-címe.

A források között van többek között:

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

Jogkivonat lekérése REST-kéréssel

Jogkivonat lekéréséhez használja a következő REST API-hívást. Ez a kérés ügyfél-azonosítót és ügyfélkulcsot használ a kérés hitelesítéséhez. Az ügyfélazonosítót és az ügyfél titkos kódját az alkalmazás Microsoft Entra-azonosítóval való regisztrálásakor kapja meg a rendszer. További információ: Alkalmazás regisztrálása engedélyezési jogkivonatok lekéréséhez és API-k használatához

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'

A válasz törzse a következő formátumban jelenik meg:

{
    "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"
}

Jogkivonat lekérése az Azure CLI használatával

A parancssori felület használatával történő jogkivonat lekéréséhez használja az alábbi parancsot

az account get-access-token

További információ: az account get-access-token

Jogkivonat lekérése az SDK-k használatával

Az alábbi kódminták bemutatják, hogyan szerezhet be jogkivonatot:

C#
NodeJS
Python

C#

Az alábbi kód bemutatja, hogyan szerezhet be jogkivonatot az Azure használatával. Identitástár A kérelem hitelesítéséhez ügyfél-azonosítóra és titkos ügyfélkódra van szükség.

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;

Másik lehetőségként a DefaultAzureCredential osztály használatával is lekérheti a jogkivonatot. Ez a módszer az alapértelmezett Azure-hitelesítő adatokkal hitelesíti a kérést, és nem igényel ügyfél-azonosítót vagy ügyfélkulcsot.

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

A felügyelt identitást vagy a szolgáltatásnév hitelesítő adatait az alábbiak szerint is megadhatja:

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" }));

További információ: DefaultAzureCredential class

Node.js

A JavaScriptet és a NodeJS-t használó hitelesítéssel kapcsolatos információkért lásd : JavaScript-alkalmazások hitelesítése az Azure-szolgáltatásokban az Azure SDK for JavaScript használatával

Az alábbi kód bemutatja, hogyan szerezhet be jogkivonatot a DefaultAzureCredential osztály használatával. Ez a módszer az alapértelmezett Azure-hitelesítő adatokkal hitelesíti a kérést, és nem igényel ügyfél-azonosítót vagy ügyfélkulcsot.

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

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

Az osztály használatával InteractiveBrowserCredential is lekérheti a hitelesítő adatokat. Ez a módszer böngészőalapú hitelesítési felületet biztosít a felhasználóknak az Azure-szolgáltatásokkal való hitelesítéshez.

További információ: DefaultAzureCredential osztály és InteractiveBrowserCredential osztály

Másik lehetőségként használhatja a ClientSecretCredential osztályt egy jogkivonat lekéréséhez. Ehhez a metódushoz ügyfél-azonosítóra és titkos ügyfélkódra van szükség a kérelem hitelesítéséhez.

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");

További információ: ClientSecretCredential class

Python

from azure.identity import DefaultAzureCredential

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

További információ: DefaultAzureCredential osztály és InteractiveBrowserCredential osztály

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)

További információ: ClientSecretCredential class

Használja a jogkivonatot a Log Analytics-végpontra irányuló kérelmekben:

    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"
    }

Példaválasz:

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

Engedélyezési kódfolyamat

A fő támogatott OAuth2-folyamat engedélyezési kódokon keresztül történik. Ehhez a metódushoz két HTTP-kérés szükséges egy jogkivonat beszerzéséhez, amellyel meghívható az Azure Monitor Log Analytics API. Két URL-cím érhető el, kérésenként egy végponttal. Formátumukat a következő szakaszok ismertetik.

Engedélyezési kód URL-címe (GET-kérelem)

    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

Az engedélyezési URL-címre irányuló kérések esetén a client_id a Microsoft Entra-alkalmazás alkalmazásazonosítója, amelyet az alkalmazás tulajdonságainak menüjéből másolnak ki. A redirect_uri a kezdőlap/bejelentkezési URL-cím ugyanabból a Microsoft Entra-alkalmazásból. Ha egy kérés sikeres, ez a végpont átirányítja a regisztrációkor megadott bejelentkezési oldalra az URL-címhez fűzött engedélyezési kóddal. Lásd a következő példát:

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

Ezen a ponton beszerzett egy engedélyezési kódot, amelyet most kell kérnie egy hozzáférési jogkivonathoz.

Engedélyezési kód jogkivonatÁNAK URL-címe (POST-kérelem)

    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>

Minden érték megegyezik a korábbi értékekkel, néhány kiegészítéssel. Az engedélyezési kód ugyanaz a kód, amelyet az előző kérelemben kapott egy sikeres átirányítás után. A kód a Microsoft Entra alkalmazásból beszerzett kulccsal van kombinálva. Ha nem mentette a kulcsot, törölheti, és létrehozhat egy újat a Microsoft Entra alkalmazás menüjének Kulcsok lapján. A válasz egy JSON-sztring, amely a következő sémával rendelkező jogkivonatot tartalmazza. A tokenértékek esetében típusok jelennek meg.

Példa a válaszra:

    {
        "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"
    }

A válasz hozzáférési jogkivonat-része az, amit a Log Analytics API-nak mutat be a Authorization: Bearer fejlécben. A frissítési jogkivonatot a jövőben is használhatja egy új access_token beszerzéséhez, és refresh_token, ha elavult a fiókja. Ebben a kérésben a formátum és a végpont a következő:

    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>

Példa a válaszra:

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

Implicit kódfolyamat

A Log Analytics API támogatja az OAuth2 implicit folyamatot. Ehhez a folyamathoz csak egyetlen kérésre van szükség, de nem szerezhető be frissítési jogkivonat.

Implicit kód engedélyezési URL-címe

    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

A sikeres kérés átirányítja az átirányítási URI-t az URL-címben található jogkivonattal:

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

Ez a Authorization: Bearer access_token használható fejlécértékként, amikor a Log Analytics API-nak továbbítja a kérések engedélyezéséhez.

További információ

Az OAuth2 és a Microsoft Entra dokumentációját itt találja:

Megosztás a következőn keresztül: