Aplicações geridas do Azure com notificações

  • Artigo

As notificações de aplicações geridas do Azure permitem que os publicadores automatizem ações com base em eventos de ciclo de vida das instâncias de aplicações geridas. Os editores podem especificar um ponto final de webhook de notificação personalizada para receber notificações de eventos sobre instâncias de aplicações geridas novas e existentes. Os editores podem configurar fluxos de trabalho personalizados no momento do aprovisionamento, atualizações e eliminação de aplicações.

Introdução

Para começar a receber notificações de aplicações geridas, crie um ponto final HTTPS público. Especifique o ponto final quando publicar a definição de aplicação do catálogo de serviços ou a oferta do Microsoft Azure Marketplace.

Eis os passos recomendados para começar rapidamente:

  1. Crie um ponto final HTTPS público que registe os pedidos POST recebidos e devolva 200 OK.
  2. Adicione o ponto final à definição de aplicação do catálogo de serviços ou Azure Marketplace oferta, conforme explicado mais adiante neste artigo.
  3. Crie uma instância de aplicação gerida que faça referência à definição da aplicação ou Azure Marketplace oferta.
  4. Confirme que as notificações estão a ser recebidas.
  5. Ative a autorização conforme explicado na secção Autenticação de ponto final deste artigo.
  6. Siga as instruções na secção Esquema de notificação deste artigo para analisar os pedidos de notificação e implementar a lógica de negócio com base na notificação.

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

Os exemplos seguintes mostram como adicionar um URI de ponto final de notificação com o portal ou a API REST.

Portal do Azure

Para começar, veja Início Rápido: Criar e publicar uma definição de Aplicação Gerida do Azure.

Captura de ecrã do portal do Azure que mostra uma definição de aplicação gerida do catálogo de serviços e o ponto final de notificação.

API REST

Nota

Só pode fornecer um ponto final na notificationEndpoints propriedade da definição da aplicação gerida.

{
  "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 Azure Marketplace notificações de aplicações geridas

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

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

Acionadores de eventos

A tabela seguinte descreve todas as combinações possíveis de e provisioningState dos eventType respetivos acionadores:

EventType ProvisioningState Acionador para notificação
PUT Aceite O grupo de recursos gerido foi criado e projetado com êxito após o PUT da aplicação (antes de a implementação dentro do grupo de recursos gerido ser iniciada).
PUT Com êxito O aprovisionamento completo da aplicação gerida foi efetuado com êxito após um PUT.
PUT Com falhas Falha do PUT do aprovisionamento da instância da aplicação em qualquer momento.
PATCH Com êxito Após um PATCH bem-sucedido na instância da aplicação gerida para atualizar etiquetas, política de acesso JIT ou identidade gerida.
DELETE Eliminar Assim que o utilizador iniciar uma ELIMINAÇÃO de uma instância de aplicação gerida.
DELETE Eliminado Após a eliminação completa e bem-sucedida da aplicação gerida.
DELETE Com falhas Após qualquer erro durante o processo de desaprovisionamento que bloqueia a eliminação.

Esquema de notificação

Quando criar o ponto final do webhook para processar notificações, terá de analisar o payload para obter propriedades importantes para, em seguida, agir após a notificação. O catálogo de serviços e Azure Marketplace notificações de aplicações geridas fornecem muitas das mesmas propriedades, mas existem algumas diferenças. A applicationDefinitionId propriedade aplica-se apenas ao catálogo de serviços. As billingDetails propriedades e plan aplicam-se apenas a Azure Marketplace.

O Azure acrescenta /resource ao URI do ponto final de notificação que forneceu na definição da aplicação gerida. O ponto final do webhook tem de conseguir processar notificações no /resource URI. Por exemplo, se tiver fornecido um URI de ponto final de notificação como https://fabrikam.com , o URI do ponto final do webhook é https://fabrikam.com/resource.

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

O exemplo seguinte mostra uma notificação do catálogo de serviços após o aprovisionamento bem-sucedido de uma instância de aplicação gerida.

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 aprovisionamento falhar, será enviada uma notificação com os detalhes do erro para o ponto final 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"
      }
    ]
  }
}

Azure Marketplace esquema de notificação da aplicação

O exemplo seguinte mostra uma notificação do catálogo de serviços após o aprovisionamento bem-sucedido de uma instância de aplicação gerida.

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 aprovisionamento falhar, será enviada uma notificação com os detalhes do erro para o ponto final 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 acionou a notificação. (Por exemplo, PUT, PATCH, DELETE.)
applicationId O identificador de recurso completamente qualificado da aplicação gerida para a qual a notificação foi acionada.
eventTime O carimbo de data/hora do evento que acionou a notificação. (Data e hora no formato ISO 8601 UTC.)
provisioningState O estado de aprovisionamento da instância da aplicação gerida. Por exemplo, Com Êxito, Com Falhas, Eliminação, Eliminado.
applicationDefinitionId Especificado apenas para aplicações geridas do catálogo de serviços. Representa o identificador de recurso completamente qualificado da definição da aplicação para a qual a instância da aplicação gerida foi aprovisionada.
billingDetails Especificado apenas para Azure Marketplace aplicações geridas. Os detalhes de faturação da instância da aplicação gerida. Contém o resourceUsageId que pode utilizar para consultar Azure Marketplace para obter detalhes de utilização.
plan Especificado apenas para Azure Marketplace aplicações geridas. Representa o publicador, a oferta, o SKU e a versão da instância da aplicação gerida.
error Especificado apenas quando provisioningState for Failed. Contém o código de erro, a mensagem e os detalhes do problema que causou a falha.

Autenticação de ponto final

Para proteger o ponto final 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 da aplicação gerida com applicationId. Confirme que corresponde ao provisioningStateprovisioningState da notificação para garantir a consistência.

Repetições de notificação

O serviço de notificação da aplicação gerida espera uma 200 OK resposta do ponto final do webhook à notificação. O serviço de notificação tentará novamente se o ponto final do webhook devolver um código de erro HTTP maior ou igual a 500, devolver um código de erro 429 ou se o ponto final estiver temporariamente inacessível. Se o ponto final do webhook não ficar disponível dentro de 10 horas, a mensagem de notificação será removida e as repetições serão interrompidas.