Aplicaciones administradas de Azure con notificaciones

  • Artículo

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.

Captura de pantalla de Azure Portal que muestra una definición de aplicación administrada de catálogo de servicios y el punto de conexión de notificación.

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

Captura de pantalla de las notificaciones de la aplicación administrada de Azure Marketplace en Azure Portal.

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 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, necesitará analizar la carga para obtener propiedades importantes y, después, actuar sobre 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 enviará 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 enviará 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 volverá 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 quitará el mensaje de notificación y se detendrán los reintentos.