Como registrar eventos nos Hubs de Eventos do Azure no Gerenciamento de API do Azure

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

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

Os Event Hubs do Azure são um serviço de entrada de dados altamente dimensionável, que pode ingerir milhões de eventos por segundo para que possa processar e analisar os quantidades enormes de dados produzidos pelos dispositivos e aplicações ligados. Os Hubs de Eventos atuam como a "porta de entrada" para um pipeline de eventos e, uma vez que os dados são coletados em um hub de eventos, eles podem ser transformados e armazenados usando qualquer provedor de análise em tempo real ou adaptadores de lote/armazenamento. Os Event Hubs desacoplam a produção de um fluxo de eventos do consumo desses eventos, para que os consumidores de eventos possam aceder aos eventos de acordo com seu próprio agendamento.

Nota

Atualmente, esse recurso não está disponível em espaços de trabalho.

Pré-requisitos

  • Uma instância de serviço de Gerenciamento de API. Se você não tiver uma, consulte Criar uma instância de serviço de Gerenciamento de API.
  • Um namespace e um hub de eventos dos Hubs de Eventos do Azure. Para obter etapas detalhadas, consulte Criar um namespace de Hubs de Eventos e um hub de eventos usando o portal do Azure.

    Nota

    O recurso Hubs de Eventos pode estar em uma assinatura diferente ou até mesmo em um locatário diferente do recurso de Gerenciamento de API

Configurar o acesso ao hub de eventos

Para registrar eventos no hub de eventos, você precisa configurar credenciais para acesso do Gerenciamento de API. O Gerenciamento de API suporta um dos dois mecanismos de acesso a seguir:

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

Nota

Sempre que possível, a Microsoft recomenda o uso de credenciais de identidade gerenciadas para maior segurança.

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

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

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

  2. Atribua a identidade à função de remetente de Dados dos Hubs de Eventos do Azure, com escopo para o namespace Hubs de Eventos ou para o hub de eventos usado para log. Para atribuir a função, use o portal do Azure ou outras ferramentas do Azure.

Opção 2: Configurar a cadeia de conexão dos Hubs de Eventos

Para criar uma cadeia de conexão de Hubs de Eventos, consulte Obter uma cadeia de conexão de Hubs de Eventos.

  • Você pode usar uma cadeia de conexão para o namespace Hubs de Eventos ou para o hub de eventos específico usado para registro em log do Gerenciamento de API.
  • A política de acesso compartilhado para a cadeia de conexão deve habilitar pelo menos as permissões de Envio .

Criar um registrador de gerenciamento de API

A próxima etapa é configurar um registrador em seu serviço de Gerenciamento de API para que ele possa registrar eventos no hub de eventos.

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

Você pode configurar um registrador de Gerenciamento de API para um hub de eventos usando credenciais de identidade gerenciadas atribuídas pelo sistema ou pelo usuário.

Logger com credenciais de identidade gerenciadas atribuídas pelo sistema

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

Use o API Management Logger - Create or Update REST API com o seguinte corpo de solicitação.

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

Logger com credenciais de identidade gerenciadas atribuídas pelo usuário

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

Use o API Management Logger - Create or Update REST API com o seguinte corpo de 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. Logger com credenciais de cadeia de conexão

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

Nota

Sempre que possível, a Microsoft recomenda configurar o registador com credenciais de identidade geridas. Consulte Configurar o registrador com credenciais de identidade gerenciadas, anteriormente neste artigo.

O exemplo a seguir usa o cmdlet New-AzApiManagementLogger para criar um registrador 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"

Configurar a política de log-to-eventhub

Depois que o registrador estiver configurado no Gerenciamento de API, você poderá configurar sua política de log no eventhub para registrar os eventos desejados. Por exemplo, use a log-to-eventhub política 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é sua instância de Gerenciamento de API.

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

  3. Selecione Todas as operações.

  4. Na parte superior do ecrã, selecione o separador Estrutura .

  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 inbound cursor na secção ou outbound política.

  7. Na janela à direita, selecione Políticas avançadas>Registrar no EventHub. Isso insere o log-to-eventhub modelo de declaração de política.

    <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 registrador que você criou na etapa anterior.
    2. Você pode usar qualquer expressão que retorne uma cadeia de caracteres como o valor do log-to-eventhub elemento. Neste exemplo, uma cadeia de caracteres no formato JSON contendo a data e a hora, o nome do serviço, a ID da solicitação, o endereço IP da solicitação e o nome da operação é registrada.

  8. Selecione Salvar para salvar a configuração de política atualizada. Assim que é salva, a política fica ativa e os eventos são registrados no hub de eventos designado.

Nota

O tamanho máximo de mensagem suportado que pode ser enviado para um hub de eventos a partir desta política de Gerenciamento de API é de 200 kilobytes (KB). 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 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 registrador envia eventos.
  2. Em Recursos, selecione a guia Dados do processo .
  3. No cartão Ativar informações em tempo real a partir de eventos, selecione Iniciar.
  4. Você deve ser capaz de visualizar o log na guia Visualização de entrada. Se os dados mostrados não forem atuais, selecione Atualizar para ver os eventos mais recentes.

Próximos passos