Acessar a API do Log Analytics do Azure Monitor

Artigo
11/05/2024

É possível enviar uma solicitação de consulta para um workspace usando o ponto de extremidade https://api.loganalytics.azure.com do Log Analytics no Azure Monitor. Para acessar o ponto de extremidade, é necessário autenticar-se por meio do Microsoft Entra ID.

Observação

O ponto de extremidade api.loganalytics.io está sendo substituído por api.loganalytics.azure.com. O ponto de extremidade api.loganalytics.io continuará a ter suporte no futuro.

Autenticação com uma chave de API de demonstração

Para explorar rapidamente a API sem a autenticação do Microsoft Entra, use o workspace de demonstração com os dados de amostra, que dá suporte à autenticação por chave de API.

Para autenticar-se e executar consultas no workspace de exemplo, use DEMO_WORKSPACE como a {workspace-id} e passe a chave de API DEMO_KEY.

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

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

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

Este exemplo usa a ID do workspace e a chave de 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 da API pública

O ponto de extremidade da API pública é:

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

em que:

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

A consulta é transmitida 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 usadas por minha organização, pesquise Log Analytics e selecione API do Log Analytics na lista.
Selecione Permissões delegadas.
Marque a caixa de seleção Dados.Leitura.
Selecione Adicionar Permissões.

Agora que o aplicativo está registrado e tem permissões para usar a API, conceda a ele acesso ao workspace do Log Analytics.

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

Observação

Neste 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 workspaces do Log Analytics.

Solicitar um token de autorização

Antes de começar, verifique se você tem todos os valores necessários para fazer a solicitação com sucesso. Todas as solicitações exigem:

Sua ID de locatário do Microsoft Entra.
A ID do workspace.
Sua ID de cliente do Microsoft Entra para o aplicativo.
Um segredo do cliente do Microsoft Entra para o aplicativo.

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

Credenciais do cliente
Código de Autorização
Implícita

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 o aplicativo na etapa anterior ao registrar um aplicativo no Microsoft Entra ID.

Use resource=https://api.loganalytics.azure.com.

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

CLI
API REST
.

Ao solicitar um token, você deve fornecer um parâmetro resource. O parâmetro resource é 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 da API REST para obter um token. Essa solicitação usa uma ID de 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. A biblioteca de identidade requer uma ID de 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 de cliente ou um 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 de entidade de serviço da seguinte forma:

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 o uso da autenticação 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 de cliente ou um 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 classe InteractiveBrowserCredential para obter as credenciais. Esse método fornece uma experiência de autenticação baseada em navegador para os usuários se autenticarem nos serviços do Azure.

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

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 DefaultAzureCredential Class e InteractiveBrowserCredential Class

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

O fluxo principal do OAuth2 com suporte é por meio 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 Log Analytics do Azure Monitor. Há duas URLs e um ponto de extremidade por solicitação. Seus formatos são descritos nas seções a seguir.

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

Ao fazer uma solicitação para a URL de autorização, o client_id é a ID do aplicativo do seu aplicativo Microsoft Entra, copiada do menu de propriedades do aplicativo. O redirect_uri é a URL da home page/logon do mesmo aplicativo Microsoft Entra. Quando uma solicitação é bem-sucedida, esse ponto de extremidade o redireciona para a página de logon fornecida na inscrição com o código de autorização acrescentado ao URL. Consulte o seguinte exemplo:

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

Aqui, você terá obtido um código de autorização e precisará solicitar um token de acesso.

URL do token de 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 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 você não salvou a chave, poderá excluí-la e criar uma nova na guia de chaves do menu do aplicativo 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 título Authorization: Bearer. Você também poderá usar o token de atualização no futuro para adquirir um novo access_token e refresh_token quando o seu ficar obsoleto. Para essa 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 também dá suporte ao fluxo implícito de OAuth2. Para esse fluxo, apenas uma solicitação é necessária, mas nenhum token de atualização poderá ser adquirido.

URL de autorização de código implícito

    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 produzirá um redirecionamento para o 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 cabeçalho Authorization: Bearer quando passado para a API do Log Analytics para autorizar solicitações.

Mais informações

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

Compartilhar via