Compartilhar via

Enviar 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 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.

Observação

A API do Coletor de Dados HTTP do Azure Monitor foi preterida e não estará mais funcional a partir de 14/09/2026. A funcionalidade foi substituída 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.

Captura de tela ilustrando a visão geral do HTTP Data Collector.

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.

Solicitar URI

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

Solicitar parâmetros de URI

Parâmetro Descrição
ID do Cliente 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 de solicitação

Cabeçalho Descrição
Autorização A assinatura de autorização. Mais adiante no 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 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 recurso-contexto. 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 no conjunto de dados que contém o timestamp do item de dados. Se você especificar um campo, seu conteúdo será usado para TimeGenerated. Se não especificares este campo, o valor padrão para TimeGenerated será 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. de Assinatura é um de Autenticação de Mensagem (HMAC) baseado em Hash 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 o SharedKey cadeia de caracteres de assinatura:

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
Booleano _b
Duplo _d
Data/hora _t
GUID (armazenado como uma cadeia de caracteres) _g

Observação

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_be string_s:

Captura de ecrã de um registo de exemplo 1.

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.

Captura de tela do registro de amostra 2.

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.

Captura de ecrã do registo de amostra 3.

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_se string_s. Nesta entrada, cada um dos valores iniciais é formatado como uma cadeia de caracteres:

Captura de ecrã do registro de amostra 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 incluir qualquer um destes nomes de propriedade:

  • inquilino
  • HoraGerada
  • 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 maior que 32 KB, os dados serão truncados.
  • Máximo recomendado de 50 campos para um determinado tipo. Este é um limite prático do ponto de vista da usabilidade e da experiência de pesquisa.
  • 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 Situação Código de erro Descrição
200 OK O pedido foi aceite com sucesso.
400 Pedido inválido InativoCliente O espaço de trabalho foi fechado.
400 Pedido inválido InvalidApiVersion A versão da API especificada não foi reconhecida pelo serviço.
400 Pedido inválido ID de Cliente Inválido O ID do espaço de trabalho especificado é inválido.
400 Pedido inválido InvalidDataFormat Um JSON inválido foi enviado. O corpo da resposta pode conter mais informações sobre como resolver o erro.
400 Pedido inválido InvalidLogType O tipo de log especificado continha caracteres especiais ou numéricos.
400 Pedido inválido VersãoDeAPIEmFalta A versão da API não foi especificada.
400 Pedido inválido TipoDeConteúdoEmFalta O tipo de conteúdo não foi especificado.
400 Mau pedido TipoDeLogAusente O tipo de log de valores necessário não foi especificado.
400 Pedido inválido TipoDeConteúdoNãoSuportado O tipo de conteúdo não foi definido como application/json.
403 Proibido Autorização Inválida 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 interno do servidor Erro Não Especificado O serviço encontrou um erro interno. Por favor, tente novamente o pedido.
503 Serviço Indisponível ServiçoIndisponível O serviço atualmente não está disponível para receber solicitações. Por favor, tente novamente o seu pedido.

Consultar dados

Para consultar dados enviados pela API do Coletor de Dados HTTP do Azure Monitor, procure registros cujo Type seja igual ao valor LogType que você especificou e anexou com _CL. Por exemplo, se você usasse 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:

  1. No portal do Azure, localize seu espaço de trabalho do Log Analytics.
  2. Selecione Agentes.
  3. À direita do ID do Espaço de Trabalho, selecione o ícone de Copiar e, em seguida, cole a ID como o valor da variável ID do Cliente.
  4. À direita da Chave Primária, selecione o ícone Copiar e, em seguida, cole o 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 Descrição 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.
  • Dados gerados em seu aplicativo, mas nã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 são mais frequentemente correlacionados com outros dados de aplicativos no Application Insights.
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 ficheiros para um Azure Blob Storage, onde os ficheiros 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.
  • Dados que não são necessariamente gerados numa aplicação instrumentada no Application Insights.
    Os exemplos incluem tabelas de pesquisa e de factos, dados de referência, estatísticas pré-agregadas e assim por diante.
  • Dados que serão cruzados com outros dados do Azure Monitor (Insights de Aplicação, outros tipos de dados de Logs do Monitor, Defender para a Nuvem, Insights de contentores e máquinas virtuais, e assim por diante).
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 de , incluindo arquivos de CSV, TSV e JSON.
  • Dados que não serão correlacionados com outros dados em Application Insights ou Monitor Logs.
  • Dados que exigem recursos avançados de ingestão ou processamento que não estão disponíveis atualmente nos Logs do Azure Monitor.

Próximos passos