Aplicativos gerenciados do Azure com notificações

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

Introdução

Para começar a receber notificações do aplicativo gerenciado, crie um ponto de extremidade HTTPS público. Especifique o ponto de extremidade quando você 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 registra em log as solicitações POST de entrada e retorna 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 do aplicativo gerenciado que faz referência à definição do aplicativo ou à oferta do Azure Marketplace.
4. Valide se as notificações estão sendo recebidas.
5. Habilita 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 a 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, confira Início Rápido: criar e publicar uma definição de Aplicativo Gerenciado do Azure.

API REST

Observação

Você só pode fornecer um ponto de extremidade na propriedade notificationEndpoints 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": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "roleDefinitionId": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
      },
    ...

Adicionar notificações do aplicativo gerenciado do Azure Marketplace

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

Gatilhos de evento

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

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

Esquema de notificação

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

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

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

O exemplo a seguir mostra uma notificação do catálogo de serviços após o provisionamento bem-sucedido de uma instância do 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 do catálogo de serviços após o provisionamento bem-sucedido de uma instância do 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"
      }
    ]
  }
}

Propriedade	Descrição
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, Êxito, Falha, Exclusão, Excluído.
applicationDefinitionId	Especificado somente 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 somente para aplicativos gerenciados do Azure Marketplace. Os detalhes de cobrança da instância do aplicativo gerenciado. Contém o resourceUsageId que você pode usar para consultar o Azure Marketplace e obter detalhes de uso.
plan	Especificado somente para aplicativos gerenciados do Azure Marketplace. Representa o editor, a oferta, o SKU e a versão da instância do aplicativo gerenciado.
error	Especificado somente quando o provisioningState tiver falha. Contém o código de erro, a mensagem e os detalhes do problema que causou a falha.

Autenticação do 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, assim: https://your-endpoint.com?sig=Guid. Com cada notificação, verifique se o parâmetro de consulta sig tem o valor esperado Guid.
2. Emita um GET na instância do aplicativo gerenciado usando applicationId. Valide se o provisioningState corresponde ao provisioningState da notificação para garantir a consistência.

Tentativas de notificação

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