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.

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 cadeia de conexão de 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 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 .

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

Nota

O uso de uma identidade gerenciada pelo Gerenciamento de API para registrar eventos em um hub de eventos é suportado na versão 2022-04-01-preview da API REST de Gerenciamento de API ou posterior.

  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.

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.

Logger com credenciais de cadeia de conexão

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

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"

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 a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um registrador em um hub de eventos com credenciais de identidade gerenciadas 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>"
    }
  }
}

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 a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um registrador em um hub de eventos com credenciais de identidade gerenciadas 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-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.

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