Protokollieren von Ereignissen in Azure Event Hubs mit Azure API Management

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel wird beschrieben, wie Sie API Management-Ereignisse mithilfe von Azure Event Hubs protokollieren.

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 fungiert als „Eingangstür“ für eine Ereignispipeline. Nach der Erfassung in Event Hubs können Sie Daten mit einem beliebigen Echtzeit-Analyseanbieter oder mit Batchverarbeitungs-/Speicheradaptern umwandeln 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.

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 Event Hubs-Verbindungszeichenfolge
  • Eine verwaltete Identität für Ihre API Management-Instanz.

Option 1: 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.

Option 2: Konfigurieren einer verwalteten API Management-Identität

Hinweis

Die Verwendung einer verwalteten API Management-Identität zum Protokollieren von Ereignissen in einem Event Hub wird in der API Management REST-API-Version 2022-04-01-preview oder höher unterstützt.

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

    • Wenn Sie eine benutzerseitig zugewiesene verwaltete Identität aktivieren, notieren Sie sich die Client-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. Verwenden Sie zum Zuweisen der Rolle das Azure-Portal oder andere Azure-Tools.

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 Management-Protokollierungen, indem Sie die API Management REST-API direkt oder mithilfe von Tools wie Azure PowerShell, einer Bicep-Vorlage oder einer Azure Resource Management-Vorlage verwenden.

Protokollierung mit Verbindungszeichenfolgen-Anmeldeinformationen

Voraussetzungen finden Sie unter Konfigurieren einer Event Hubs-Verbindungszeichenfolge.

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

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

Protokollierung mit systemseitig zugewiesenen Anmeldeinformationen für verwaltete Identitäten

Voraussetzungen finden Sie unter Konfigurieren der verwalteten API Management-Identität.

Verwenden Sie die API Management REST-API oder eine Bicep- oder ARM-Vorlage, um eine Protokollierung für einen Event Hub mit Anmeldeinformationen für eine systemseitig zugewiesene verwaltete Identität zu konfigurieren.

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

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

Voraussetzungen finden Sie unter Konfigurieren der verwalteten API Management-Identität.

Verwenden Sie die API Management REST-API oder eine Bicep- oder ARM-Vorlage, um eine Protokollierung für einen Event Hub mit Anmeldeinformationen für eine benutzerseitig zugewiesene verwaltete Identität zu konfigurieren.

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

Konfigurieren der Richtlinie „log-to-eventhub“ (Protokollieren zum Event Hub)

Nachdem Sie die Protokollierung in API Management konfiguriert haben, können Sie Ihre Richtlinie log-to-eventhub (Protokollieren zum Event Hub) für die gewünschten Ereignisse konfigurieren. 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. Navigieren Sie zu Ihrer API Management-Instanz.

  2. Wählen Sie APIs 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 Alle Vorgänge aus.

  4. Wählen Sie oben auf dem Bildschirm die Registerkarte Entwurf aus.

  5. Wählen Sie im Fenster „Eingehenden Datenverkehr verarbeiten“ oder „Ausgehenden Datenverkehr verarbeiten“ das Symbol </> (Codeeditor) aus. Weitere Informationen finden Sie unter Einrichten oder Bearbeiten von Richtlinien.

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

  7. Wählen Sie im Fenster rechts die Optionen Erweiterte Richtlinien>Bei EventHub anmelden aus. Damit wird die Richtlinienanweisungsvorlage log-to-eventhub 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.

  8. Wählen Sie Speichern aus, um die aktualisierte Richtlinienkonfiguration zu speichern. Die Richtlinie ist sofort nach dem Speichern aktiv, und Ereignisse werden zum angegebenen 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). Ist eine an einen Event Hub gesendete Nachricht größer als 200 KB, wird sie automatisch gekürzt, und die gekürzte Nachricht wird an den Event Hub übertragen.

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. Navigieren Sie im Azure-Portal zu dem Event Hub, an den die Protokollierung Ereignisse sendet.
  2. Wählen Sie unter Featuresdie Registerkarte Daten verarbeiten 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 neuesten Ereignisse anzuzeigen.

Nächste Schritte