Acessar a API do Log Analytics do Azure Monitor
É 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.
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 o ponto de extremidade https://api.loganalytics.azure.com.
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 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 homepage/login 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, pode 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:
- Fluxo de código de autorização do Microsoft Entra
- fluxo de concessão implícita do Microsoft Entra
- Fluxo de credenciais do cliente S2S do Microsoft Entra