Freigeben über

Protokollieren von Ereignissen in Azure Event Hubs mit Azure API Management

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird das Protokollieren von API-Verwaltungsereignissen mithilfe von Azure Event Hubs beschrieben.

Azure Event Hubs ist ein hochgradig skalierbarer Dateneingangsdienst, der Millionen von Ereignissen pro Sekunde erfassen kann. Auf diese Weise können Sie riesige Datenmengen verarbeiten und analysieren, die von vernetzten Geräten und Anwendungen erzeugt werden. Event Hubs fungieren als "Front door" für eine Ereignispipeline, und nachdem Daten in einem Event Hub gesammelt wurden, können Sie sie mithilfe eines beliebigen Echtzeitanalyseanbieters oder Batch-/Speicheradapters transformieren und speichern. Event Hubs entkoppelt die Erzeugung eines Datenstroms von Ereignissen von der Nutzung dieser Ereignisse, sodass Ereignisconsumer nach einem eigenen Zeitplan auf Ereignisse zugreifen können.

Hinweis

Dieses Feature ist derzeit in Arbeitsbereichen nicht verfügbar.

Voraussetzungen

Konfigurieren des Zugriffs auf den Event Hub

Um Ereignisse zum Event Hub zu protokollieren, müssen Sie Anmeldeinformationen für den Zugriff von API Management konfigurieren. API Management unterstützt einen der beiden folgenden Zugriffsmechanismen:

  • Eine verwaltete Identität für Ihre API Management-Instanz (empfohlen)
  • Eine Event Hubs-Verbindungszeichenfolge

Hinweis

Es wird empfohlen, nach Möglichkeit verwaltete Identitätsanmeldeinformationen für erhöhte Sicherheit zu verwenden.

Option 1: Konfigurieren einer verwalteten API-Verwaltungsidentität

  1. Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität für API Management in Ihrer API Management-Instanz.

    • Wenn Sie eine vom Benutzer zugewiesene verwaltete Identität aktivieren, notieren Sie sich die Objekt-ID der Identität.

  2. Weisen Sie der Identität die Rolle Azure Event Hubs-Datensender zu, die auf den Event Hubs-Namespace oder den für die Protokollierung verwendeten Event Hubs festgelegt ist. Um die Rolle zuzuweisen, verwenden Sie das Azure-Portal oder ein anderes Azure-Tool.

Option 2: Konfigurieren einer Event Hubs-Verbindungszeichenfolge

Um eine Event Hubs-Verbindungszeichenfolge zu erstellen, lesen Sie Abrufen einer Event Hubs-Verbindungszeichenfolge.

  • Sie können eine Verbindungszeichenfolge für den Event Hubs-Namespace oder für den spezifischen Event Hub verwenden, den Sie für die Protokollierung von API Management verwenden.
  • Die SAS-Richtlinie für die Verbindungszeichenfolge muss mindestens Berechtigungen für Senden aktivieren.

Erstellen eines API Management-Loggers

Der nächste Schritt besteht darin, eine Protokollierung in Ihrem API Management-Dienst zu konfigurieren, sodass er Ereignisse zum Event Hub protokollieren kann.

Erstellen und verwalten Sie API-Verwaltungsprotokollierer mithilfe der API-Verwaltungs-REST-API direkt oder mithilfe anderer Tools wie Azure PowerShell, einer Bicep-Datei oder einer Azure-Ressourcenverwaltungsvorlage.

Sie können einen API Management Logger für einen Event Hub konfigurieren, indem Sie entweder vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identitätsanmeldeinformationen verwenden.

Erstellen einer Protokollierung mit Anmeldeinformationen für eine systemseitig zugewiesene verwaltete Identität

Voraussetzungen finden Sie unter Konfigurieren einer verwalteten API-Verwaltungsidentität.

Verwenden Sie das REST-API-Element Protokollierung – Erstellen oder Aktualisieren von API Management mit dem folgenden Anforderungstext.

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

Erstellen einer Protokollierung mit Anmeldeinformationen für eine benutzerseitig zugewiesene verwaltete Identität

Voraussetzungen finden Sie unter Konfigurieren einer verwalteten API-Verwaltungsidentität.

Verwenden Sie das REST-API-Element Protokollierung – Erstellen oder Aktualisieren von API Management mit dem folgenden Anforderungstext.

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

Option 2. Erstellen einer Protokollierung mit Anmeldeinformationen für die Verbindungszeichenfolge

Voraussetzungen finden Sie unter Konfigurieren einer Event Hubs-Verbindungszeichenfolge.

Hinweis

Es wird empfohlen, den Logger nach Möglichkeit mit verwalteten Identitätsanmeldeinformationen zu konfigurieren. Weitere Informationen finden Sie unter Konfigurieren eines Loggers mit verwalteten Identitätsanmeldeinformationen weiter oben in diesem Artikel.

Im folgenden Beispiel wird das Cmdlet New-AzApiManagementLogger verwendet, um eine Protokollierung zu einem Event Hub zu erstellen, indem eine Verbindungszeichenfolge konfiguriert wird.

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

Konfigurieren einer Protokoll-zu-EventHub-Richtlinie

Nachdem Ihr Logger in der API-Verwaltung konfiguriert wurde, können Sie Ihre Log-to-EventHub-Richtlinie so konfigurieren, dass die gewünschten Ereignisse protokolliert werden. Verwenden Sie beispielsweise die log-to-eventhub-Richtlinie im Abschnitt für eingehenden Datenverkehr der Richtlinie, um Anforderungen zu protokollieren, oder im Abschnitt für ausgehenden Datenverkehr der Richtlinie, um Antworten zu protokollieren.

  1. Wechseln Sie zu Ihrer API-Verwaltungsinstanz.

  2. Wählen Sie unter APIsAPIs aus, und wählen Sie dann die API aus, der Sie die Richtlinie hinzufügen möchten. In diesem Beispiel fügen wir die Richtlinie zur Echo-API im Produkt Unlimited hinzu.

  3. Wählen Sie auf der Registerkarte " Entwurf " die Option "Alle Vorgänge" aus.

  4. Wählen Sie im Bereich "Eingehende Verarbeitung " oder " Ausgehende Verarbeitung " die <Schaltfläche /> (Richtliniencode-Editor) aus. Weitere Informationen finden Sie unter Einrichten oder Bearbeiten von Richtlinien.

  5. Positionieren Sie den Cursor im Richtlinienabschnitt inbound oder outbound.

  6. Wählen Sie „Codeausschnitte anzeigen“ oben auf der Registerkarte aus. Wählen Sie „Erweiterte Richtlinien“> bei EventHub protokollieren aus. Mit dieser Aktion wird die log-to-eventhub-Richtlinienausweisungsvorlage eingefügt.

    <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. Ersetzen Sie logger-id durch den Namen der Protokollierung, die Sie im vorherigen Schritt erstellt haben.
    2. Sie können jeden Ausdruck verwenden, der eine Zeichenfolge als Wert für das Element log-to-eventhub zurückgibt. In diesem Beispiel wird eine Zeichenfolge im JSON-Format protokolliert, die das Datum, die Uhrzeit, den Dienstnamen, die Anforderungs-ID, die IP-Adresse der Anforderung und den Vorgangsnamen enthält.

  7. Wählen Sie Speichern aus, um die aktualisierte Richtlinienkonfiguration zu speichern. Sobald die Konfiguration gespeichert wird, ist die Richtlinie aktiv, und Ereignisse werden beim vorgesehenen Event Hub protokolliert.

Hinweis

Die maximal unterstützte Nachrichtengröße, die von dieser API Management-Richtlinie an einen Event Hub gesendet werden kann, beträgt 200 Kilobyte (KB). Wenn eine Nachricht, die an einen Event Hub gesendet wird, größer als 200 KB ist, wird sie automatisch abgeschnitten, und die abgeschnittene Nachricht wird an den Ereignishub übertragen. Für größere Nachrichten sollten Sie Azure Storage mit API-Verwaltung als Problemumgehung verwenden, um den Grenzwert von 200 KB zu umgehen. Weitere Informationen finden Sie unter Senden von Anforderungen an Azure Storage aus der API-Verwaltung.

Anzeigen einer Vorschau des Protokolls in Event Hubs mithilfe von Azure Stream Analytics

Sie können eine Vorschau des Protokolls in Event Hubs anzeigen, indem Sie Azure Stream Analytics-Abfragen verwenden.

  1. Wechseln Sie im Azure-Portal zum Event Hub, an den der Logger Ereignisse sendet.
  2. Wählen Sie unter "Features"die Option "Prozessdaten" aus.
  3. Wählen Sie auf der Karte Echtzeiterkenntnisse von Ereignissen aktivieren die Option Start aus.
  4. Sie sollten in der Lage sein, die Vorschau des Protokolls auf der Registerkarte Eingabevorschau anzuzeigen. Wenn die angezeigten Daten nicht aktuell sind, wählen Sie Aktualisieren aus, um die aktuellen Ereignisse anzuzeigen.

Verwandte Inhalte

  • Last updated on