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

  • Articolo

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. Gli hub di eventi fungono da "porta principale" per una pipeline di eventi e una volta che i dati vengono raccolti in un hub di eventi, possono essere trasformati e archiviati con qualsiasi provider di analisi in tempo reale o adattatori di invio in batch/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.

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:

  • Una stringa di connessione ad Hub eventi
  • Un'identità gestita per un'istanza di Gestione API.

Opzione 1: Configurare una stringa di connessione ad 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.

Opzione 2: Configurare l'identità gestita di Gestione API

Nota

L'uso di un'identità gestita di Gestione API per la registrazione di eventi in un hub eventi è supportato nella versione dell'API REST di Gestione API 2022-04-01-preview o versione successiva.

  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'ID client dell'identità.

  2. Assegnare all'identità il ruolo di 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 altri strumenti di Azure.

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 strumenti che includono Azure PowerShell, un modello Bicep o un modello di Gestione risorse di Azure.

Logger con credenziali della stringa di connessione

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

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

# 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 con credenziali di identità gestita assegnata dal sistema

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

Usare l'API REST di Gestione API o un modello Bicep o ARM per configurare un logger in un hub eventi con credenziali di identità gestita assegnata dal 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 con credenziali di identità gestita assegnata dall'utente

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

Usare l'API REST di Gestione API o un modello Bicep o ARM per configurare un logger in un hub eventi con credenziali di identità gestita assegnata dall'utente.

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

Configurare il criterio log-to-eventhub

Dopo la configurazione del logger in Gestione API, è possibile configurare il criterio log-to-eventhubs in modo da 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. Selezionare le API, 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. Selezionare Tutte le operazioni.

  4. Nella parte superiore della schermata selezionare la scheda Progettazione.

  5. Nella finestra Elaborazione in ingresso o Elaborazione in uscita selezionare l'icona </> (editor di codice). Per altre informazioni, vedere Come configurare o modificare i criteri.

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

  7. Nella finestra di destra selezionare Criteri avanzati>Log to EventHub (Accedi a hub eventi). In questo modo viene inserito il modello di istruzione del criterio 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. 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.

  8. Selezionare Salva per salvare la configurazione aggiornata dei criteri. Immediatamente dopo il salvataggio, il criterio risulta attivo e gli eventi vengono registrati nell'hub eventi designato.

Nota

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, verrà troncato automaticamente e il messaggio troncato verrà trasferito all'hub eventi. Per i messaggi di dimensioni maggiori, provare a usare Archiviazione di Azure con Azure Gestione API come soluzione alternativa per ignorare il limite di 200 KB. Altri dettagli sono disponibili in questo articolo.

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 la scheda 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.

Passaggi successivi