Azure Managed Applications と通知

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

作業の開始

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

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

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

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

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

Azure portal

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

REST API

{
  "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 アプリケーション オファーを作成する」を参照してください。

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

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

通知スキーマ

通知を処理するために 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"
      }
    ]
  }
}

エンドポイントの認証

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

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

通知の再試行

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