Aceder à API de Análise de Registos do Azure Monitor

Artigo
11/05/2024

Você pode enviar uma solicitação de consulta para um espaço de trabalho usando o ponto de extremidade https://api.loganalytics.azure.comdo Azure Monitor Log Analytics . Para acessar o ponto de extremidade, você deve autenticar por meio do Microsoft Entra ID.

Nota

O api.loganalytics.io ponto de extremidade está sendo substituído por api.loganalytics.azure.com. O api.loganalytics.io endpoint continuará a ser suportado num futuro previsível.

Autenticar com uma chave de API de demonstração

Para explorar rapidamente a API sem a autenticação do Microsoft Entra, use o espaço de trabalho de demonstração com dados de exemplo, que oferece suporte à autenticação de chave de API.

Para autenticar e executar consultas no espaço de trabalho de exemplo, use DEMO_WORKSPACE como {workspace-id} e passe a chave DEMO_KEYda API .

Se a ID do aplicativo ou a chave da API estiver incorreta, o serviço da API retornará um erro 403 (Proibido).

A chave DEMO_KEY da API pode ser passada de três maneiras diferentes, dependendo se você deseja usar um cabeçalho, a URL ou a autenticação básica:

Cabeçalho personalizado: forneça a chave da API no cabeçalho X-Api-Keypersonalizado.
Parâmetro de consulta: forneça a chave da API no parâmetro api_keyURL .
Autenticação básica: forneça a chave da API como nome de usuário ou senha. Se você fornecer ambos, a chave da API deverá estar no nome de usuário.

Este exemplo usa a ID do espaço de trabalho e a chave da API no cabeçalho:

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

Ponto de extremidade de API pública

O ponto de extremidade público da API é:

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

onde:

api-version: A versão da API. A versão atual é "v1".
workspaceId: seu ID do espaço de trabalho.

A consulta é passada no corpo da solicitação.

Por exemplo:

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

Configurar a autenticação

Para acessar a API, registre um aplicativo cliente com o Microsoft Entra ID e solicite um token.

Registre um aplicativo no Microsoft Entra ID.
Na página de visão geral do aplicativo, selecione Permissões de API.
Selecione Adicionar uma permissão.
Na guia APIs que minha organização usa, procure por Log Analytics e selecione Log Analytics API na lista.
Selecione Permissões delegadas.
Marque a caixa de seleção Data.Read .
Selecione Adicionar permissões.

Agora que seu aplicativo está registrado e tem permissões para usar a API, conceda ao aplicativo acesso ao espaço de trabalho do Log Analytics.

Na página de visão geral do espaço de trabalho do Log Analytics, selecione Controle de acesso (IAM).
Selecione Adicionar atribuição de função.
Selecione a função Leitor e, em seguida, selecione Membros.
Na guia Membros, escolha Selecionar membros.
Digite o nome do seu aplicativo na caixa Selecionar .
Selecione seu aplicativo e escolha Selecionar.
Selecione Rever + atribuir.
Depois de concluir a configuração do Ative Directory e as permissões do espaço de trabalho, solicite um token de autorização.

Nota

Para este exemplo, aplicamos a função Leitor. Essa função é uma das muitas funções internas e pode incluir mais permissões do que você precisa. Funções e permissões mais granulares podem ser criadas. Para obter mais informações, consulte Gerenciar o acesso a espaços de trabalho do Log Analytics.

Solicitar um token de autorização

Antes de começar, certifique-se de que tem todos os valores necessários para fazer o pedido com sucesso. Todos os pedidos requerem:

Sua ID de locatário do Microsoft Entra.
O ID do seu espaço de trabalho.
Sua ID de cliente do Microsoft Entra para o aplicativo.
Um segredo do cliente Microsoft Entra para o aplicativo.

A API do Log Analytics suporta a autenticação do Microsoft Entra com três fluxos diferentes do Microsoft Entra ID OAuth2 :

Credenciais de cliente
Código de autorização
Implícito

Fluxo de credenciais do cliente

No fluxo de credenciais do cliente, o token é usado com o ponto de extremidade do Log Analytics. Uma única solicitação é feita para receber um token usando as credenciais fornecidas para seu aplicativo na etapa anterior quando você registra um aplicativo no Microsoft Entra ID.

resource=https://api.loganalytics.azure.comUtilize.

Obtenha um token de autenticação usando qualquer um dos seguintes métodos:

CLI
API REST
SDK

Ao solicitar um token, você deve fornecer um resource parâmetro. O resource parâmetro é a URL do recurso que você deseja acessar.

Os recursos incluem:

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

Obter um token usando uma solicitação REST

Use a seguinte chamada à API REST para obter um token. Essa solicitação usa uma ID do cliente e um segredo do cliente para autenticar a solicitação. A ID do cliente e o segredo do cliente são obtidos quando você registra seu aplicativo com o Microsoft Entra ID. Para obter mais informações, consulte Registrar um aplicativo para solicitar tokens de autorização e trabalhar com APIs

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'

O corpo da resposta aparece no seguinte formato:

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

Obter um token usando a CLI do Azure

Para obter um token usando a CLI, você pode usar o seguinte comando

az account get-access-token

Para obter mais informações, consulte az account get-access-token

Obter um token usando os SDKs

Os exemplos de código a seguir mostram como obter um token usando:

C#
NodeJS
Python

C#

O código a seguir mostra como obter um token usando o Azure. Biblioteca de identidades Requer um ID do cliente e um segredo do cliente para autenticar a solicitação.

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;

Como alternativa, você pode usar a classe DefaultAzureCredential para obter um token. Esse método usa as credenciais padrão do Azure para autenticar a solicitação e não requer uma ID do cliente ou segredo do cliente.

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

Você também pode especificar sua identidade gerenciada ou credenciais da entidade de serviço da seguinte maneira:

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

Para obter mais informações, consulte DefaultAzureCredential Class

Node.js

Para obter informações sobre como usar JavaScript e NodeJS, consulte Como autenticar aplicativos JavaScript nos serviços do Azure usando o SDK do Azure para JavaScript

O código a seguir mostra como obter um token usando a classe DefaultAzureCredential. Esse método usa as credenciais padrão do Azure para autenticar a solicitação e não requer uma ID do cliente ou segredo do cliente.

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

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

Você também pode usar a InteractiveBrowserCredential classe para obter as credenciais. Esse método fornece uma experiência de autenticação baseada em navegador para que os usuários se autentiquem com os serviços do Azure.

Para obter mais informações, consulte Classe DefaultAzureCredential e Classe InteractiveBrowserCredential

Como alternativa, você pode usar a classe ClientSecretCredential para obter um token. Esse método requer uma ID do cliente e um segredo do cliente para autenticar a solicitação.

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

Para obter mais informações, consulte ClientSecretCredential Class

Python

from azure.identity import DefaultAzureCredential

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

Para obter mais informações, consulte Classe DefaultAzureCredential e Classe InteractiveBrowserCredential

Como alternativa, você pode usar a classe ClientSecretCredential para obter um token. Esse método requer uma ID do cliente e um segredo do cliente para autenticar a solicitação.

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)

Para obter mais informações, consulte ClientSecretCredential Class

Use o token em solicitações para o ponto de extremidade do 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"
    }

Resposta de exemplo:

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

Fluxo de código de autorização

O principal fluxo OAuth2 suportado é através de códigos de autorização. Esse método requer duas solicitações HTTP para adquirir um token com o qual chamar a API do Azure Monitor Log Analytics. Há duas URLs, com um ponto de extremidade por solicitação. Os seus formatos são descritos nas secções seguintes.

URL do código de autorização (solicitação 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

Quando uma solicitação é feita para a URL de autorização, o client_id é a ID do aplicativo Microsoft Entra, copiada do menu de propriedades do aplicativo. O redirect_uri é a página inicial/URL de login do mesmo aplicativo Microsoft Entra. Quando uma solicitação é bem-sucedida, esse ponto de extremidade redireciona você para a página de entrada fornecida na inscrição com o código de autorização anexado à URL. Veja o seguinte exemplo:

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

Neste ponto, você obteve um código de autorização, que agora precisa solicitar um token de acesso.

URL do token do código de autorização (solicitação 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>

Todos os valores são os mesmos de antes, com algumas adições. O código de autorização é o mesmo código que você recebeu na solicitação anterior após um redirecionamento bem-sucedido. O código é combinado com a chave obtida do aplicativo Microsoft Entra. Se não guardou a chave, pode eliminá-la e criar uma nova a partir do separador teclas do menu da aplicação Microsoft Entra. A resposta é uma cadeia de caracteres JSON que contém o token com o esquema a seguir. Os tipos são indicados para os valores de token.

Exemplo de resposta:

    {
        "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 parte do token de acesso dessa resposta é o que você apresenta à API do Log Analytics no Authorization: Bearer cabeçalho. Você também pode usar o token de atualização no futuro para adquirir um novo access_token e refresh_token quando o seu tiver ficado obsoleto. Para esta solicitação, o formato e o ponto de extremidade são:

    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>

Exemplo de resposta:

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

Fluxo de código implícito

A API do Log Analytics suporta o fluxo implícito OAuth2. Para esse fluxo, apenas uma única solicitação é necessária, mas nenhum token de atualização pode ser adquirido.

Código implícito autorizar 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

Uma solicitação bem-sucedida produz um redirecionamento para seu URI de redirecionamento com o token na URL:

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

Esse access_token pode ser usado como o valor do Authorization: Bearer cabeçalho quando é passado para a API do Log Analytics para autorizar solicitações.

Mais informações

Você pode encontrar documentação sobre OAuth2 com o Microsoft Entra aqui:

Partilhar via