Aceder à API do Azure Monitor Log Analytics

2025-08-29

Você pode enviar uma solicitação de consulta para um espaço de trabalho usando o Azure Monitor Log Analytics https://api.loganalytics.azure.com. Para aceder ao ponto de extremidade, é necessário autenticar-se através do Microsoft Entra ID.

Nota

O endpoint api.loganalytics.io está a ser substituído pelo api.loganalytics.azure.com. O api.loganalytics.io ponto final continuará a ser suportado num futuro previsível.

Autenticar com uma chave de API de demonstração

Para explorar rapidamente a API sem autenticação do Microsoft Entra, utilize o espaço de trabalho de demonstração com dados de exemplo, que suporta autenticação por chave API.

Para autenticar e executar consultas no espaço de trabalho de amostra, utilize DEMO_WORKSPACE como o {workspace-id} e insira a chave da API DEMO_KEY.

Se o Application ID ou a chave da API estiverem incorretos, o serviço de API devolve um erro 403 (Proibido).

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

Cabeçalho Personalizado: Forneça a chave API no cabeçalho personalizado X-Api-Key.
Parâmetro de consulta: Forneça a chave da API no parâmetro de URL api_key.
Autenticação básica: Forneça a chave da API como nome de utilizador ou palavra-passe. Se fornecer ambos, a chave API deve estar no nome de utilizador.

Este exemplo utiliza o ID do espaço de trabalho 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 final de API pública

O ponto de extremidade da API pública é:

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.

Nota

A versão da API beta foi descontinuada. Para mais informações, veja Migrar do uso de APIs de consulta em lote e beta.

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

Por exemplo:

https://api.loganalytics.azure.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1

Body:
{
    "query": "Usage"
}

Configurar autenticação

Para aceder à API, regista uma aplicação cliente com o Microsoft Entra ID e solicita um token.

Registar uma aplicação no Microsoft Entra ID.
Na página de visão geral da aplicação, selecione API permissions.
Select Adicionar uma permissão.
No separador APIs utilizadas pela minha organização, procure por Log Analytics e selecione API de Log Analytics da lista.
Selecione Permissões delegadas.
Selecione a caixa de verificação Data.Read.
Selecione Adicionar permissões.

Agora que a sua aplicação está registada e tem permissões para utilizar a API, conceda à sua aplicação acesso ao seu espaço de trabalho do Log Analytics.

Na página de visão geral do seu espaço de trabalho do Log Analytics, selecione Controlo de acesso (IAM).
Selecionar Adicionar atribuição de função.
Selecione a função Reader e depois selecione Membros.
Na aba Membros, escolha Selecionar membros.
Introduza o nome da sua aplicação na caixa Select.
Selecione a sua app e escolha Selecionar.
Selecione Verificar + atribuir.
Após terminar a configuração do Active Directory e definir as permissões do espaço de trabalho, solicite um token de autorização.

Nota

Para este exemplo, aplicámos a função de Leitor. Este papel é um dos muitos papéis integrados e pode incluir mais permissões do que você necessita. Podem ser criados papéis e permissões mais granulares. Para mais informações, consulte Manage access to Log Analytics workspaces.

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. Todas as solicitações exigem:

O ID do inquilino do Microsoft Entra.
O ID do seu espaço de trabalho.
O ID do cliente do Microsoft Entra para a aplicação.
Um segredo do cliente do Microsoft Entra para a aplicação.

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

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

Fluxo de credenciais do cliente

No fluxo de credenciais de cliente, o token é utilizado com o ponto final do Log Analytics. Uma única solicitação é feita para receber um token usando as credenciais fornecidas para a sua aplicação no passo anterior ao registar uma aplicação no Microsoft Entra ID.

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

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

Interface de Linha de Comando (CLI)
API REST
SDK

Ao solicitar um token, é necessário fornecer um parâmetro resource. O parâmetro resource é o URL do recurso que você deseja aceder.

Recursos incluem:

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

Obtenha um token usando uma solicitação REST

Utilize a seguinte chamada de API REST para obter um token. Esta solicitação utiliza uma identificação de cliente e um segredo de cliente para autenticar a solicitação. O ID do cliente e o segredo do cliente são obtidos quando você regista a sua aplicação com o Microsoft Entra ID. Para mais informações, consulte Registar uma Aplicação 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"
}

Obtenha um token usando Azure CLI

Para obter um token usando a CLI, pode utilizar o seguinte comando

az account get-access-token

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

Obtenha um token usando os SDKs

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

C#
NodeJS
Píton

C#

O código seguinte mostra como obter um token utilizando o Azure. A biblioteca de identidade requer um ID de cliente e um segredo de cliente para autenticar o pedido.

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;

Alternativamente, pode utilizar a classe DefaultAzureCredential para obter um token. Este método utiliza as credenciais padrão do Azure para autenticar o pedido e não requer um ID de cliente ou segredo de cliente.

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

Também pode especificar a sua identidade gerida ou as credenciais do principal 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 mais informações, consulte DefaultAzureCredential Class

Node.js

Para obter informações sobre como usar JavaScript e NodeJS para autenticação, consulte Como autenticar aplicações JavaScript aos serviços Azure utilizando o Azure SDK para JavaScript.

O código seguinte demonstra como obter um token utilizando a classe DefaultAzureCredential. Este método utiliza as credenciais padrão do Azure para autenticar o pedido e não requer um ID de cliente ou segredo de cliente.

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

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

Também pode usar a classe InteractiveBrowserCredential para obter as credenciais. Este método oferece uma experiência de autenticação baseada em navegador para os utilizadores se autenticarem com os serviços do Azure.

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

Alternativamente, pode usar a classe ClientSecretCredential para obter um token. Este método requer um ID de cliente e uma chave secreta de 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 mais informações, consulte ClientSecretCredential Class

Píton

from azure.identity import DefaultAzureCredential

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

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

Alternativamente, pode usar a classe ClientSecretCredential para obter um token. Este método requer um ID de cliente e uma chave secreta de 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 mais informações, consulte a classe ClientSecretCredential.

Utilize o token em pedidos ao 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"
}

Exemplo de resposta:

{
    "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 principal fluxo do 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. Existem dois URLs, com um endpoint por pedido. Os seus formatos são descritos nas seguintes secções.

URL de código de autorização (requisiçã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 ao URL de autorização, o client_id é o ID da aplicação do seu aplicativo Microsoft Entra, copiado do menu de propriedades do aplicativo. O redirect_uri é o URL da página inicial/login da mesma aplicação Microsoft Entra. Quando uma solicitação é bem-sucedida, este endpoint redireciona-o para a página de início de sessão fornecida no registo 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, já obteve um código de autorização, que agora precisa para solicitar um token de acesso.

URL de token de código de autorização (requisiçã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 recebeu na solicitação anterior após um redirecionamento bem-sucedido. O código é combinado com a chave obtida na aplicação Microsoft Entra. Se não guardou a chave, pode eliminá-la e criar uma nova no separador de chaves do menu da aplicação Microsoft Entra. A resposta é uma string JSON que contém o token com o seguinte esquema. Os tipos são indicados para os valores do 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 desta resposta é o que apresenta à API do Log Analytics no cabeçalho Authorization: Bearer. Pode também usar o token de atualização no futuro para obter um novo token de acesso e um novo token de atualização quando os seus tiverem expirado. Para este pedido, o formato e o ponto final 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 OAuth2 implicit flow. Neste fluxo, apenas uma única solicitação é necessária, mas nenhum token de atualização pode ser adquirido.

URL de autorização por 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 gera um redirecionamento para o seu URI de redirecionamento com o token no URL.

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

Este access_token pode ser usado como valor do cabeçalho Authorization: Bearer quando é passado para a API do Log Analytics para autorizar pedidos.

Partilhar via

Aceder à API do Azure Monitor Log Analytics

Autenticar com uma chave de API de demonstração

Ponto final de API pública

Configurar autenticação

Solicitar um token de autorização

Fluxo de credenciais do cliente

Obtenha um token usando uma solicitação REST

Fluxo do código de autorização

URL de código de autorização (requisição GET)

URL de token de código de autorização (requisição POST)

Fluxo de código implícito

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

Mais informações

Próximos passos

Comentários

Recursos adicionais