Aplicaciones administradas de Azure con notificaciones

Las notificaciones de aplicaciones administradas de Azure permiten a los publicadores automatizar acciones basadas en eventos del ciclo de vida de las instancias de la aplicación administrada. Los publicadores pueden especificar un punto de conexión de webhook de notificación personalizado para recibir notificaciones de eventos sobre las instancias de aplicaciones administradas nuevas y existentes. Los publicadores pueden configurar flujos de trabajo personalizados en el momento del aprovisionamiento, las actualizaciones y la eliminación de la aplicación.

Introducción

Para empezar a recibir notificaciones de aplicaciones administradas, cree un punto de conexión HTTPS público. Especifique el punto de conexión al publicar la definición de aplicación del catálogo de servicios o la oferta de Microsoft Azure Marketplace.

Estos son los pasos recomendados para empezar a usarlas rápidamente:

1. Cree un punto de conexión HTTPS público que registre las solicitudes POST entrantes y devuelva 200 OK.
2. Agregue el punto de conexión a la definición de aplicación de catálogo de servicios o a la oferta de Azure Marketplace, como se explica más adelante en este artículo.
3. Cree una instancia de aplicación administrada que haga referencia a la definición de la aplicación o a la oferta de Azure Marketplace.
4. Confirme que las notificaciones se reciben.
5. Habilite la autorización tal y como se explica en la sección Autenticación de punto de conexión de este artículo.
6. Siga las instrucciones de la sección Esquema de notificación de este artículo para analizar las solicitudes de notificación e implementar la lógica de negocios basada en la notificación.

Adición de notificaciones de definición de aplicación del catálogo de servicios

En los ejemplos siguientes se muestra cómo agregar un URI de punto de conexión de notificación mediante el portal o la API REST.

Portal de Azure

Para comenzar, consulte Inicio rápido: Creación y publicación de una definición de aplicación administrada de Azure.

API DE REST

Nota

Solo puede proporcionar un punto de conexión en la propiedad notificationEndpoints de la definición de aplicación administrada.

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

Adición de notificaciones de aplicaciones administradas de Azure Marketplace

Para más información, vea Crear una oferta de una aplicación de Azure.

Desencadenadores de eventos

En la tabla siguiente se describen todas las posibles combinaciones de eventType y provisioningState y sus desencadenadores:

EventType	ProvisioningState	Desencadenador para la notificación
PUT	Accepted	Se ha creado y proyectado correctamente un grupo de recursos administrados después del evento PUT de la aplicación (antes de que se inicie la implementación en el grupo de recursos administrados).
PUT	Correcto	El aprovisionamiento completo de la aplicación administrada se realizó correctamente después de un PUT.
PUT	Con error	Error al poner el aprovisionamiento de la instancia de aplicación en cualquier momento.
PATCH	Correcto	Después de un evento PATCH correcto de la instancia de la aplicación administrada para actualizar las etiquetas, la directiva de acceso Just-In-Time (JIT) o la identidad administrada.
Delete	Eliminando	En cuanto el usuario inicia una eliminación de una instancia de la aplicación administrada.
Delete	Deleted	Después de la eliminación completa y correcta de la aplicación administrada.
Delete	Con error	Después de cualquier error durante el proceso de desaprovisionamiento que bloquea la eliminación.

Esquema de la notificación

Al crear el punto de conexión de webhook para controlar las notificaciones, necesita analizar la carga para obtener propiedades importantes y, después, actuar en función de la notificación. Las notificaciones de aplicaciones administradas del catálogo de servicios y de Azure Marketplace proporcionan muchas de esas mismas propiedades, pero hay algunas diferencias. La propiedad applicationDefinitionId solo se aplica al catálogo de servicios. Las propiedades billingDetails y plan solo se aplican a Azure Marketplace.

Azure anexa /resource al URI del punto de conexión de notificación que proporcionó en la definición de aplicación administrada. El punto de conexión de webhook debe ser capaz de controlar las notificaciones en el URI /resource. Por ejemplo, si proporcionó un URI de punto de conexión de notificación como https://fabrikam.com, el URI del punto de conexión de webhook es https://fabrikam.com/resource.

Esquema de notificación de aplicación de catálogo de servicios

El ejemplo siguiente muestra una notificación del catálogo de servicios después de un aprovisionamiento correcto de una instancia de la aplicación administrada.

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 se produce un error en el aprovisionamiento, se envía una notificación con los detalles del error al punto de conexión especificado.

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

Esquema de notificación de aplicación de Azure Marketplace

El ejemplo siguiente muestra una notificación del catálogo de servicios después de un aprovisionamiento correcto de una instancia de la aplicación administrada.

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 se produce un error en el aprovisionamiento, se envía una notificación con los detalles del error al punto de conexión especificado.

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

Propiedad	Descripción
eventType	Tipo de evento que desencadenó la notificación. Por ejemplo, PUT, PATCH, DELETE.
applicationId	El identificador de recurso completo de la aplicación administrada para la que se desencadenó la notificación.
eventTime	Marca de tiempo del evento que desencadenó la notificación. Fecha y hora en formato UTC ISO 8601.
provisioningState	El estado de aprovisionamiento de la instancia de la aplicación administrada. Por ejemplo, Succeeded, Failed, Deleting, Deleted.
applicationDefinitionId	Solo se especifica en el caso de las aplicaciones administradas del catálogo de servicios. Representa el identificador de recurso completo de la definición de la aplicación para la que se aprovisionó la instancia de la aplicación administrada.
billingDetails	Solo se especifica en el caso de las aplicaciones administradas de Azure Marketplace. El estado de facturación de la instancia de la aplicación administrada. Contiene el identificador resourceUsageId, que sirve para consultar los detalles de uso de Azure Marketplace.
plan	Solo se especifica en el caso de las aplicaciones administradas de Azure Marketplace. Representa el publicador, la oferta, la SKU y la versión de la instancia de la aplicación administrada.
error	Solo se especifica cuando se produce un error en provisioningState. Contiene el código de error, el mensaje y los detalles del problema que causó el error.

Autenticación de punto de conexión

Para proteger el punto de conexión del webhook y garantizar la autenticidad de la notificación:

1. Proporcione un parámetro de consulta en la parte superior del URI del webhook, como este: https://your-endpoint.com?sig=Guid. Con cada notificación, compruebe que el parámetro de consulta sig tiene el valor esperado Guid.
2. Emita un evento GET en la instancia de la aplicación administrada con applicationId. Compruebe que provisioningState coincide con el provisioningState de la notificación para garantizar la coherencia.

Reintentos de notificación

El servicio de notificaciones de aplicaciones administradas espera una respuesta 200 OK del punto de conexión de webhook a la notificación. El servicio de notificación vuelve a intentarlo si el punto de conexión de webhook devuelve un código de error HTTP igual o superior a 500, devuelve un código de error 429 o si el punto de conexión no está disponible temporalmente. Si el punto de conexión de webhook no está disponible en 10 horas, se quita el mensaje de notificación y se detienen los reintentos.