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

Artigo
10/18/2023

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.

Use o ponto de https://api.loganalytics.azure.com extremidade.

URL do token de credenciais do cliente (solicitação POST)

    POST /<your-tenant-id>/oauth2/token
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=client_credentials
    &client_id=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

Uma solicitação bem-sucedida recebe um token de acesso na resposta:

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

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 do seu 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:

Share via