提供通知的 Azure 托管应用程序Azure managed applications with notifications

Azure 托管应用程序通知可让发布者根据托管应用程序实例的生命周期事件自动执行操作。Azure managed application notifications allow publishers to automate actions based on lifecycle events of the managed application instances. 发布者可以指定自定义通知 Webhook 终结点,以接收有关新的和现有的托管应用程序实例的事件通知。Publishers can specify custom notification webhook endpoints to receive event notifications about new and existing managed application instances. 发布者可以在预配、更新和删除应用程序时设置自定义工作流。Publishers can set up custom workflows at the time of application provisioning, updates, and deletion.

入门Getting started

若要开始接收托管应用程序,请启动公共 HTTPS 终结点,并在发布服务目录应用程序定义或 Azure 市场套餐时指定该终结点。To start receiving managed applications, spin up a public HTTPS endpoint and specify it when you publish the service catalog application definition or Azure Marketplace offer.

下面是建议的快速入门步骤:Here are the recommended steps to get started quickly:

  1. 启动一个公共 HTTPS 终结点,用于记录传入的 POST 请求并返回 200 OKSpin up a public HTTPS endpoint that logs the incoming POST requests and returns 200 OK.
  2. 如本文稍后所述,将该终结点添加到服务目录应用程序定义或 Azure 市场套餐。Add the endpoint to the service catalog application definition or Azure Marketplace offer as explained later in this article.
  3. 创建一个引用应用程序定义或 Azure 市场套餐的托管应用程序实例。Create a managed application instance that references the application definition or Azure Marketplace offer.
  4. 验证是否正在接收通知。Validate that the notifications are being received.
  5. 根据本文的“终结点身份验证”部分所述启用授权。 Enable authorization as explained in the Endpoint authentication section of this article.
  6. 按照本文的“通知架构”部分中的说明分析通知请求,并根据通知实现业务逻辑。 Follow the instructions in the Notification schema section of this article to parse the notification requests and implement your business logic based on the notification.

添加服务目录应用程序定义通知Add service catalog application definition notifications

Azure 门户Azure portal

若要开始,请参阅通过 Azure 门户发布服务目录应用程序To get started, see Publish a service catalog application through Azure portal.

Azure 门户中的服务目录应用程序定义通知

REST APIREST API

备注

目前,只能在应用程序定义属性中的 notificationEndpoints 内提供一个终结点。Currently, you can supply only one endpoint in the notificationEndpoints in the application definition properties.

    {
      "properties": {
        "isEnabled": true,
        "lockLevel": "ReadOnly",
        "displayName": "Sample Application Definition",
        "description": "Notification-enabled application definition.",
        "notificationPolicy": {
            "notificationEndpoints": [
                {
                    "uri": "https://isv.chinacloudsites.cn:1214?sig=unique_token"
                }
            ]
        },
        "authorizations": [
          {
            "principalId": "d6b7fbd3-4d99-43fe-8a7a-f13aef11dc18",
            "roleDefinitionId": "8e3af657-a8ff-443c-a75c-2fe8c4bcb635"
          },
        ...

添加 Azure 市场托管应用程序通知Add Azure Marketplace managed application notifications

Azure 门户中的 Azure 市场托管应用程序通知

事件触发器Event triggers

下表描述了 EventType 和 ProvisioningState 的所有可能组合及其触发器:The following table describes all the possible combinations of EventType and ProvisioningState and their triggers:

EventTypeEventType ProvisioningStateProvisioningState 通知的触发器Trigger for notification
PUTPUT 已接受Accepted 在应用程序 PUT 之后(启动托管资源组中的部署之前)已成功创建并投影托管资源组。Managed resource group has been created and projected successfully after application PUT (before the deployment inside the managed resource group is kicked off).
PUTPUT 已成功Succeeded PUT 之后完全预配托管应用程序成功。Full provisioning of the managed application succeeded after a PUT.
PUTPUT 失败Failed 在任意时间点 PUT 应用程序实例预配失败。Failure of PUT of application instance provisioning at any point.
PATCHPATCH 已成功Succeeded 在托管应用程序实例上成功执行 PATCH 以更新标记、JIT 访问策略或托管标识之后发生。After a successful PATCH on the managed application instance to update tags, JIT access policy, or managed identity.
DELETEDELETE 正在删除Deleting 在用户启动托管应用程序实例的 DELETE 后立即发生。As soon as the user initiates a DELETE of a managed app instance.
DELETEDELETE DeletedDeleted 在完全成功删除托管应用程序之后发生。After the full and successful deletion of the managed application.
DELETEDELETE 失败Failed 在取消预配过程中出现任何阻止删除的错误之后发生。After any error during the deprovisioning process that blocks the deletion.

通知架构Notification schema

在启动 Webhook 终结点来处理通知时,需要分析有效负载,以获取重要属性,然后再处理通知。When you spin up your webhook endpoint to handle notifications, you'll need to parse the payload to get important properties to then act upon the notification. 服务目录和 Azure 市场托管应用程序通知提供许多相同的属性。Service catalog and Azure Marketplace managed application notifications provide many of the same properties. 示例后面的表格中概述了两个细微的差异。Two small differences are outlined in the table that follows the samples.

服务目录应用程序通知架构Service catalog application notification schema

下面是在成功预配托管应用程序实例后的服务目录通知示例:Here's a sample service catalog notification after the successful provisioning of a managed application instance:

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

如果预配失败,会将包含错误详细信息的通知发送到指定的终结点。If the provisioning fails, a notification with the error details will be sent to the specified endpoint.

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 市场应用程序通知架构Azure Marketplace application notification schema

下面是在成功预配托管应用程序实例后的服务目录通知示例:Here's a sample service catalog notification after the successful provisioning of a managed application instance:

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

如果预配失败,会将包含错误详细信息的通知发送到指定的终结点。If the provisioning fails, a notification with the error details will be sent to the specified endpoint.

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

参数Parameter 说明Description
eventTypeeventType 触发通知的事件类型。The type of event that triggered the notification. (例如 PUT、PATCH、DELETE。)(For example, PUT, PATCH, DELETE.)
applicationIdapplicationId 对其触发了通知的托管应用程序的完全限定资源标识符。The fully qualified resource identifier of the managed application for which the notification was triggered.
EventTimeeventTime 触发通知的事件的时间戳。The timestamp of the event that triggered the notification. (UTC ISO 8601 格式的日期和时间。)(Date and time in UTC ISO 8601 format.)
provisioningStateprovisioningState 托管应用程序实例的预配状态。The provisioning state of the managed application instance. (例如 Succeeded、Failed、Deleting、Deleted。)(For example, Succeeded, Failed, Deleting, Deleted.)
errorerror 仅当 provisioningState 为 Failed 时指定。 Specified only when the provisioningState is Failed. 包含导致失败的问题的错误代码、消息和详细信息。Contains the error code, message, and details of the issue that caused the failure.
applicationDefinitionIdapplicationDefinitionId 仅为服务目录托管应用程序指定。 Specified only for service catalog managed applications. 表示为其预配了托管应用程序实例的应用程序定义的完全限定资源标识符。Represents the fully qualified resource identifier of the application definition for which the managed application instance was provisioned.
计划plan 仅为 Azure 市场托管应用程序指定。 Specified only for Azure Marketplace managed applications. 表示托管应用程序实例的发布者、套餐、SKU 和版本。Represents the publisher, offer, SKU, and version of the managed application instance.
billingDetailsbillingDetails 仅为 Azure 市场托管应用程序指定。 Specified only for Azure Marketplace managed applications. 托管应用程序实例的计费详细信息。The billing details of the managed application instance. 包含可用于在 Azure 市场中查询使用情况详细信息的 resourceUsageId。Contains the resourceUsageId that you can use to query Azure Marketplace for usage details.

终结点身份验证Endpoint authentication

若要保护 Webhook 终结点并确保通知的真实性:To secure the webhook endpoint and ensure the authenticity of the notification:

  1. 在 Webhook URI 的基础上提供一个查询参数,如下所示:https://your-endpoint.com?sig=Guid。Provide a query parameter on top of the webhook URI, like this: https://your-endpoint.com?sig=Guid. 对于每个通知,请检查查询参数 sig 是否包含预期值 GuidWith each notification, check that the query parameter sig has the expected value Guid.
  2. 使用 applicationId 对托管应用程序实例发出 GET。Issue a GET on the managed application instance by using applicationId. 验证 provisioningState 是否与通知的 provisioningState 相匹配,以确保一致性。Validate that the provisioningState matches the provisioningState of the notification to ensure consistency.

通知重试Notification retries

托管应用程序通知服务预期 Webhook 终结点在通知中返回 200 OK 响应。The Managed Application Notification service expects a 200 OK response from the webhook endpoint to the notification. 如果 Webhook 终结点返回大于或等于 500 的 HTTP 错误代码、返回错误代码 429,或暂时不可访问,则通知服务将会重试。The notification service will retry if the webhook endpoint returns an HTTP error code greater than or equal to 500, if it returns an error code of 429, or if the endpoint is temporarily unreachable. 如果 Webhook 终结点在 10 小时内一直不可用,则会删除通知消息,并且重试将会停止。If the webhook endpoint doesn't become available within 10 hours, the notification message will be dropped and the retries will stop.