Applications managées Azure avec notifications

Les notifications d’applications managées Azure permettent aux éditeurs d’automatiser des actions en fonction des événements du cycle de vie des instances de l’application managée. Les éditeurs peuvent spécifier un point de terminaison webhook de notification personnalisé pour recevoir des notifications d’événements sur les instances nouvelles et existantes de l’application managée. Les éditeurs peuvent configurer des workflows personnalisés au moment du provisionnement, des mises à jour et de la suppression de l’application.

Prise en main

Pour commencer à recevoir des notifications d’application managée, créez un point de terminaison HTTPS public. Spécifiez le point de terminaison lorsque vous publiez la définition de l’application de catalogue de services ou l’offre Place de marché Microsoft Azure.

Voici les étapes recommandées pour bien démarrer :

1. Créez un point de terminaison HTTPS public qui journalise les requêtes POST entrantes et retourne 200 OK.
2. Ajoutez le point de terminaison à la définition de l’application du catalogue de services ou à l’offre de la Place de marché Azure, comme expliqué plus loin dans cet article.
3. Créez une instance d’application managée qui fait référence à la définition de l’application ou à l’offre de la Place de marché Azure.
4. Vérifiez que les notifications sont bien reçues.
5. Activez l’autorisation, comme expliqué dans la section Authentification du point de terminaison plus loin dans cet article.
6. Suivez les instructions de la section Schéma de notification dans cet article pour analyser les requêtes de notification et implémenter votre logique métier basée sur la notification.

Ajouter des notifications de définition de l’application du catalogue de services

Les exemples suivants montrent comment ajouter un URI de point de terminaison de notification à l’aide du portail ou de l’API REST.

Portail Azure

Pour démarrer, voir Démarrage rapide : créer et publier une définition d’application managée Azure.

API REST

Notes

Vous ne pouvez fournir qu’un seul point de terminaison dans la propriété notificationEndpoints de la définition d’application managée.

{
  "properties": {
    "isEnabled": true,
    "lockLevel": "ReadOnly",
    "displayName": "Sample Application Definition",
    "description": "Notification-enabled application definition.",
    "notificationPolicy": {
      "notificationEndpoints": [
        {
            "uri": "https://isv.azurewebsites.net:1214?sig=unique_token"
        }
      ]
    },
    "authorizations": [
      {
        "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "roleDefinitionId": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
      },
    ...

Ajouter des notifications d’application managée de la Place de marché Azure

Pour plus d’informations, consultez Créer une offre d’application Azure.

Déclencheurs d’événement

Le tableau suivant décrit toutes les combinaisons possibles de eventType et provisioningState et leurs déclencheurs :

Type d’événement	ProvisioningState	Déclencheur pour la notification
PUT	Acceptée	Le groupe de ressources managé a été créé et projeté correctement après l’opération PUT de l’application (avant le lancement du déploiement dans le groupe de ressources managées).
PUT	Opération réussie	Le provisionnement complet de l’application managée a réussi après une opération PUT.
PUT	Échec	Échec de l’opération PUT de provisionnement d’une instance d’application à tout moment.
PATCH	Opération réussie	Après la réussite d’une opération PATCH sur l’instance d’application managée pour mettre à jour les balises, la stratégie d’accès JAT (juste-à-temps) ou l’identité managée.
DELETE	En cours de suppression	Dès que l’utilisateur lance une opération DELETE d’une instance d’application managée.
Suppression	Deleted	Après la suppression complète et réussie de l’application managée.
Suppression	Échec	Après une erreur pendant le processus de déprovisionnement qui bloque la suppression.

Schéma de notification

Lorsque vous créez votre point de terminaison webhook pour gérer les notifications, vous devez analyser la charge utile pour obtenir des propriétés importantes afin de pouvoir agir sur la notification. Les notifications d’application managée de catalogue de services et de Place de marché Azure fournissent un grand nombre des mêmes propriétés, mais il existe certaines différences. La propriété applicationDefinitionId s’applique uniquement au catalogue de services. Les propriétés billingDetails et plan s’appliquent uniquement à la Place de marché Azure.

Azure ajoute /resource à l’URI du point de terminaison de notification que vous avez fourni dans la définition d’application managée. Le point de terminaison webhook doit être capable de gérer les notifications sur l’URI /resource. Par exemple, si vous avez fourni un URI de point de terminaison de notification comme https://fabrikam.com, l’URI du point de terminaison webhook est https://fabrikam.com/resource.

Schéma de notification de l’application du catalogue de services

L’exemple suivant montre une notification du catalogue de services après le provisionnement réussi d’une instance d’application managée.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>"
}

Si un approvisionnement échoue, une notification avec les détails de l’erreur est envoyée au point de terminaison spécifié.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "applicationDefinitionId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applicationDefinitions/<appDefName>",
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}

Schéma de notification de l’application de la Place de marché Azure

L’exemple suivant montre une notification du catalogue de services après le provisionnement réussi d’une instance d’application managée.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Succeeded",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  }
}

Si un approvisionnement échoue, une notification avec les détails de l’erreur est envoyée au point de terminaison spécifié.

POST https://{your_endpoint_URI}/resource?{optional_parameter}={optional_parameter_value} HTTP/1.1

{
  "eventType": "PUT",
  "applicationId": "/subscriptions/<subId>/resourceGroups/<rgName>/providers/Microsoft.Solutions/applications/<applicationName>",
  "eventTime": "2019-08-14T19:20:08.1707163Z",
  "provisioningState": "Failed",
  "billingDetails": {
    "resourceUsageId": "<resourceUsageId>"
  },
  "plan": {
    "publisher": "publisherId",
    "product": "offer",
    "name": "skuName",
    "version": "1.0.1"
  },
  "error": {
    "code": "ErrorCode",
    "message": "error message",
    "details": [
      {
        "code": "DetailedErrorCode",
        "message": "error message"
      }
    ]
  }
}

Propriété	Description
eventType	Type d’événement ayant déclenché la notification. Par exemple PUT, PATCH et DELETE.
applicationId	Identificateur de ressource complet de l’application managée pour laquelle la notification a été déclenchée.
eventTime	Horodatage de l’événement ayant déclenché la notification. Date et heure au format UTC ISO 8601.
provisioningState	État de provisionnement de l’instance d’application managée. Par exemple Succeeded, Failed, Deleting, Deleted.
applicationDefinitionId	Spécifié uniquement pour les applications managées du catalogue de services. Représente l’identificateur de ressource complet de la définition d’application pour laquelle l’instance d’application managée a été provisionnée.
billingDetails	Spécifié uniquement pour les applications managées de la Place de marché Azure. Détails de facturation de l’instance d’application managée. Contient le resourceUsageId que vous pouvez utiliser pour interroger la Place de marché Azure afin d’obtenir des détails sur l’utilisation.
plan	Spécifié uniquement pour les applications managées de la Place de marché Azure. Représente l’éditeur, l’offre, la référence (SKU) et la version de l’instance de l’application managée.
error	Spécifié uniquement quand provisioningState est égal à Failed. Contient le code d’erreur, le message et les détails relatifs au problème à l’origine de l’échec.

Authentification du point de terminaison

Pour sécuriser le point de terminaison webhook et garantir l’authenticité de la notification :

1. Fournissez un paramètre de requête au-dessus de l’URI webhook, comme ceci : https://your-endpoint.com?sig=Guid. Avec chaque notification, vérifiez que le paramètre de requête sig a la valeur attendue Guid.
2. Émettez une opération GET sur l’instance d’application managée à l’aide de applicationId. Vérifiez que provisioningState correspond au provisioningState de la notification pour garantir la cohérence.

Nouvelles tentatives de notification

Le service de notification d’application managée attend une réponse 200 OK du point de terminaison webhook à la notification. Le service de notification effectue une nouvelle tentative si le point de terminaison webhook retourne un code d’erreur HTTP supérieur ou égal à 500, s’il retourne un code d’erreur 429 ou si le point de terminaison est temporairement inaccessible. Si le point de terminaison webhook n’est pas disponible sous 10 heures, le message de notification est abandonné et les nouvelles tentatives s’arrêtent.