Enviar dados de log para o Azure Monitor usando a API do Coletor de Dados HTTP (preterida)
Este artigo mostra como usar a API do Coletor de Dados HTTP para enviar dados de log para o Azure Monitor a partir de um cliente de API REST. Ele descreve como formatar dados coletados pelo seu script ou aplicativo, incluí-los em uma solicitação e ter essa solicitação autorizada pelo Azure Monitor. Fornecemos exemplos para Azure PowerShell, C# e Python.
Nota
A API do Coletor de Dados HTTP do Azure Monitor foi preterida e não estará mais funcional a partir de 14/09/2026. Ele foi substituído pela API de ingestão de logs.
Conceitos
Você pode usar a API do Coletor de Dados HTTP para enviar dados de log para um espaço de trabalho do Log Analytics no Azure Monitor de qualquer cliente que possa chamar uma API REST. O cliente pode ser um runbook na Automação do Azure que coleta dados de gerenciamento do Azure ou de outra nuvem, ou pode ser um sistema de gerenciamento alternativo que usa o Azure Monitor para consolidar e analisar dados de log.
Todos os dados no espaço de trabalho do Log Analytics são armazenados como um registro com um tipo de registro específico. Você formata seus dados para enviar para a API HTTP Data Collector como vários registros em JavaScript Object Notation (JSON). Quando você envia os dados, um registro individual é criado no repositório para cada registro na carga útil da solicitação.
Criar um pedido
Para usar a API do Coletor de Dados HTTP, crie uma solicitação POST que inclua os dados a serem enviados em JSON. As próximas três tabelas listam os atributos necessários para cada solicitação. Descrevemos cada atributo com mais detalhes mais adiante no artigo.
URI do pedido
Atributo | Property |
---|---|
Método | POST |
URI | https://< CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01> |
Tipo do conteúdo | application/json |
Solicitar parâmetros de URI
Parâmetro | Description |
---|---|
IDDeCliente | O identificador exclusivo do espaço de trabalho do Log Analytics. |
Recurso | O nome do recurso da API: /api/logs. |
Versão da API | A versão da API a ser usada com essa solicitação. Atualmente, a versão é 2016-04-01. |
Cabeçalhos do pedido
Cabeçalho | Description |
---|---|
Autorização | A assinatura de autorização. Mais adiante no artigo, você pode ler sobre como criar um cabeçalho HMAC-SHA256. |
Log-Tipo | Especifique o tipo de registro dos dados que estão sendo enviados. Ele pode conter apenas letras, números e o caractere sublinhado (_) e não pode exceder 100 caracteres. |
data-ms x | A data em que o pedido foi processado, no formato RFC 1123 . |
x-ms-AzureResourceId | A ID do recurso do Azure ao qual os dados devem ser associados. Ele preenche a propriedade _ResourceId e permite que os dados sejam incluídos em consultas de contexto de recurso. Se este campo não for especificado, os dados não serão incluídos nas consultas de contexto de recursos. |
campo gerado pelo tempo | O nome de um campo nos dados que contém o carimbo de data/hora do item de dados. Se você especificar um campo, seu conteúdo será usado para TimeGenerated. Se você não especificar esse campo, o padrão para TimeGenerated é a hora em que a mensagem é ingerida. O conteúdo do campo de mensagem deve seguir o formato ISO 8601 AAAA-MM-DDThh:mm:ssZ. O valor Tempo Gerado não pode ser mais antigo do que 2 dias antes da hora recebida ou mais de um dia no futuro. Nesse caso, será utilizado o tempo em que a mensagem for ingerida. |
Autorização
Qualquer solicitação para a API do Coletor de Dados HTTP do Azure Monitor deve incluir um cabeçalho de autorização. Para autenticar uma solicitação, assine a solicitação com a chave primária ou secundária do espaço de trabalho que está fazendo a solicitação. Em seguida, passe essa assinatura como parte da solicitação.
Aqui está o formato para o cabeçalho de autorização:
Authorization: SharedKey <WorkspaceID>:<Signature>
WorkspaceID é o identificador exclusivo do espaço de trabalho do Log Analytics. Assinatura é um código de autenticação de mensagem baseado em hash (HMAC) que é construído a partir da solicitação e, em seguida, calculado usando o algoritmo SHA256. Em seguida, codificá-lo usando a codificação Base64.
Use este formato para codificar a cadeia de caracteres de assinatura SharedKey :
StringToSign = VERB + "\n" +
Content-Length + "\n" +
Content-Type + "\n" +
"x-ms-date:" + x-ms-date + "\n" +
"/api/logs";
Aqui está um exemplo de uma cadeia de caracteres de assinatura:
POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs
Quando você tiver a cadeia de caracteres de assinatura, codifice-a usando o algoritmo HMAC-SHA256 na cadeia de caracteres codificada em UTF-8 e, em seguida, codifique o resultado como Base64. Use este formato:
Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))
Os exemplos nas próximas seções têm código de exemplo para ajudá-lo a criar um cabeçalho de autorização.
Corpo do pedido
O corpo da mensagem deve estar em JSON. Ele deve incluir um ou mais registros com o nome da propriedade e pares de valor no formato a seguir. O nome da propriedade pode conter apenas letras, números e o caractere sublinhado (_).
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Você pode agrupar vários registros em lote em uma única solicitação usando o seguinte formato. Todos os registos devem ser do mesmo tipo.
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
},
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Tipo de registo e propriedades
Você define um tipo de registro personalizado ao enviar dados por meio da API do Coletor de Dados HTTP do Azure Monitor. Atualmente, não é possível gravar dados em tipos de registro existentes que foram criados por outros tipos de dados e soluções. O Azure Monitor lê os dados de entrada e, em seguida, cria propriedades que correspondem aos tipos de dados dos valores inseridos.
Cada solicitação para a API do coletor de dados deve incluir um cabeçalho Log-Type com o nome do tipo de registro. O sufixo _CL é automaticamente anexado ao nome inserido para distingui-lo de outros tipos de log como um log personalizado. Por exemplo, se você inserir o nome MyNewRecordType, o Azure Monitor criará um registro com o tipo MyNewRecordType_CL. Isso ajuda a garantir que não haja conflitos entre nomes de tipo criados pelo usuário e aqueles fornecidos em soluções atuais ou futuras da Microsoft.
Para identificar o tipo de dados de uma propriedade, o Azure Monitor adiciona um sufixo ao nome da propriedade. Se uma propriedade contiver um valor nulo, a propriedade não será incluída nesse registro. Esta tabela lista o tipo de dados da propriedade e o sufixo correspondente:
Tipo de dados de propriedade | Sufixo |
---|---|
String | _s |
Boolean | _b |
Duplo | _d |
Data/hora | _t |
GUID (armazenado como uma cadeia de caracteres) | _g |
Nota
Os valores de cadeia de caracteres que parecem ser GUIDs recebem o sufixo _g e são formatados como um GUID, mesmo que o valor de entrada não inclua traços. Por exemplo, "8145d822-13a7-44ad-859c-36f31a84f6dd" e "8145d82213a744ad859c36f31a84f6dd" são armazenados como "8145d822-13a7-44ad-859c-36f31a84f6dd". As únicas diferenças entre esta e outra cadeia de caracteres são a _g no nome e a inserção de traços se eles não forem fornecidos na entrada.
O tipo de dados que o Azure Monitor usa para cada propriedade depende se o tipo de registro para o novo registro já existe.
- Se o tipo de registro não existir, o Azure Monitor criará um novo usando a inferência de tipo JSON para determinar o tipo de dados para cada propriedade do novo registro.
- Se o tipo de registro existir, o Azure Monitor tentará criar um novo registro com base nas propriedades existentes. Se o tipo de dados de uma propriedade no novo registro não corresponder e não puder ser convertido para o tipo existente, ou se o registro incluir uma propriedade que não existe, o Azure Monitor criará uma nova propriedade com o sufixo relevante.
Por exemplo, a seguinte entrada de envio criaria um registro com três propriedades, number_d, boolean_b e string_s:
Se você enviasse essa próxima entrada, com todos os valores formatados como strings, as propriedades não seriam alteradas. Você pode converter os valores em tipos de dados existentes.
Mas, se você fizer esse próximo envio, o Azure Monitor criará as novas propriedades boolean_d e string_d. Não é possível converter esses valores.
Se você enviar a seguinte entrada, antes que o tipo de registro seja criado, o Azure Monitor criará um registro com três propriedades, number_s, boolean_s e string_s. Nesta entrada, cada um dos valores iniciais é formatado como uma cadeia de caracteres:
Propriedades reservadas
As propriedades a seguir são reservadas e não devem ser usadas em um tipo de registro personalizado. Você receberá um erro se sua carga incluir qualquer um destes nomes de propriedade:
- tenant
- TimeGenerated
- RawData
Limites de dados
Os dados postados na API de coleta de dados do Azure Monitor estão sujeitos a determinadas restrições:
- Máximo de 30 MB por postagem na API do Azure Monitor Data Collector. Este é um limite de tamanho para uma única publicação. Se os dados de uma única postagem excederem 30 MB, você deve dividir os dados em blocos de tamanho menor e enviá-los simultaneamente.
- Máximo de 32 KB para valores de campo. Se o valor do campo for superior a 32 KB, os dados serão truncados.
- Máximo recomendado de 50 campos para um determinado tipo. Este é um limite prático de uma perspetiva de experiência de pesquisa e usabilidade.
- As tabelas nos espaços de trabalho do Log Analytics suportam apenas até 500 colunas (referidas como campos neste artigo).
- Máximo de 45 caracteres para nomes de colunas.
Códigos de devolução
O código de status HTTP 200 significa que a solicitação foi recebida para processamento. Isso indica que a operação foi concluída com êxito.
O conjunto completo de códigos de status que o serviço pode retornar está listado na tabela a seguir:
Código | Status | Código de erro | Description |
---|---|---|---|
200 | OK | O pedido foi aceite com sucesso. | |
400 | Solicitação inválida | InativoCliente | O espaço de trabalho foi fechado. |
400 | Solicitação inválida | InvalidApiVersion | A versão da API especificada não foi reconhecida pelo serviço. |
400 | Solicitação inválida | InvalidCustomerId | O ID do espaço de trabalho especificado é inválido. |
400 | Solicitação inválida | InvalidDataFormat | Um JSON inválido foi enviado. O corpo da resposta pode conter mais informações sobre como resolver o erro. |
400 | Solicitação inválida | InvalidLogType | O tipo de log especificado continha caracteres especiais ou numéricos. |
400 | Solicitação inválida | MissingApiVersion | A versão da API não foi especificada. |
400 | Solicitação inválida | MissingContentType | O tipo de conteúdo não foi especificado. |
400 | Solicitação inválida | MissingLogType | O tipo de log de valores necessário não foi especificado. |
400 | Solicitação inválida | UnsupportedContentType | O tipo de conteúdo não foi definido como application/json. |
403 | Proibido | InvalidAuthorization | O serviço não conseguiu autenticar o pedido. Verifique se o ID do espaço de trabalho e a chave de conexão são válidos. |
404 | Não Encontrado | O URL fornecido está incorreto ou a solicitação é muito grande. | |
429 | Demasiados pedidos | O serviço está enfrentando um alto volume de dados da sua conta. Por favor, tente novamente o pedido mais tarde. | |
500 | Erro de Servidor Interno | UnspecifiedError | O serviço encontrou um erro interno. Por favor, tente novamente o pedido. |
503 | Serviço Indisponível | ServiceUnavailable | O serviço atualmente não está disponível para receber solicitações. Por favor, tente novamente o seu pedido. |
Consultar os dados
Para consultar dados enviados pela API do Coletor de Dados HTTP do Azure Monitor, procure registros cujo Type seja igual ao valor LogType especificado e anexado com _CL. Por exemplo, se você usou MyCustomLog, retornaria todos os registros com MyCustomLog_CL
.
Pedidos de amostra
Nesta seção estão exemplos que demonstram como enviar dados para a API do Coletor de Dados HTTP do Azure Monitor usando várias linguagens de programação.
Para cada exemplo, defina as variáveis para o cabeçalho de autorização fazendo o seguinte:
- No portal do Azure, localize seu espaço de trabalho do Log Analytics.
- Selecione Agentes.
- À direita de ID do espaço de trabalho, selecione o ícone Copiar e cole o ID como o valor da variável ID do cliente.
- À direita da Chave Primária, selecione o ícone Copiar e cole a ID como o valor da variável Chave Compartilhada.
Como alternativa, você pode alterar as variáveis para o tipo de log e dados JSON.
# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"
# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""
# Create two records with the same set of properties to create
$json = @"
[{ "StringValue": "MyString1",
"NumberValue": 42,
"BooleanValue": true,
"DateValue": "2019-09-12T20:00:00.625Z",
"GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{ "StringValue": "MyString2",
"NumberValue": 43,
"BooleanValue": false,
"DateValue": "2019-09-12T20:00:00.625Z",
"GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@
# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
$xHeaders = "x-ms-date:" + $date
$stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource
$bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
$keyBytes = [Convert]::FromBase64String($sharedKey)
$sha256 = New-Object System.Security.Cryptography.HMACSHA256
$sha256.Key = $keyBytes
$calculatedHash = $sha256.ComputeHash($bytesToHash)
$encodedHash = [Convert]::ToBase64String($calculatedHash)
$authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
return $authorization
}
# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
$method = "POST"
$contentType = "application/json"
$resource = "/api/logs"
$rfc1123date = [DateTime]::UtcNow.ToString("r")
$contentLength = $body.Length
$signature = Build-Signature `
-customerId $customerId `
-sharedKey $sharedKey `
-date $rfc1123date `
-contentLength $contentLength `
-method $method `
-contentType $contentType `
-resource $resource
$uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"
$headers = @{
"Authorization" = $signature;
"Log-Type" = $logType;
"x-ms-date" = $rfc1123date;
"time-generated-field" = $TimeStampField;
}
$response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
return $response.StatusCode
}
# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType
Alternativas e considerações
Embora a API do Coletor de Dados deva cobrir a maioria das suas necessidades à medida que você coleta dados de forma livre nos Logs do Azure, você pode precisar de uma abordagem alternativa para superar algumas das limitações da API. Suas opções, incluindo as principais considerações, estão listadas na tabela a seguir:
Alternativa | Description | Mais adequado para |
---|---|---|
Eventos personalizados: ingestão nativa baseada em SDK no Application Insights | O Application Insights, geralmente instrumentado por meio de um SDK em seu aplicativo, oferece a capacidade de enviar dados personalizados por meio de eventos personalizados. |
|
API do coletor de dados nos logs do Azure Monitor | A API do Coletor de Dados nos Logs do Azure Monitor é uma maneira completamente aberta de ingerir dados. Todos os dados formatados em um objeto JSON podem ser enviados aqui. Depois de enviado, ele é processado e disponibilizado nos Logs do Monitor para ser correlacionado com outros dados nos Logs do Monitor ou com outros dados do Application Insights. É bastante fácil carregar os dados como arquivos em um blob de Armazenamento de Blob do Azure, onde os arquivos serão processados e, em seguida, carregados no Log Analytics. Para obter um exemplo de implementação, consulte Criar um pipeline de dados com a API do coletor de dados. |
|
Azure Data Explorer | O Azure Data Explorer, agora disponível ao público em geral, é a plataforma de dados que alimenta o Application Insights Analytics e o Azure Monitor Logs. Usando a plataforma de dados em sua forma bruta, você tem total flexibilidade (mas requer a sobrecarga de gerenciamento) sobre o cluster (RBAC (controle de acesso baseado em função) do Kubernetes, taxa de retenção, esquema e assim por diante). O Azure Data Explorer fornece muitas opções de ingestão, incluindo arquivos CSV, TSV e JSON . |
|
Próximos passos
Use a API de Pesquisa de Log para recuperar dados do espaço de trabalho do Log Analytics.
Saiba mais sobre como criar um pipeline de dados com a API do Coletor de Dados usando um fluxo de trabalho de Aplicativos Lógicos para o Azure Monitor.