Comment enregistrer des événements sur Azure Event Hubs dans Gestion des API Azure

  • Article

S’APPLIQUE À : Tous les niveaux de Gestion des API

Cet article décrit comment consigner les événements de Gestion des API à l’aide d’Azure Event Hubs.

Les concentrateurs d'événements Azure sont un service d'entrée de données hautement évolutif qui peut traiter des millions d'événements par seconde afin que vous puissiez traiter et analyser les grandes quantités de données générées par vos périphériques connectés et vos applications. Les concentrateurs d'événements fonctionnent comme la « porte d'entrée » d’un pipeline d’événements, et une fois que les données sont collectées dans un concentrateur d'événements, elles peuvent être transformées et stockées à l'aide de n'importe quel fournisseur d'analyse en temps réel ou d’adaptateurs de traitement par lot ou de stockage. Les concentrateurs d'événements dissocient la production d'un flux d'événements de la consommation de ces événements, de manière à ce que les consommateurs d'événements puissent accéder aux événements selon leur propre planification.

Prérequis

Configurer l’accès au hub d’événements

Pour enregistrer des événements dans l’Event Hub, vous devez configurer les informations d’identification pour l’accès à partir de Gestion des API. Gestion des API prend en charge l’un des deux mécanismes d’accès suivants :

  • Une chaîne de connexion Event Hubs
  • Une identité managée pour une instance du service Gestion des API.

Option 1 : Configurer la chaîne de connexion Event Hubs

Pour plus d’informations sur la chaîne de connexion Event Hubs, consultez Obtenir une chaîne de connexion Event Hubs.

  • Vous pouvez utiliser une chaîne de connexion pour l’espace de noms Event Hubs ou pour le hub d’événements spécifique que vous utilisez pour la journalisation à partir de Gestion des API.
  • La stratégie d’accès partagé pour la chaîne de connexion doit activer au moins les autorisations d’envoi.

Option 2 : Configurer l’identité managée Gestion des API

Notes

L’utilisation d’une identité managée Gestion des API pour la journalisation d’événements dans un hub d’événements est prise en charge dans la version 2022-04-01-preview ou ultérieure de l’API REST Gestion des API.

  1. Activez une identité managée affectée par le système ou par l’utilisateur pour Gestion des API dans votre instance Gestion des API.

    • Si vous activez une identité managée affectée par l’utilisateur, prenez note de l’ID client de l’identité.

  2. Attribuez à l’identité le rôle expéditeur de données Azure Event Hubs, limité à l’espace de noms Event Hubs ou au hub d’événements utilisé pour la journalisation. Pour attribuer le rôle, utilisez le portail Azure ou d’autres outils Azure.

Créer un enregistreur d’événements de gestion des API

Maintenant que vous disposez d’un hub d’événements, l’étape suivante consiste à configurer un enregistreur d’événements dans votre service Gestion des API afin qu’il puisse enregistrer des événements dans le hub d’événements.

Créez et gérez Gestion des API enregistreurs d’événements directement à l’aide de l’API REST Gestion des API ou à l’aide d’outils tels que Azure PowerShell, un modèle Bicep ou un modèle Azure Resource Management.

Enregistreur d’événements avec les informations d’identification de chaîne de connexion

Pour connaître les prérequis, consultez Configurer la chaîne de connexion Event Hubs.

L’exemple suivant utilise le cmdlet New-AzApiManagementLogger pour créer un enregistreur d’événements dans un hub d’événements en configurant une chaîne de connexion.

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

Enregistreur d’événements avec des informations d’identification d’identité managées affectées par le système

Pour connaître les prérequis, consultez Configurer l’identité managée Gestion des API.

Utilisez l’API REST Gestion des API ou un modèle Bicep ou ARM pour configurer un enregistreur d’événements sur un hub d’événements avec des informations d’identification d’identité managées affectées par le système.

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

Enregistreur d’événements avec des informations d’identification d’identité managées affectées par l’utilisateur

Pour connaître les prérequis, consultez Configurer l’identité managée Gestion des API.

Utilisez l’API REST Gestion des API ou un modèle Bicep ou ARM pour configurer un enregistreur d’événements sur un hub d’événements avec des informations d’identification d’identité managées affectées par l’utilisateur.

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

Configurer des stratégies log-to-eventhub

Une fois que votre journal est configuré dans Gestion des API, vous pouvez configurer votre stratégie log-to-eventhub pour enregistrer les événements de votre choix. Par exemple, utilisez la stratégie log-to-eventhub de la section stratégie entrante pour journaliser les demandes, ou dans la section stratégie sortante pour journaliser les réponses.

  1. Accédez à votre instance Gestion des API.

  2. Sélectionnez les API, puis sélectionnez l’API à ajouter la stratégie. Dans cet exemple, nous ajoutons une stratégie à l’API Echo dans le produit Illimité.

  3. Sélectionnez Toutes les opérations.

  4. En haut de l’écran, sélectionnez l’onglet Conception.

  5. Sélectionnez l’icône </> (éditeur de code) dans la fenêtre Traitement entrant ou Traitement sortant. Pour plus d’informations, consultez la section Guide pratique pour configurer ou modifier des stratégies.

  6. Placez votre curseur dans la section des stratégies inbound ou outbound.

  7. Dans la fenêtre de droite, sélectionnez Stratégies avancées>Consigner sur Event Hub. Cela permet d’insérer le modèle d’instruction de stratégie 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. Remplacez logger-id par le nom du fichier JSON que vous avez créé à l’étape précédente.
    2. Vous pouvez utiliser toute expression qui renvoie une chaîne en tant que valeur pour l’élément log-to-eventhub . Dans cet exemple, une chaîne dans le format JSON contenant la date et l’heure, le nom du service, l’ID de la requête, son adresse IP et le nom de l’opération est consignée.

  8. Cliquez sur Enregistrer pour enregistrer la mise à jour de la configuration de la stratégie. Dès qu’elle est enregistrée, la stratégie est active et les événements sont enregistrés dans l’Event Hub désigné.

Notes

La taille maximale des messages pris en charge pouvant être envoyée à un Event Hub par cette stratégie Gestion des API est de 200 kilooctets (ko). Si un message envoyé à un Event Hub dépasse 200 ko, il est automatiquement tronqué. Le message tronqué est ensuite transféré vers le hub d’événements. Pour les messages plus grands, envisagez d’utiliser le Stockage avec la Gestion des API Azure comme solution de contournement pour éviter la limite de 200 Ko. Vous trouverez plus de détails dans cet article.

Afficher un aperçu du journal dans Event Hubs à l’aide d’Azure Stream Analytics

Vous pouvez afficher un aperçu du journal dans Event Hubs à l’aide de requêtes Azure Stream Analytics.

  1. Dans le Portail Azure, accédez au Event Hub auquel le journal envoie des événements.
  2. Sous Fonctionnalités, sélectionnez l’onglet Traiter les données.
  3. Sur la vignette Activer des insights en temps réel à partir d’événements, sélectionnez Démarrer.
  4. Vous devez être en mesure d’afficher un aperçu du journal dans l’onglet Aperçu de l’entrée. Si les données qui apparaissent ne sont pas à jour, sélectionnez Actualiser pour afficher les événements les plus récents.

Étapes suivantes