Applicazioni gestite di Azure con notifiche

Le notifiche delle applicazioni gestite di Azure consentono agli editori di automatizzare le azioni in base agli eventi del ciclo di vita delle istanze dell'applicazione gestita. Gli editori possono specificare un endpoint webhook di notifica personalizzato per ricevere notifiche degli eventi in relazione alle istanze di applicazioni gestite nuove ed esistenti. Gli editori possono configurare flussi di lavoro personalizzati al momento del provisioning, degli aggiornamenti e dell'eliminazione delle applicazioni.

Introduzione

Per iniziare a ricevere le notifiche dell'applicazione gestita, creare un endpoint HTTPS pubblico. Specificare l'endpoint quando si pubblica la definizione dell'applicazione del catalogo di servizi o l'offerta di Microsoft Azure Marketplace.

Ecco la procedura consigliata per iniziare rapidamente:

1. Creare un endpoint HTTPS pubblico che registra le richieste POST in ingresso e restituisce 200 OK.
2. Aggiungere l'endpoint alla definizione dell'applicazione del catalogo di servizi o all'offerta di Azure Marketplace, come illustrato più avanti in questo articolo.
3. Creare un'istanza di applicazione gestita che faccia riferimento alla definizione dell'applicazione o all'offerta di Azure Marketplace.
4. Verificare che le notifiche vengano ricevute.
5. Abilitare l'autorizzazione come illustrato nella sezione Autenticazione degli endpoint di questo articolo.
6. Seguire le istruzioni nella sezione Schema di notifica di questo articolo per analizzare le richieste di notifica e implementare la logica di business in base alla notifica.

Aggiungere le notifiche alla definizione di applicazione del catalogo di servizi

Gli esempi seguenti illustrano come aggiungere un URI dell'endpoint di notifica usando il portale o l'API REST.

Azure portal

Per iniziare, vedere Avvio rapido: Creare e pubblicare una definizione di applicazione gestita di Azure.

REST API

{
  "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"
      },
    ...

Aggiungere le notifiche all'applicazione gestita di Azure Marketplace

Per altre informazioni, vedere Creare un'offerta di applicazione di Azure.

Trigger di evento

La tabella seguente descrive tutte le possibili combinazioni di eventType e provisioningState e i relativi trigger:

Schema di notifica

Quando si crea l'endpoint webhook per gestire le notifiche, è necessario analizzare il payload per ottenere proprietà importanti per poi intervenire sulla notifica. Le notifiche delle applicazioni gestite del catalogo di servizi e di Azure Marketplace forniscono molte delle stesse proprietà, ma esistono alcune differenze. La proprietà applicationDefinitionId si applica solo al catalogo di servizi. Le proprietà billingDetails e plan si applicano solo ad Azure Marketplace.

Azure aggiunge /resource all'URI dell'endpoint di notifica fornito nella definizione di applicazione gestita. L'endpoint webhook deve essere in grado di gestire le notifiche nell'URI /resource. Ad esempio, se è stato specificato un URI dell'endpoint di notifica come https://fabrikam.com, l'URI dell'endpoint webhook sarà https://fabrikam.com/resource.

Schema di notifica delle applicazioni del catalogo di servizi

L'esempio seguente mostra una notifica del catalogo dei servizi dopo il provisioning di un'istanza dell'applicazione gestita.

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

Se il provisioning ha esito negativo, viene inviata una notifica con i dettagli dell'errore all'endpoint specificato.

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"
      }
    ]
  }
}

Schema di notifica delle applicazioni di Azure Marketplace

L'esempio seguente mostra una notifica del catalogo dei servizi dopo il provisioning di un'istanza dell'applicazione gestita.

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

Se il provisioning ha esito negativo, viene inviata una notifica con i dettagli dell'errore all'endpoint specificato.

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"
      }
    ]
  }
}

Autenticazione dell'endpoint

Per proteggere l'endpoint webhook e verificare l'autenticità della notifica:

1. Specificare un parametro di query all'inizio dell'URI del webhook, come questo: https://your-endpoint.com?sig=Guid. A ogni notifica, verificare che il parametro di query sig abbia il valore previsto Guid.
2. Eseguire un'operazione GET sull'istanza dell'applicazione gestita usando applicationId. Verificare che provisioningState corrisponda al valore di provisioningState della notifica per garantire la coerenza.

Ripetizione dei tentativi di notifica

Il servizio di notifica dell'applicazione gestita prevede una risposta 200 OK dall'endpoint webhook alla notifica. Il servizio di notifica ripete ulteriori tentativi se l'endpoint webhook restituisce un codice errore HTTP maggiore o uguale a 500, restituisce un codice errore 429 o se l'endpoint è temporaneamente non raggiungibile. Se l'endpoint webhook non diventa disponibile entro 10 ore, il messaggio di notifica viene eliminato e i tentativi vengono interrotti.