Dostęp do interfejsu API usługi Azure Monitor Log Analytics

Żądanie zapytania można przesłać do obszaru roboczego przy użyciu punktu końcowego https://api.loganalytics.azure.comusługi Log Analytics usługi Azure Monitor. Aby uzyskać dostęp do punktu końcowego, musisz uwierzytelnić się za pomocą identyfikatora Entra firmy Microsoft.

Uwaga

Punkt api.loganalytics.io końcowy jest zastępowany przez api.loganalytics.azure.comelement . Punkt api.loganalytics.io końcowy będzie nadal obsługiwany w przyszłości.

Uwierzytelnianie przy użyciu klucza demonstracyjnego interfejsu API

Aby szybko eksplorować interfejs API bez uwierzytelniania firmy Microsoft, użyj demonstracyjnego obszaru roboczego z przykładowymi danymi, które obsługują uwierzytelnianie klucza interfejsu API.

Aby uwierzytelnić i uruchomić zapytania względem przykładowego obszaru roboczego, użyj polecenia DEMO_WORKSPACE {workspace-id} i przekaż klucz DEMO_KEYinterfejsu API .

Jeśli identyfikator aplikacji lub klucz interfejsu API jest niepoprawny, usługa interfejsu API zwraca błąd 403 (Zabronione).

Klucz DEMO_KEY interfejsu API można przekazać na trzy różne sposoby, w zależności od tego, czy chcesz użyć nagłówka, adresu URL, czy uwierzytelniania podstawowego:

• Nagłówek niestandardowy: podaj klucz interfejsu API w nagłówku X-Api-Keyniestandardowym .
• Parametr zapytania: podaj klucz interfejsu API w parametrze api_keyadresu URL .
• Uwierzytelnianie podstawowe: podaj klucz interfejsu API jako nazwę użytkownika lub hasło. Jeśli podasz oba te elementy, klucz interfejsu API musi znajdować się w nazwie użytkownika.

W tym przykładzie użyto identyfikatora obszaru roboczego i klucza interfejsu API w nagłówku:

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

Publiczny punkt końcowy interfejsu API

Publiczny punkt końcowy interfejsu API to:

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

gdzie:

• api-version: wersja interfejsu API. Bieżąca wersja to "v1".
• workspaceId: Identyfikator obszaru roboczego.

Zapytanie jest przekazywane w treści żądania.

Na przykład:

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

Konfigurowanie uwierzytelniania

Aby uzyskać dostęp do interfejsu API, należy zarejestrować aplikację kliencką przy użyciu identyfikatora Entra firmy Microsoft i zażądać tokenu.

1. Zarejestruj aplikację w identyfikatorze Entra firmy Microsoft.

2. Na stronie przeglądu aplikacji wybierz pozycję Uprawnienia interfejsu API.

3. Wybierz Dodaj uprawnienie.

4. Na karcie Interfejsy API używane przez moją organizację wyszukaj pozycję Log Analytics i wybierz z listy pozycję Interfejs API usługi Log Analytics.

   

5. Wybieranie delegowanych uprawnień.

6. Zaznacz pole wyboru Data.Read.

7. Wybierz Przyznaj uprawnienia.

   

Teraz, gdy aplikacja jest zarejestrowana i ma uprawnienia do korzystania z interfejsu API, przyznaj aplikacji dostęp do obszaru roboczego usługi Log Analytics.

1. Na stronie przeglądu obszaru roboczego usługi Log Analytics wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

2. Wybierz pozycję Dodaj przypisanie roli.

   

3. Wybierz rolę Czytelnik, a następnie wybierz pozycję Członkowie.

   

4. Na karcie Członkowie wybierz pozycję Wybierz członków.

5. Wprowadź nazwę aplikacji w polu Wybierz .

6. Wybierz aplikację i wybierz pozycję Wybierz.

7. Wybierz Przejrzyj + przypisz.

   

8. Po zakończeniu konfigurowania usługi Active Directory i uprawnień obszaru roboczego zażądaj tokenu autoryzacji.

Uwaga

W tym przykładzie zastosowano rolę Czytelnik. Ta rola jest jedną z wielu wbudowanych ról i może zawierać więcej uprawnień niż wymagane. Można utworzyć bardziej szczegółowe role i uprawnienia. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do obszarów roboczych usługi Log Analytics.

Żądanie tokenu autoryzacji

Przed rozpoczęciem upewnij się, że masz wszystkie wartości wymagane do pomyślnego wykonania żądania. Wszystkie żądania wymagają:

• Identyfikator dzierżawy entra firmy Microsoft.
• Identyfikator obszaru roboczego.
• Identyfikator klienta entra firmy Microsoft dla aplikacji.
• Wpis tajny klienta firmy Microsoft Entra dla aplikacji.

Interfejs API usługi Log Analytics obsługuje uwierzytelnianie firmy Microsoft Entra z trzema różnymi przepływami protokołu OAuth2 identyfikatora Entra firmy Microsoft:

• Poświadczenia klienta
• Kod autoryzacji
• Niejawnie

Przepływ poświadczeń klienta

W przepływie poświadczeń klienta token jest używany z punktem końcowym usługi Log Analytics. Jedno żądanie jest wykonywane w celu otrzymania tokenu przy użyciu poświadczeń podanych dla aplikacji w poprzednim kroku podczas rejestrowania aplikacji w identyfikatorze Entra firmy Microsoft.

Użyj witryny resource=https://api.loganalytics.azure.com.

Pobierz token uwierzytelniania przy użyciu dowolnej z następujących metod:

• Interfejs wiersza polecenia
• Interfejs API REST
• SDK

Podczas żądania tokenu należy podać resource parametr. Parametr resource jest adresem URL zasobu, do którego chcesz uzyskać dostęp.

Dostępne są m.in. następujące zasoby:

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

REST

Uzyskiwanie tokenu przy użyciu żądania REST

Użyj następującego wywołania interfejsu API REST, aby uzyskać token. To żądanie używa identyfikatora klienta i klucza tajnego klienta do uwierzytelniania żądania. Identyfikator klienta i klucz tajny klienta są uzyskiwane podczas rejestrowania aplikacji przy użyciu identyfikatora Entra firmy Microsoft. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji w celu żądania tokenów autoryzacji i pracy z interfejsami API

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'

Treść odpowiedzi jest wyświetlana w następującym formacie:

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

CLI

Uzyskiwanie tokenu przy użyciu interfejsu wiersza polecenia platformy Azure

Aby uzyskać token przy użyciu interfejsu wiersza polecenia, możesz użyć następującego polecenia

az account get-access-token 

Aby uzyskać więcej informacji, zobacz az account get-access-token

SDK

Uzyskiwanie tokenu przy użyciu zestawów SDK

W poniższych przykładach kodu pokazano, jak uzyskać token przy użyciu:

• C#
• NodeJS
• Python

C#

Poniższy kod pokazuje, jak uzyskać token przy użyciu platformy Azure. Biblioteka tożsamości Wymaga identyfikatora klienta i klucza tajnego klienta w celu uwierzytelnienia żądania.

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;

Alternatywnie możesz użyć klasy DefaultAzureCredential, aby uzyskać token. Ta metoda używa domyślnych poświadczeń platformy Azure do uwierzytelniania żądania i nie wymaga identyfikatora klienta ani klucza tajnego klienta.

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

Możesz również określić tożsamość zarządzaną lub poświadczenia jednostki usługi w następujący sposób:

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

Aby uzyskać więcej informacji, zobacz DefaultAzureCredential Class (Klasa DefaultAzureCredential)

Node.js

Aby uzyskać informacje na temat uwierzytelniania przy użyciu języków JavaScript i NodeJS, zobacz Jak uwierzytelniać aplikacje JavaScript w usługach platformy Azure przy użyciu zestawu Azure SDK dla języka JavaScript

Poniższy kod pokazuje, jak uzyskać token przy użyciu klasy DefaultAzureCredential. Ta metoda używa domyślnych poświadczeń platformy Azure do uwierzytelniania żądania i nie wymaga identyfikatora klienta ani klucza tajnego klienta.

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

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

Możesz również użyć InteractiveBrowserCredential klasy , aby uzyskać poświadczenia. Ta metoda zapewnia użytkownikom środowisko uwierzytelniania oparte na przeglądarce w celu uwierzytelniania za pomocą usług platformy Azure.

Aby uzyskać więcej informacji, zobacz DefaultAzureCredential Class (Klasa DefaultAzureCredential) i InteractiveBrowserCredential Class (Klasa DefaultAzureCredential) i InteractiveBrowserCredential Class (Klasa DefaultAzureCredential)

Alternatywnie możesz użyć klasy ClientSecretCredential, aby uzyskać token. Ta metoda wymaga identyfikatora klienta i klucza tajnego klienta w celu uwierzytelnienia żądania.

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

Aby uzyskać więcej informacji, zobacz ClientSecretCredential Class (Klasa ClientSecretCredential)

Python

Poniższy kod pokazuje, jak uzyskać token przy użyciu klasy DefaultAzureCredential. Ta metoda używa domyślnych poświadczeń platformy Azure do uwierzytelniania żądania i nie wymaga identyfikatora klienta ani klucza tajnego klienta.

from azure.identity import DefaultAzureCredential

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

Możesz również użyć InteractiveBrowserCredential klasy , aby uzyskać poświadczenia. Ta metoda zapewnia użytkownikom środowisko uwierzytelniania oparte na przeglądarce w celu uwierzytelniania za pomocą usług platformy Azure.

Aby uzyskać więcej informacji, zobacz DefaultAzureCredential Class (Klasa DefaultAzureCredential) i InteractiveBrowserCredential Class (Klasa DefaultAzureCredential) i InteractiveBrowserCredential Class (Klasa DefaultAzureCredential)

Alternatywnie możesz użyć klasy ClientSecretCredential, aby uzyskać token. Ta metoda wymaga identyfikatora klienta i klucza tajnego klienta w celu uwierzytelnienia żądania.

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)

Aby uzyskać więcej informacji, zobacz ClientSecretCredential Class (Klasa ClientSecretCredential)

Użyj tokenu w żądaniach do punktu końcowego usługi 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"
    }

Przykładowa odpowiedź:

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

Przepływ kodu autoryzacji

Obsługiwany jest główny przepływ OAuth2 za pomocą kodów autoryzacji. Ta metoda wymaga dwóch żądań HTTP w celu uzyskania tokenu, za pomocą którego należy wywołać interfejs API usługi Log Analytics usługi Azure Monitor. Istnieją dwa adresy URL z jednym punktem końcowym na żądanie. Ich formaty opisano w poniższych sekcjach.

Adres URL kodu autoryzacji (żądanie 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

Po wysłaniu żądania do autoryzowanego adresu URL client_id jest identyfikatorem aplikacji z aplikacji Microsoft Entra skopiowanym z menu właściwości aplikacji. Redirect_uri to adres URL strony głównej/logowania z tej samej aplikacji Microsoft Entra. Gdy żądanie zakończy się pomyślnie, ten punkt końcowy przekierowuje Cię do strony logowania podanej podczas rejestracji przy użyciu kodu autoryzacji dołączonego do adresu URL. Zobacz poniższy przykład:

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

Na tym etapie uzyskano kod autoryzacji, który jest teraz potrzebny do żądania tokenu dostępu.

Adres URL tokenu kodu autoryzacji (żądanie 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>

Wszystkie wartości są takie same jak poprzednio, z pewnymi dodatkami. Kod autoryzacji jest tym samym kodem otrzymanym w poprzednim żądaniu po pomyślnym przekierowaniu. Kod jest połączony z kluczem uzyskanym z aplikacji Microsoft Entra. Jeśli klucz nie został zapisany, możesz go usunąć i utworzyć nowy na karcie klucze w menu aplikacji Microsoft Entra. Odpowiedź jest ciągiem JSON zawierającym token z następującym schematem. Typy są wskazywane dla wartości tokenu.

Przykładowa odpowiedź:

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

Część tokenu dostępu tej odpowiedzi jest tym, co przedstawiasz interfejsowi API usługi Log Analytics w nagłówku Authorization: Bearer . Możesz również użyć tokenu odświeżania w przyszłości, aby uzyskać nowe access_token i refresh_token, gdy twoje dane przestaną być nieaktualne. W przypadku tego żądania format i punkt końcowy to:

    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>

Przykładowa odpowiedź:

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

Niejawny przepływ kodu

Interfejs API usługi Log Analytics obsługuje niejawny przepływ OAuth2. W przypadku tego przepływu wymagane jest tylko jedno żądanie, ale nie można uzyskać tokenu odświeżania.

Adres URL autoryzacji kodu niejawnego

    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

Pomyślne żądanie generuje przekierowanie do identyfikatora URI przekierowania przy użyciu tokenu w adresie URL:

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

Tego access_token można użyć jako wartości nagłówka po przekazaniu jej do interfejsu Authorization: Bearer API usługi Log Analytics w celu autoryzowania żądań.

Więcej informacji

Dokumentację dotyczącą protokołu OAuth2 w usłudze Microsoft Entra można znaleźć tutaj:

• Przepływ kodu autoryzacji entra firmy Microsoft
• Przepływ niejawnego udzielania w usłudze Microsoft Entra
• Przepływ poświadczeń klienta usługi Microsoft Entra S2S

Następne kroki

• Format żądania
• Format odpowiedzi
• Wykonywanie zapytań dotyczących dzienników dla zasobów platformy Azure
• Zapytania wsadowe