Condividi tramite

Come registrare eventi nell'Hub eventi di Azure in Gestione API di Azure

SI APPLICA A: tutti i livelli di Gestione API

Questo articolo descrive come registrare gli eventi di Gestione API usando Hub eventi di Azure.

Hub di eventi di Azure è un servizio di ingresso dati altamente scalabile che può inserire milioni di eventi al secondo in modo che è possibile elaborare e analizzare enormi quantità di dati generati per i dispositivi connessi e le applicazioni. Hub di eventi funge da "porta d'ingresso" per una pipeline di eventi e, dopo che i dati vengono raccolti in un hub di eventi, è possibile trasformarli e archiviarli usando qualsiasi provider di analisi in tempo reale o adattatori per l'invio in batch o l'archiviazione. Gli hub di eventi separano la produzione di un flusso di eventi dal consumo di questi eventi, in modo che i consumer di eventi può accedere agli eventi in base a una pianificazione.

Note

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

Prerequisiti

Configurare l'accesso all'hub eventi

Per registrare gli eventi nell'hub eventi, è necessario configurare le credenziali per l'accesso da Gestione API. Gestione API supporta uno dei due meccanismi di accesso seguenti:

  • Un'identità gestita per un'istanza di Gestione API (scelta consigliata)
  • Una stringa di connessione ad Hub eventi

Note

È consigliabile usare le credenziali dell'identità gestita, quando possibile, per una maggiore sicurezza.

Opzione 1: Configurare un'identità gestita di Gestione API

  1. Abilitare un'identità gestita per Gestione API assegnata dal sistema o assegnata dall'utente nell'istanza di Gestione API.

    • Se si abilita un'identità gestita assegnata dall'utente, prendere nota dell'Object ID dell'identità.

  2. Assegnare all'identità il ruolo Mittente dei dati di Hub eventi di Azure, con ambito dello spazio dei nomi di Hub eventi o dell'hub eventi usato per la registrazione. Per assegnare il ruolo, usare il portale di Azure o un altro strumento di Azure.

Opzione 2: Configurare una stringa di connessione di Hub eventi

Per creare una stringa di connessione ad Hub eventi vedere Ottenere una stringa di connessione ad Hub eventi.

  • È possibile usare una stringa di connessione per lo spazio dei nomi di Hub eventi o per l'hub eventi specifico usato per la registrazione da Gestione API.
  • I criteri di accesso condiviso per la stringa di connessione devono abilitare almeno le autorizzazioni Invia.

Creare un logger di Gestione API

Il passaggio successivo consiste nel configurare un logger nel servizio Gestione API, in modo che possa registrare eventi nell'hub eventi.

Creare e gestire logger di Gestione API usando direttamente l'API REST di Gestione API o usando altri strumenti, ad esempio Azure PowerShell, un file Bicep o un modello di Gestione risorse di Azure.

È possibile configurare un logger di Gestione API in un hub eventi usando credenziali di identità gestite assegnate dal sistema o assegnate dall'utente.

Creare un logger con credenziali di identità gestite assegnate dal sistema

Per i prerequisiti, vedere Configurare un'identità gestita di Gestione API.

Usare l'API REST Gestione API Logger - Creare o aggiornare con il corpo della richiesta seguente.

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

Creare un logger con credenziali di identità gestite assegnate dall'utente

Per i prerequisiti, vedere Configurare un'identità gestita di Gestione API.

Usare l'API REST Gestione API Logger - Creare o aggiornare con il corpo della richiesta seguente.

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

Opzione 2. Creare un logger con credenziali della stringa di connessione

Per i prerequisiti, vedere Configurare una stringa di connessione di Hub eventi.

Note

È consigliabile configurare il logger con credenziali di identità gestite, quando possibile. Vedere Configurare un logger con credenziali di identità gestite, più indietro in questo articolo.

L'esempio seguente usa il cmdlet New-AzApiManagementLogger per creare un logger in un hub eventi configurando una stringa di connessione.

# 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"

Configurare un criterio log-to-eventhub

Dopo aver configurato il logger in Gestione API, è possibile configurare i criteri log-to-eventhub per registrare gli eventi desiderati. Ad esempio, usare il criterio log-to-eventhub nella sezione dei criteri in ingresso per registrare le richieste o nella sezione dei criteri in uscita per registrare le risposte.

  1. Passare all'istanza di Gestione API.

  2. In API selezionare API e quindi selezionare l'API a cui si vuole aggiungere il criterio. In questo esempio si aggiungono dei criteri all'API Echo nel prodotto Unlimited.

  3. Nella scheda Progettazione selezionare Tutte le operazioni.

  4. Nel riquadro Elaborazione in ingresso o Elaborazione in uscita, selezionare il pulsante </> (editor del codice dei criteri). Per altre informazioni, vedere Come configurare o modificare i criteri.

  5. Posizionare il cursore nella sezione relativa ai criteri inbound o outbound.

  6. Selezionare Mostra frammenti nella parte superiore della scheda. Selezionare Advanced policies>Log to EventHub. Questa azione inserisce il log-to-eventhub modello di dichiarazione dei criteri.

    <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. Sostituire logger-id con il nome del logger creato nei passaggi precedenti.
    2. È possibile usare qualsiasi espressione che restituisce una stringa come valore dell'elemento log-to-eventhub . In questo esempio viene registrata una stringa in formato JSON contenente data e ora, nome del servizio, ID richiesta, indirizzo IP della richiesta e nome dell'operazione.

  7. Selezionare Salva per salvare la configurazione aggiornata dei criteri. Non appena viene salvata la configurazione, i criteri sono attivi e gli eventi vengono registrati nell'hub eventi designato.

Note

La dimensione massima supportata dei messaggi che può essere inviata a un hub eventi da questo criterio di Gestione API è di 200 kilobyte (KB). Se un messaggio inviato a un hub eventi è maggiore di 200 KB, viene troncato automaticamente e il messaggio troncato viene trasferito all'hub eventi. Per i messaggi di dimensioni maggiori, prendere in considerazione l'uso di Azure Storage con Gestione API come soluzione alternativa per oltrepassare il limite di 200 KB. Per ulteriori informazioni, vedere Inviare richieste a Azure Storage da l'API Management.

Visualizzare in anteprima il log in Hub eventi usando Analisi di flusso di Azure

È possibile visualizzare in anteprima il log in Hub eventi usando Query di Analisi di flusso di Azure.

  1. Nel portale di Azure passare all'hub eventi a cui il logger invia gli eventi.
  2. In Funzionalità selezionare Elabora dati.
  3. Nella scheda Abilita informazioni dettagliate in tempo reale dagli eventi selezionare Avvia.
  4. Dovrebbe essere possibile visualizzare in anteprima il log nella scheda Anteprima input. Se i dati visualizzati non sono aggiornati, selezionare Aggiorna per visualizzare gli eventi più recenti.

Contenuti correlati

  • Last updated on