Aplicativos gerenciados do Azure com notificações

  • Artigo

As notificações de aplicativos gerenciados do Azure permitem que os editores automatizem ações com base em eventos do ciclo de vida das instâncias de aplicativos gerenciados. Os editores podem especificar um ponto de extremidade de webhook de notificação personalizado para receber notificações de eventos sobre instâncias de aplicativos gerenciados novas e existentes. Os editores podem configurar fluxos de trabalho personalizados no momento do provisionamento, atualizações e exclusão de aplicativos.

Introdução

Para começar a receber notificações de aplicativos gerenciados, crie um ponto de extremidade HTTPS público. Especifique o ponto de extremidade ao publicar a definição de aplicativo do catálogo de serviços ou a oferta do Microsoft Azure Marketplace.

Aqui estão as etapas recomendadas para começar rapidamente:

  1. Crie um ponto de extremidade HTTPS público que registre as solicitações POST de entrada e retorne 200 OK.
  2. Adicione o ponto de extremidade à definição de aplicativo do catálogo de serviços ou à oferta do Azure Marketplace, conforme explicado posteriormente neste artigo.
  3. Crie uma instância de aplicativo gerenciado que faça referência à definição de aplicativo ou à oferta do Azure Marketplace.
  4. Valide se as notificações estão sendo recebidas.
  5. Habilite a autorização conforme explicado na seção Autenticação de ponto de extremidade deste artigo.
  6. Siga as instruções na seção Esquema de notificação deste artigo para analisar as solicitações de notificação e implementar sua lógica de negócios com base na notificação.

Adicionar notificações de definição de aplicativo do catálogo de serviços

Os exemplos a seguir mostram como adicionar um URI de ponto de extremidade de notificação usando o portal ou a API REST.

Portal do Azure

Para começar, consulte Guia de início rápido: criar e publicar uma definição de Aplicativo Gerenciado do Azure.

Captura de tela do portal do Azure que mostra uma definição de aplicativo gerenciado do catálogo de serviços e o ponto de extremidade de notificação.

API REST

Nota

Você só pode fornecer um ponto de extremidade na notificationEndpoints propriedade da definição de aplicativo gerenciado.

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

Adicionar notificações de aplicativos gerenciados do Azure Marketplace

Para obter mais informações, consulte Criar uma oferta de aplicativo do Azure.

Captura de ecrã das notificações de aplicações geridas do Azure Marketplace no portal do Azure.

Acionadores de eventos

A tabela a seguir descreve todas as combinações possíveis de eventType e provisioningState seus gatilhos:

EventType ProvisioningState Gatilho para notificação
PUT Aceite O grupo de recursos gerenciados foi criado e projetado com êxito após o PUT do aplicativo (antes que a implantação dentro do grupo de recursos gerenciados seja iniciada).
PUT Com êxito O provisionamento completo do aplicativo gerenciado foi bem-sucedido após um PUT.
PUT Com falhas Falha de PUT de provisionamento de instância de aplicativo em qualquer ponto.
PATCH Com êxito Após um PATCH bem-sucedido na instância do aplicativo gerenciado para atualizar tags, política de acesso just-in-time (JIT) ou identidade gerenciada.
DELETE Eliminar Assim que o usuário inicia um DELETE de uma instância de aplicativo gerenciado.
DELETE Eliminado Após a exclusão completa e bem-sucedida do aplicativo gerenciado.
DELETE Com falhas Após qualquer erro durante o processo de desprovisionamento que bloqueia a exclusão.

Esquema de notificação

Ao criar seu ponto de extremidade webhook para lidar com notificações, você precisa analisar a carga útil para obter propriedades importantes e, em seguida, agir de acordo com a notificação. O catálogo de serviços e as notificações de aplicativos gerenciados do Azure Marketplace fornecem muitas das mesmas propriedades, mas há algumas diferenças. A applicationDefinitionId propriedade só se aplica ao catálogo de serviços. As billingDetails propriedades e plan só se aplicam ao Azure Marketplace.

O Azure acrescenta ao URI do ponto de /resource extremidade de notificação fornecido na definição de aplicativo gerenciado. O ponto de extremidade webhook deve ser capaz de lidar com notificações no /resource URI. Por exemplo, se você forneceu um URI de ponto de extremidade de notificação como https://fabrikam.com o URI do ponto de extremidade webhook é https://fabrikam.com/resource.

Esquema de notificação de aplicativo do catálogo de serviços

O exemplo a seguir mostra uma notificação de catálogo de serviços após o provisionamento bem-sucedido de uma instância de aplicativo gerenciado.

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 o provisionamento falhar, uma notificação com os detalhes do erro será enviada para o ponto de extremidade 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 notificação de aplicativo do Azure Marketplace

O exemplo a seguir mostra uma notificação de catálogo de serviços após o provisionamento bem-sucedido de uma instância de aplicativo gerenciado.

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 o provisionamento falhar, uma notificação com os detalhes do erro será enviada para o ponto de extremidade 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"
      }
    ]
  }
}
Property Description
eventType O tipo de evento que disparou a notificação. Por exemplo, PUT, PATCH, DELETE.
applicationId O identificador de recurso totalmente qualificado do aplicativo gerenciado para o qual a notificação foi disparada.
eventTime O carimbo de data/hora do evento que disparou a notificação. Data e hora no formato UTC ISO 8601.
provisioningState O estado de provisionamento da instância do aplicativo gerenciado. Por exemplo, Succeeded, Failed, Excluting, Deleted.
applicationDefinitionId Especificado apenas para aplicativos gerenciados do catálogo de serviços. Representa o identificador de recurso totalmente qualificado da definição de aplicativo para a qual a instância do aplicativo gerenciado foi provisionada.
billingDetails Especificado apenas para aplicativos gerenciados do Azure Marketplace. Os detalhes de faturamento da instância do aplicativo gerenciado. Contém o que você pode usar para consultar o resourceUsageId Azure Marketplace para obter detalhes de uso.
plan Especificado apenas para aplicativos gerenciados do Azure Marketplace. Representa o editor, a oferta, a SKU e a versão da instância do aplicativo gerenciado.
error Especificado somente quando o provisioningState é Failed. Contém o código de erro, a mensagem e os detalhes do problema que causou a falha.

Autenticação de ponto de extremidade

Para proteger o ponto de extremidade do webhook e garantir a autenticidade da notificação:

  1. Forneça um parâmetro de consulta sobre o URI do webhook, da seguinte forma: https://your-endpoint.com?sig=Guid. Com cada notificação, verifique se o parâmetro sig de consulta tem o valor Guidesperado.
  2. Emita um GET na instância do aplicativo gerenciado usando applicationIdo . Valide se o provisioningState corresponde ao provisioningState da notificação para garantir a consistência.

Tentativas de notificação novamente

O serviço de notificação de aplicativo gerenciado espera uma 200 OK resposta do ponto de extremidade webhook para a notificação. O serviço de notificação tenta novamente se o ponto de extremidade webhook retornar um código de erro HTTP maior ou igual a 500, ele retornará um código de erro de 429 ou se o ponto de extremidade estiver temporariamente inacessível. Se o ponto de extremidade do webhook não ficar disponível dentro de 10 horas, a mensagem de notificação será descartada e as tentativas serão interrompidas.