Envie dados de log para o Azure Monitor usando a API do coletor de dados HTTP (preterida)

  • Artigo

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 API REST. Ele descreve como formatar dados coletados por 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.

Observação

A API do Coletor de Dados HTTP do Azure Monitor foi preterida e não será mais funcional a partir de 14/09/2026. Ela foi substituída pela API de ingestão de logs.

Conceitos

É possível usar a API do Coletor de Dados HTTP para enviar dados de log a 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 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 à API do coletor de dados HTTP como diversos registros em JSON (JavaScript Object Notation). Quando você envia os dados, um registro individual é criado no repositório de cada registro no conteúdo da solicitação.

Screenshot illustrating the HTTP Data Collector overview.

Criar uma solicitação

Para usar a API do coletor de dados HTTP, crie uma solicitação POST que inclua os dados que serão enviados em JSON. As próximas três tabelas listam os atributos que são necessários para cada solicitação. Descrevemos cada atributo em mais detalhes posteriormente neste artigo.

URI da solicitação

Atributo Propriedade
Método POST
URI https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Tipo de conteúdo aplicativo/json

Solicitar parâmetros de URI (Uniform Resource Identifier)

Parâmetro Descrição
CustomerID O identificador exclusivo do espaço de trabalho do Log Analytics.
Recurso O nome do recurso de API: /api/logs.
Versão da API A versão da API a ser usada com esta solicitação. Atualmente, a versão é 2016-04-01.

Cabeçalhos da solicitação

parâmetro Descrição
Autorização A assinatura de autorização. Posteriormente neste artigo, você pode ler sobre como criar um cabeçalho HMAC-SHA256.
Log-Type 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.
x-ms-date A data em que a solicitação foi processada, no formato RFC 1123.
x-ms-AzureResourceId A ID do recurso do Azure ao qual os dados devem ser associados. Preencherá a propriedade _ResourceId e permitirá 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 recurso.
time-generated-field O nome de um campo nos dados que contém o carimbo de data/hora do item de dados. Se você especificar um campo, o conteúdo dele será usado para TimeGenerated. Se esse campo não for especificado, o padrão para TimeGenerated será a hora em que a mensagem é incluída. O conteúdo do campo de mensagem deve seguir o formato ISO 8601 AAAA-MM-DDThh:mm:ssZ. O valor TimeGenerated não pode ter mais de 2 dias antes do horário recebido ou mais de um dia no futuro. Nesse caso, será utilizado o tempo em que a mensagem é ingerida.

Autorização

Todas as solicitações para a API do Coletor de Dados HTTP do Azure Monitor devem incluir um cabeçalho de autorização. Para autenticar uma solicitação, assine-a com a chave primária ou secundária do workspace que está fazendo a solicitação. Em seguida, passe essa assinatura como parte da solicitação.

Aqui está o formato do cabeçalho de autorização:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID é o identificador exclusivo do espaço de trabalho do Log Analytics. Signature é um HMAC (Código de Autenticação de Mensagem Baseado em Hash) que é criado com solicitação e é calculado usando o algoritmo SHA256. Em seguida, você o codifica 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, codifique-a usando o algoritmo HMAC-SHA256 na sequência de caracteres codificada em UTF-8 e codifique o resultado em Base64. Use este formato:

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

Os exemplos nas seções a seguir têm o código de exemplo para ajudá-lo a criar um cabeçalho de autorização.

Corpo da solicitação

O corpo da mensagem deve ser em JSON. Ele deve incluir um ou mais registros com os pares de nome e valor de propriedade 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 criar lotes de vários registros em uma única solicitação usando o formato a seguir. Todos os registros devem ser do mesmo tipo de registro.

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    },
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

Propriedades e o tipo de registro

Você define um tipo de registro personalizado quando envia dados por meio da API do Coletor de Dados HTTP do Azure Monitor. No momento, você não pode gravar dados em tipos de registro existentes que foram criados por outras soluções e tipos de dados. O Azure Monitor lê os dados recebidos 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 é acrescentado automaticamente 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 nenhum conflito entre os nomes de tipo criados pelo usuário e aqueles fornecidos nas 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 contém um valor nulo, a propriedade não é incluída nesse registro. Esta tabela lista o tipo de dados de propriedade e o sufixo correspondente:

Tipo de dados de propriedade Sufixo
Cadeia de caracteres _s
Booliano _b
Double _d
Data/hora _t
GUID (armazenado como uma cadeia de caracteres) _g

Observação

Os valores da cadeia de caracteres que parecem ser GUIDs recebem o sufixo _g e são formatados como 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 o _g no nome e a inserção de traços caso eles não sejam 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 de 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 no tipo existente, ou se o registro incluir uma propriedade que não existe, o Azure Monitor criará uma nova propriedade que tenha o sufixo relevante.

Por exemplo, a entrada de envio a seguir criaria um registro com três propriedades: number_d, boolean_b e string_s:

Screenshot of sample record 1.

Se você enviar esta próxima entrada, com todos os valores formatados como cadeias de caracteres, as propriedades não mudarão. É possível converter os valores em tipos de dados existentes.

Screenshot of sample record 2.

Mas, se você fizer este próximo envio, o Azure Monitor criará as novas propriedades boolean_d e string_d. Não é possível alterar esses valores.

Screenshot of sample record 3.

Se, em seguida, 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:

Screenshot of sample record 4.

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 útil incluir qualquer um destes nomes de propriedade:

  • locatário
  • TimeGenerated
  • RawData

Limites de dados

Os dados postados na API de coleta de dados do Azure Monitor estão sujeitos a certas restrições:

  • Máximo de 30 MB por post na API do Coletor de Dados do Azure Monitor. Este é um limite de tamanho para um único post. Se os dados de uma única postagem excederem 30 MB, divida-os em partes menores e envie-os simultaneamente.
  • Limite máximo de 32 KB para valores de campo. Se o valor do campo for maior do que 32 KB, os dados serão truncados.
  • É recomendado um máximo de 50 campos para um determinado tipo. Este é um limite prático de uma perspectiva de experiência de pesquisa e usabilidade.
  • Só há suporte nas tabelas em workspaces do Log Analytics para até 500 colunas (chamadas de campos neste artigo).
  • Máximo de 45 caracteres para nomes de colunas.

Códigos de retorno

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 do erro Descrição
200 OK A solicitação foi aceita com êxito.
400 Solicitação incorreta InactiveCustomer O workspace foi fechado.
400 Solicitação incorreta InvalidApiVersion A versão da API que você especificou não foi reconhecida pelo serviço.
400 Solicitação incorreta InvalidCustomerId A ID do workspace especificada é inválida.
400 Solicitação incorreta InvalidDataFormat Um JSON inválido foi enviado. O corpo da resposta pode conter mais informações sobre como resolver o erro.
400 Solicitação incorreta InvalidLogType O tipo de log especificado continha caracteres especiais ou numéricos.
400 Solicitação incorreta MissingApiVersion A versão da API não foi especificada.
400 Solicitação incorreta MissingContentType O tipo de conteúdo não foi especificado.
400 Solicitação incorreta MissingLogType O tipo de log de valor necessário não foi especificado.
400 Solicitação incorreta UnsupportedContentType O tipo de conteúdo não foi definido como aplicativo/json.
403 Proibido InvalidAuthorization O serviço falhou ao autenticar a solicitação. Verifique se a chave de conexão e a ID do workspace são válidos.
404 Não encontrado A URL fornecida está incorreta ou a solicitação é muito grande.
429 Número Excessivo de Solicitações O serviço está recebendo um alto volume de dados da sua conta. Tente fazer novamente a solicitação.
500 Erro interno do servidor UnspecifiedError O serviço encontrou um erro interno. Tente novamente a solicitação.
503 Serviço indisponível ServiceUnavailable No momento, o serviço está indisponível para receber solicitações. Tente novamente a sua solicitação.

Consultar dados

Para consultar os dados enviados pela API do coletor de dados HTTP do Azure Monitor, pesquise os registros cujoTipo é igual ao valor LogType especificado e anexado a _CL. Por exemplo, se você usar MyCustomLog, todos os registros serão retornados com MyCustomLog_CL.

Solicitações de exemplo

Nesta seção, há amostras 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 amostra, defina as variáveis para o cabeçalho de autorização fazendo o seguinte:

  1. No portal do Azure, localize seu espaço de trabalho do Log Analytics.
  2. Selecione Agentes.
  3. À direita da ID do workspace, selecione o ícone Copiar e cole a ID como o valor da variável ID do cliente.
  4. À 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 cubra a maioria de suas necessidades ao coletar dados de formato livre nos Logs do Azure, você pode exigir uma abordagem alternativa para superar algumas das limitações da API. Suas opções, incluindo considerações principais, estão listadas na tabela a seguir:

Alternativa Descrição Mais indicado para
Eventos personalizados: ingestão baseada em SDK nativo 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.
  • Esses dados são gerados em seu aplicativo, mas não são coletados pelo SDK por meio de um dos tipos de dados padrão (solicitações, dependências, exceções e assim por diante).
  • Dados que costumam ser correlacionados com outros dados de aplicativo no Application Insights.
API do Coletor de Dados em logs do Azure Monitor A API do Coletor de Dados em logs de Azure Monitor é uma maneira completamente aberta de ingerir dados. Todos os dados formatados em um objeto JSON podem ser enviados aqui. Depois de enviados, eles são processados e disponibilizados nos Logs do Monitor para correlação com outros dados nos Logs do Monitor ou outros dados do Application Insights.

É bastante fácil carregar os dados como arquivos em um blob do Armazenamento de Blobs do Azure, onde os arquivos serão processados e carregados para o Log Analytics. Para obter um exemplo de implementação, veja Criar um pipeline de dados com a API do coletor de dados.
  • Dados que não são necessariamente gerados em um aplicativo instrumentado no Application Insights.
    Os exemplos incluem tabelas de pesquisa e de fatos, dados de referência, estatísticas pré-agregadas e assim por diante.
  • Dados que serão referenciados entre outros dados do Azure Monitor (Aplicativo Insights, outros tipos de dados de Logs do Monitor, Defender para Nuvem, insights de contêiner e máquinas virtuais e assim por diante).
Azure Data Explorer O Azure Data Explorer, agora com disponibilidade geral pública, é a plataforma de dados que alimenta o Application Insights Analytics e os Logs do Azure Monitor. Ao usar a plataforma de dados na forma bruta, você tem flexibilidade completa (mas isso requer a sobrecarga do gerenciamento) sobre o cluster, com 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, como arquivos CSV, TSV e JSON.
  • Dados que não serão correlacionados com nenhum outro no Application Insights ou nos Logs do Monitor.
  • Dados que exigem ingestão avançada ou recursos de processamento que não estão disponíveis atualmente nos Logs do Azure Monitor.

Próximas etapas