具有通知的 Azure 受控應用程式

發行項
06/24/2024

Azure 受控應用程式通知可讓發行者根據受控應用程式執行個體的生命週期事件來將動作自動化。發行者可以指定自訂通知 Webhook 端點，來接收有關新的和現有受控應用程式執行個體的事件通知。發行者可以在應用程式佈建、更新和刪除時設定自訂工作流程。

開始使用

若要開始接收受控代理程式通知，請建立公用 HTTPS 端點。當您發佈服務類別目錄應用程式定義或 Microsoft Azure Marketplace 供應項目時，請指定端點。

以下是快速入門的建議步驟：

建立可記錄傳入 POST 要求並傳回 200 OK 的公用 HTTPS 端點。
將該端點新增至服務類別目錄應用程式定義或 Azure Marketplace 供應項目，如此文章稍後所述。
建立受控應用程式執行個體來參考應用程式定義或 Azure Marketplace 供應項目。
驗證已收到通知。
啟用授權，如此文章的端點驗證一節所述。
遵循此文章的通知結構描述一節中的指示來剖析通知要求，並根據通知實作您的商務邏輯。

新增服務類別目錄應用程式定義通知

下列範例示範如何使用入口網站或 REST API 來新增通知端點 URI。

Azure 入口網站

若要開始使用，請參閱快速入門：建立和發佈 Azure 受控應用程式定義。

顯示服務類別目錄受管理應用程式定義和通知端點的 Azure 入口網站螢幕擷取畫面。

REST API

注意

您只能在受控應用程式定義的 notificationEndpoints 屬性中提供一個端點。

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

新增 Azure Marketplace 受控應用程式通知

如需詳細資訊，請參閱建立 Azure 應用程式供應項目。

Azure 入口網站中 Azure Marketplace 受管理應用程式通知的螢幕擷取畫面。

事件觸發程序

下表描述 eventType 和 provisioningState 及其觸發程序的所有可能組合：

EventType	ProvisioningState	通知的觸發程序
PUT	已接受	受控資源群組已在應用程式 PUT 之後 (在受控資源群組內的部署開始進行之前) 成功建立並投射。
PUT	成功	受控應用程式在 PUT 之後完整佈建成功。
PUT	失敗	應用程式執行個體佈建在任何時間點 PUT 失敗。
修補檔	成功	在成功 PATCH 受管理應用程式執行個體以更新標籤、Just-In-Time (JIT) 存取原則或受控識別之後。
DELETE	刪除中	一旦使用者起始受控應用程式執行個體的 DELETE。
DELETE	已刪除	完整且成功刪除受控應用程式之後。
DELETE	失敗	取消佈建程序中因發生任何錯誤而封鎖刪除之後。

通知結構描述

在建立 Webhook 端點來處理通知時，您需要剖析承載以取得重要屬性，然後對通知採取動作。服務類別目錄和 Azure Marketplace 受控應用程式通知提供許多相同的屬性，但會有一些差異。 applicationDefinitionId 屬性僅適用於服務類別目錄。 billingDetails 和 plan 屬性僅適用於 Azure Marketplace。

Azure 會將 /resource 附加至您在受控應用程式定義中提供的通知端點 URI。 Webhook 端點必須能夠處理 /resource URI 上的通知。例如，如果您提供了通知端點 URI，例如 https://fabrikam.com，則 Webhook 端點 URI 為 https://fabrikam.com/resource。

服務類別目錄應用程式通知結構描述

下列範例示範成功佈建受控應用程式執行個體之後的服務類別目錄通知。

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

如果佈建失敗，就會將包含錯誤詳細資料的通知傳送至指定的端點。

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 應用程式通知結構描述

下列範例示範成功佈建受控應用程式執行個體之後的服務類別目錄通知。

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

如果佈建失敗，就會將包含錯誤詳細資料的通知傳送至指定的端點。

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

屬性	說明
`eventType`	觸發通知的事件類型。例如 PUT、PATCH、DELETE。
`applicationId`	觸發通知之受控應用程式的完整資源識別碼。
`eventTime`	觸發通知之事件的時間戳記。 UTC ISO 8601 格式的日期和時間。
`provisioningState`	受控應用程式執行個體的佈建狀態。例如 Succeeded、Failed、Deleting、Deleted。
`applicationDefinitionId`	僅針對服務類別目錄受控應用程式指定。代表已佈建受控應用程式執行個體之應用程式定義的完整資源識別碼。
`billingDetails`	僅針對 Azure Marketplace 受控應用程式指定。受控應用程式執行個體的帳單詳細資料。包含可用來查詢 Azure Marketplace 以取得使用方式詳細資料的 `resourceUsageId`。
`plan`	僅針對 Azure Marketplace 受控應用程式指定。代表受控應用程式執行個體的發行者、供應項目、SKU 和版本。
`error`	僅在 ProvisioningState 為 Failed 時指定。包含導致失敗之問題的錯誤碼、訊息和詳細資料。

端點驗證

保護 Webhook 端點的安全，並確保通知的真確性：

在 Webhook URI 之上提供查詢參數，如下所示：https://your-endpoint.com?sig=Guid。檢查每個通知中的查詢參數 sig 是否具有預期的值 Guid。
使用 applicationId 對受控應用程式執行個體發出 GET。驗證 provisioningState 會與通知的 provisioningState 相符，以確保一致性。

通知重試

受控應用程式通知服務預期會從 Webhook 端點對通知產生 200 OK 回應。如果 Webhook 端點傳回大於或等於 500 的 HTTP 錯誤碼、傳回錯誤碼 429，或暫時無法連線到端點，通知服務將會重試。如果 Webhook 端點未在 10 小時內恢復為可用，系統會捨棄通知訊息，並停止重試。

共用方式為