Compartilhar via

Como registrar eventos em log para Hubs de Eventos do Azure no Gerenciamento de API do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

Este artigo descreve como registrar eventos de Gerenciamento de API usando Os Hubs de Eventos do Azure.

Hub de Eventos do Azure é um serviço de entrada de dados altamente escalonável que pode incluir milhões de eventos por segundo, para que você possa processar e analisar grandes quantidades de dados produzidos por seus aplicativos e dispositivos conectados. Os Hubs de Eventos atuam como a "porta de entrada" para um pipeline de eventos, e após os dados serem coletados em um hub de eventos, você pode transformá-los e armazená-los usando qualquer provedor de análise em tempo real ou adaptadores de envio em lote/armazenamento. Hub de Eventos separa a produção de um fluxo de eventos do consumo desses eventos, para que os consumidores de eventos possam acessar os eventos em seu próprio cronograma.

Observação

Atualmente, esse recurso não está disponível em workspaces.

Pré-requisitos

Conceder acesso para o hub de eventos

Para registrar eventos no hub de eventos, você precisa configurar credenciais para acesso do Gerenciamento de API. O gerenciamento de API dá suporte a um dos dois seguintes mecanismos de acesso:

  • Uma identidade gerenciada para sua instância do Gerenciamento de API (recomendado).
  • Uma cadeia de conexão dos Hubs de Eventos

Observação

Recomendamos que você use as credenciais de identidade gerenciada, quando possível, para maior segurança.

Opção 1: Configurar uma identidade gerenciada do Gerenciamento de API

  1. Habilite uma identidade gerenciada atribuída pelo sistema ou pelo usuário para Gerenciamento de API em sua instância do API Management.

    • Se você habilitar uma identidade gerenciada atribuída pelo usuário, observe a ID do Objeto da identidade.

  2. Atribua a identidade à função de Remetente de dados do Hubs de Eventos do Azure, com escopo para o namespace dos Hubs de Eventos ou para o hub de eventos usado para registro em log. Para atribuir a função, use o portal do Azure ou outra ferramenta do Azure.

Opção 2: configurar uma cadeia de conexão dos Hubs de Eventos

Para obter mais informações sobre a cadeia de conexão dos Hubs de Eventos, consulte Obter uma cadeia de conexão dos Hubs de Eventos.

  • Você pode usar uma cadeia de conexão para o namespace dos Hubs de Eventos ou para o hub de eventos específico que você usa para fazer logon do Gerenciamento de API.
  • A política de acesso compartilhado da cadeia de conexão deve habilitar pelo menos as permissões Enviar.

Criar um agente de Gerenciamento de API

A próxima etapa será configurar um agente no seu serviço de Gerenciamento de API para que ele possa registrar eventos em log para o Hub de Eventos.

Crie e gerencie registradores de Gerenciamento de API usando a API REST de Gerenciamento de API diretamente ou usando outras ferramentas, como o Azure PowerShell, um arquivo Bicep ou um modelo de Gerenciamento de Recursos do Azure.

Você pode configurar um agente do Gerenciamento de API para um hub de eventos usando credenciais de identidade gerenciada atribuída pelo sistema ou pelo usuário.

Criar um registrador com credenciais de identidade gerenciada atribuídas pelo sistema

Para pré-requisitos, consulte Configurar uma identidade gerenciada do Gerenciamento de API.

Usar o membro da API REST Agente - Criar ou Atualizar do Gerenciamento de API com o seguinte corpo da solicitação.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with system-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

Criar um logger com credenciais de identidade gerenciada atribuídas pelo usuário

Para pré-requisitos, consulte Configurar uma identidade gerenciada do Gerenciamento de API.

Usar o membro da API REST Agente - Criar ou Atualizar do Gerenciamento de API com o seguinte corpo da solicitação.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "Event Hub logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

Opção 2. Criar um agente com credenciais de cadeia de conexão

Para pré-requisitos, consulte Configurar uma cadeia de conexão dos Hubs de Eventos.

Observação

Recomendamos que você configure o registrador com credenciais de identidade gerenciadas quando possível. Veja Configurar um registrador com credenciais de identidade gerenciada, anteriormente neste artigo.

O exemplo a seguir usa o cmdlet New-AzApiManagementLogger para criar um agente para um hub de eventos configurando uma cadeia de conexão.

# Details specific to API Management 
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

Configurar uma política de log para o Event Hub

Após o seu agente ser configurado no Gerenciamento de API, você pode configurar sua política log-to-eventhub para registrar os eventos desejados. Por exemplo, use a política log-to-eventhub na seção de política de entrada para registrar solicitações ou na seção de política de saída para registrar respostas.

  1. Vá para sua instância de Gerenciamento de API.

  2. Em APIs, selecione APIs e selecione a API à qual você deseja adicionar a política. Neste exemplo, estamos adicionando uma política para a API Echo API no produto Unlimited.

  3. Na guia Design , selecione Todas as operações.

  4. No painel processamento de entrada ou processamento de saída , selecione o <botão /> (Editor de código de política). Para obter mais informações, consulte Como definir ou editar políticas.

  5. Posicione o cursor na seção da política inbound ou outbound.

  6. Selecione Mostrar snippets na parte superior da guia. Selecione Políticas avançadas>Log para o EventHub. Essa ação insere o modelo de declaração de política log-to-eventhub.

    <log-to-eventhub logger-id="logger-id">
    @{
        return new JObject(
            new JProperty("EventTime", DateTime.UtcNow.ToString()),
            new JProperty("ServiceName", context.Deployment.ServiceName),
            new JProperty("RequestId", context.RequestId),
            new JProperty("RequestIp", context.Request.IpAddress),
            new JProperty("OperationName", context.Operation.Name)
        ).ToString();
    }
</log-to-eventhub>
    1. Substitua logger-id pelo nome do agente que você criou na etapa anterior.
    2. Você pode usar qualquer expressão que retorne uma cadeia de caracteres como o valor do elemento log-to-eventhub . Neste exemplo, uma cadeia de caracteres no formato JSON que contém a data e a hora, o nome do serviço, a ID da solicitação, endereço IP da solicitação e o nome da operação é registrada.

  7. Selecione Salvar para salvar a configuração da política atualizada. Assim que a configuração for salva, a política estará ativa e os eventos serão registrados no hub de eventos designado.

Observação

O tamanho máximo de mensagem com suporte que pode ser enviado a um hub de eventos dessa política do Gerenciamento de API é de 200 KB (quilobytes). Se uma mensagem enviada para um hub de eventos for maior que 200 KB, ela será truncada automaticamente e a mensagem truncada será transferida para o hub de eventos. Para mensagens maiores, considere usar o Armazenamento do Azure com o Gerenciamento de API como uma solução alternativa para ignorar o limite de 200 KB. Para obter mais informações, consulte Enviar solicitações para o Armazenamento do Azure do Gerenciamento de API.

Visualizar o log nos Hubs de Eventos usando o Azure Stream Analytics

Você pode visualizar o log nos Hubs de Eventos usando consultas do Azure Stream Analytics.

  1. No portal do Azure, vá para o Event Hub para o qual o logger envia eventos.
  2. Em Recursos, selecione Processar dados.
  3. No cartão Habilitar percepções em tempo real do evento, selecione Iniciar.
  4. Você deve ser capaz de visualizar o log na guia Visualização de entrada. Se os dados mostrados não estiverem atuais, selecione Atualizar para ver os eventos mais recentes.

Conteúdo relacionado

  • Last updated on