Partilhar via

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

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, depois que os dados são 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 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

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

Recomendamos que você use credenciais de identidade gerenciadas sempre que 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 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 objeto 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 outra ferramenta do Azure.

Opção 2: Configurar uma cadeia de conexão de 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 dos Event Hubs ou para o hub de eventos específico que utiliza para o registo a partir 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 outras ferramentas, como o Azure PowerShell, um arquivo 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.

Criar um registador com credenciais de identidade geridas atribuídas pelo sistema

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

Use o API Management Logger - Criar ou atualizar membro da API REST 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>"
    }
  }
}

Criar um registador com credenciais de identidade geridas atribuídas pelo utilizador

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

Use o API Management Logger - Criar ou atualizar membro da API REST 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. Criar um registrador com credenciais de cadeia de conexão

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

Nota

Recomendamos que você configure o registrador com credenciais de identidade gerenciadas quando possível. Consulte Configurar um 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.

# 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

Depois de configurar o seu logger no Gerenciamento de API, poderá configurar a sua política log-to-eventhub para registar 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. Vá para sua instância de Gerenciamento de API.

  2. Em APIs, selecione APIs e, em seguida, selecione a API à qual pretende adicionar a política. Neste exemplo, estamos adicionando uma política à API Echo 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 secção inbound ou outbound de política.

  6. Selecione Mostrar trechos na parte superior da guia. Selecione Políticas avançadas>Registrar no EventHub. Esta ação 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.

  7. Selecione Salvar para salvar a configuração de política atualizada. Assim que a configuração é 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 tiver mais de 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 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 a partir do Gerenciamento de API.

Pré-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 hub de eventos para o qual o registrador envia eventos.
  2. Em Recursos, selecione Processar dados.
  3. No cartão Ativar informações em tempo real a partir de eventos, selecione Iniciar.
  4. Deve conseguir visualizar o log no separador Visualização de entrada. Se os dados mostrados não forem atuais, selecione Atualizar para ver os eventos mais recentes.

Conteúdo relacionado

  • Last updated on