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

  • Artigo

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. Hub de Eventos age como a "porta de entrada” para um pipeline de eventos e depois que os dados são coletados em um hub de eventos, ele pode ser transformado e armazenado 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.

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 cadeia de conexão dos Hubs de Eventos
  • Uma identidade gerenciada para sua instância de Gerenciamento de API.

Opção 1: Configurar a 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.

Opção 2: Configurar a identidade gerenciada do Gerenciamento de API

Observação

O uso de uma identidade gerenciada do Gerenciamento de API para registrar eventos em log em um hub de eventos tem suporte no Gerenciamento de API da versão 2022-04-01-preview ou posterior da API REST.

  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 ao usuário, anote a ID do Cliente 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 outras ferramentas do Azure.

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 agentes de Gerenciamento de API usando a API REST de Gerenciamento de API diretamente ou usando ferramentas, incluindo o Azure PowerShell, um modelo Bicep ou um modelo de Gerenciamento de Recursos do Azure.

Agente com credenciais de cadeia de conexão

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

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

# API Management service-specific details
$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"

Agente com credenciais de identidade gerenciada atribuídas pelo sistema

Para obter os pré-requisitos, consulte Configurar identidade gerenciada de Gerenciamento de API .

Use a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um agente para um hub de eventos com credenciais de identidade gerenciada atribuídas pelo sistema.

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

Agente com credenciais de identidade gerenciada atribuídas pelo usuário

Para obter os pré-requisitos, consulte Configurar identidade gerenciada de Gerenciamento de API .

Use a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um agente para um hub de eventos com credenciais de identidade gerenciada atribuídas pelo usuário.

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

Configurar a política de log para eventhub

Depois que o agente de log estiver configurado no Gerenciamento de API, você poderá configurar suas políticas log ao hub de eventos para registrar os eventos desejados em log. 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. Navegue até instância de Gerenciamento de API.

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

  3. Selecione Todas as operações.

  4. Na parte superior da tela, selecione a guia Design.

  5. Na janela Processamento de entrada ou Processamento de saída, selecione o ícone </> (editor de código). Para obter mais informações, consulte Como definir ou editar políticas.

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

  7. Na janela à direita, selecione Políticas avançadas>Log EventHub. Isso insere o modelo de instrução da 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.

  8. Selecione Salvar para salvar a configuração da política atualizada. Assim que for salva, a política estará ativa e os eventos serão registrados em log para o 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 os hub de eventos. Para mensagens maiores, considere usar o Armazenamento do Microsoft Azure com o Gerenciamento de API do Azure como uma solução alternativa para ignorar o limite de 200 KB. Mais detalhes podem ser encontrados neste artigo.

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, navegue até o hub de eventos para o qual o agente envia eventos.
  2. Em Recursos, selecione a guia 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.

Próximas etapas