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

Nota

È possibile specificare un solo endpoint nella proprietà notificationEndpoints della definizione di applicazione gestita.

{
  "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": "d6b7fbd3-4d99-43fe-8a7a-f13aef11dc18",
        "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:

EventType	ProvisioningState	Trigger per la notifica
PUT	Accettata	Il gruppo di risorse gestite è stato creato e proiettato correttamente dopo l'esecuzione dell'operazione PUT nell'applicazione (prima dell'avvio della distribuzione all'interno del gruppo di risorse gestite).
PUT	Completato	Provisioning completo dell'applicazione gestita completato dopo un'operazione PUT.
PUT	Non riuscito	Errore dell'operazione PUT per il provisioning dell'istanza dell'applicazione in qualsiasi momento.
PATCH	Completato	Dopo il corretto completamento di un'operazione PATCH nell'istanza dell'applicazione gestita per aggiornare i tag, i criteri di accesso JIT o l'identità gestita.
DELETE	Deleting	Non appena l'utente avvia un'operazione DELETE di un'istanza dell'app gestita.
DELETE	Eliminata	Dopo l'eliminazione completa e riuscita dell'applicazione gestita.
DELETE	Non riuscito	Dopo qualsiasi errore durante il processo di deprovisioning che blocca l'eliminazione.

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, verrà 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, verrà 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"
      }
    ]
  }
}

Proprietà	Descrizione
eventType	Tipo di evento che ha attivato la notifica. Ad esempio PUT, PATCH, DELETE.
applicationId	Identificatore completo della risorsa dell'applicazione gestita per cui è stata attivata la notifica.
eventTime	Timestamp dell'evento che ha attivato la notifica. Data e ora in formato UTC ISO 8601.
provisioningState	Stato di provisioning dell'istanza dell'applicazione gestita. Ad esempio, Riuscito, Non riuscito, In fase di eliminazione, Eliminato.
applicationDefinitionId	Specificato solo per le applicazioni gestite del catalogo di servizi. Rappresenta l'identificatore di risorsa completo della definizione di applicazione per cui è stato effettuato il provisioning dell'istanza dell'applicazione gestita.
billingDetails	Specificato solo per le applicazioni gestite di Azure Marketplace. Dettagli di fatturazione dell'istanza dell'applicazione gestita. Contiene l'ID resourceUsageId che è possibile usare per eseguire query su Azure Marketplace per ottenere informazioni dettagliate sull'utilizzo.
plan	Specificato solo per le applicazioni gestite di Azure Marketplace. Rappresenta l'editore, l'offerta, lo SKU e la versione dell'istanza dell'applicazione gestita.
error	Specificato solo quando provisioningState è Non riuscito. Contiene il codice errore, il messaggio e i dettagli del problema che ha causato l'errore.

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 ripeterà 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 verrà eliminato e i tentativi verranno interrotti.