Azure Managed Applications と通知

[アーティクル]
06/24/2024

Azure Managed Application の通知を使用することで、パブリッシャーは、マネージドアプリケーションインスタンスのライフサイクルイベントに基づいてアクションを自動化することができます。パブリッシャーは、カスタム通知 Webhook エンドポイントを指定して、新規および既存のマネージドアプリケーションインスタンスに関するイベント通知を受け取ることができます。パブリッシャーは、アプリケーションのプロビジョニング、更新、および削除時のカスタムワークフローを設定することができます。

作業の開始

マネージドアプリケーションの通知を受け取るようにするには、パブリック HTTPS エンドポイントを作成します。サービスカタログのアプリケーション定義または Microsoft Azure Marketplace オファーを発行するときにエンドポイントを指定します。

すぐに開始するには、次の手順を実行することをお勧めします。

受信 POST 要求をログに記録し、200 OK を返すパブリック HTTPS エンドポイントを作成します。
この記事で後で説明するように、そのエンドポイントをサービスカタログアプリケーション定義または Azure Marketplace オファーに追加します。
アプリケーション定義または Azure Marketplace オファーを参照するマネージドアプリケーションインスタンスを作成します。
通知が受信されていることを確認します。
この記事の「エンドポイントの認証」セクションの説明に従って承認を有効にします。
この記事の「通知スキーマ」セクションの手順に従って、通知要求を解析し、通知に基づいてビジネスロジックを実装します。

サービスカタログアプリケーション定義の通知の追加

次の例では、ポータルまたは REST API を使用して通知エンドポイント URI を追加する方法を示します。

Azure portal

開始するには、「クイックスタート: Azure マネージドアプリケーションの定義を作成および発行する」を参照してください。

サービスカタログのマネージドアプリケーション定義と通知エンドポイントが表示されている Azure portal のスクリーンショット。

REST API

Note

マネージドアプリケーション定義の notificationEndpoints プロパティに指定できるエンドポイントは 1 つだけです。

{
  "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 portal での Azure Marketplace マネージドアプリケーション通知のスクリーンショット。

Event triggers (イベントトリガー)

次の表では、eventType と provisioningState の考えられるすべての組み合わせとそれらのトリガーについて説明します。

EventType	ProvisioningState	通知のトリガー
PUT	承認済み	アプリケーション PUT 後 (管理対象リソースグループ内のデプロイが開始される前) にマネージドリソースグループが作成され、正常に投影されました。
PUT	成功	PUT 後に、マネージドアプリケーションのフルプロビジョニングが成功した。
PUT	失敗	任意の時点でのアプリケーションインスタンスプロビジョニングの PUT の失敗。
PATCH	Succeeded	タグ、Just-In-Time (JIT) アクセスポリシー、またはマネージド ID を更新するための、マネージドアプリケーションインスタンスに対する修正プログラムが正常に適用された後。
DELETE	削除中	ユーザーがマネージドアプリインスタンスの DELETE を開始するとすぐ。
DELETE	Deleted	マネージドアプリケーションの完全な削除が正常に行われた後。
DELETE	失敗	削除をブロックする、プロビジョニング解除プロセス中のエラーの後。

通知スキーマ

通知を処理するために Webhook エンドポイントを作成する場合は、ペイロードを解析して重要なプロパティを取得してから、通知に基づいて対応する必要があります。サービスカタログと Azure Marketplace マネージドアプリケーションの通知では、多くの同じプロパティが使用されますが、いくつかの違いもあります。 applicationDefinitionId プロパティは、サービスカタログにのみ適用されます。 billingDetails と plan プロパティは、Azure Marketplace にのみ適用されます。

Azure は、マネージドアプリケーション定義で指定した通知エンドポイント URI に /resource を追加します。 Webhook エンドポイントは、/resource URI で通知を処理できる必要があります。たとえば、https://fabrikam.com のような通知エンドポイント URI を指定した場合、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`	マネージドアプリケーションインスタンスのプロビジョニングの状態。例: 成功、失敗、削除中、削除済み
`applicationDefinitionId`	サービスカタログマネージドアプリケーションに対してのみ指定されます。マネージドアプリケーションインスタンスがプロビジョニングされたアプリケーション定義の完全修飾リソース識別子を表します。
`billingDetails`	Azure Marketplace マネージドアプリケーションに対してのみ指定されます。マネージドアプリケーションインスタンスの課金の詳細。 Azure Marketplace で使用量の詳細を照会するために使用できる `resourceUsageId` が含まれます。
`plan`	Azure Marketplace マネージドアプリケーションに対してのみ指定されます。マネージドアプリケーションインスタンスのパブリッシャー、オファー、SKU、およびバージョンを表します。
`error`	provisioningState が Failed の場合にのみ指定されます。エラーコード、メッセージ、およびエラーの原因となった問題の詳細が含まれます。

エンドポイントの認証

Webhook エンドポイントをセキュリティで保護し、通知の信頼性を確保するには、次のようにします。

https://your-endpoint.com?sig=Guid のように、Webhook URI に加えて、クエリパラメーターを指定します。各通知で、クエリパラメーター sig が予期された値 Guid を持っていることを確認します。
applicationId を使用してマネージドアプリケーションインスタンスに対して GET を発行します。一貫性を確保するために、provisioningState が通知の provisioningState と一致していることを確認します。

通知の再試行

マネージドアプリケーション通知サービスでは、Webhook エンドポイントから通知に対する 200 OK 応答があることを想定しています。 Webhook エンドポイントが 500 以上の HTTP エラーコードを返した場合、エラーコード 429 を返した場合、またはエンドポイントに一時的に到達できない場合、通知サービスは再試行します。 Webhook エンドポイントが 10 時間以内に利用可能にならない場合、通知メッセージは削除され、再試行は停止されます。

次の方法で共有

Azure Managed Applications と通知

作業の開始

サービスカタログアプリケーション定義の通知の追加

Azure portal

REST API

Azure Marketplace マネージドアプリケーション通知の追加

Event triggers (イベントトリガー)

通知スキーマ

サービスカタログアプリケーションの通知スキーマ

Azure Marketplace アプリケーションの通知スキーマ

エンドポイントの認証

通知の再試行

フィードバック

その他のリソース

次の方法で共有

Azure Managed Applications と通知

作業の開始

サービス カタログ アプリケーション定義の通知の追加

Azure portal

REST API

Azure Marketplace マネージド アプリケーション通知の追加

Event triggers (イベント トリガー)

通知スキーマ

サービス カタログ アプリケーションの通知スキーマ

Azure Marketplace アプリケーションの通知スキーマ

エンドポイントの認証

通知の再試行

フィードバック

その他のリソース

サービスカタログアプリケーション定義の通知の追加

Azure Marketplace マネージドアプリケーション通知の追加

Event triggers (イベントトリガー)

サービスカタログアプリケーションの通知スキーマ