Aplikacje zarządzane platformy Azure z powiadomieniami

Powiadomienia aplikacji zarządzanej platformy Azure umożliwiają wydawcom automatyzowanie akcji na podstawie zdarzeń cyklu życia wystąpień aplikacji zarządzanych. Wydawcy mogą określić niestandardowy punkt końcowy elementu webhook powiadomień, aby otrzymywać powiadomienia o zdarzeniach dotyczących nowych i istniejących wystąpień aplikacji zarządzanych. Wydawcy mogą konfigurować niestandardowe przepływy pracy w momencie aprowizacji, aktualizacji i usuwania aplikacji.

Wprowadzenie

Aby rozpocząć odbieranie powiadomień aplikacji zarządzanych, utwórz publiczny punkt końcowy HTTPS. Określ punkt końcowy podczas publikowania definicji aplikacji katalogu usług lub oferty witryny Microsoft Azure Marketplace.

Poniżej przedstawiono zalecane kroki umożliwiające szybkie rozpoczęcie pracy:

1. Utwórz publiczny punkt końcowy HTTPS, który rejestruje przychodzące żądania POST i zwraca wartość 200 OK.
2. Dodaj punkt końcowy do definicji aplikacji katalogu usług lub oferty witryny Azure Marketplace, jak wyjaśniono w dalszej części tego artykułu.
3. Utwórz wystąpienie aplikacji zarządzanej, które odwołuje się do definicji aplikacji lub oferty witryny Azure Marketplace.
4. Sprawdź, czy powiadomienia są odbierane.
5. Włącz autoryzację zgodnie z opisem w sekcji Uwierzytelnianie punktu końcowego w tym artykule.
6. Postępuj zgodnie z instrukcjami w sekcji Schemat powiadomień w tym artykule, aby przeanalizować żądania powiadomień i zaimplementować logikę biznesową na podstawie powiadomienia.

Dodawanie powiadomień definicji aplikacji katalogu usług

W poniższych przykładach pokazano, jak dodać identyfikator URI punktu końcowego powiadomień przy użyciu portalu lub interfejsu API REST.

Azure Portal

Aby rozpocząć, zobacz Szybki start: tworzenie i publikowanie definicji aplikacji zarządzanej platformy Azure.

Interfejs API REST

Uwaga

Można podać tylko jeden punkt końcowy we notificationEndpoints właściwości definicji aplikacji zarządzanej.

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

Dodawanie powiadomień aplikacji zarządzanych w witrynie Azure Marketplace

Aby uzyskać więcej informacji, zobacz Tworzenie oferty aplikacji platformy Azure.

Wyzwalacze zdarzeń

W poniższej tabeli opisano wszystkie możliwe kombinacje eventType i provisioningState ich wyzwalacze:

EventType	ProvisioningState	Wyzwalacz powiadomienia
ODŁÓŻ	Zaakceptowano	Zarządzana grupa zasobów została utworzona i przewidywana pomyślnie po uruchomieniu aplikacji PUT (przed rozpoczęciem wdrażania wewnątrz zarządzanej grupy zasobów).
ODŁÓŻ	Powodzenie	Pełna aprowizacja aplikacji zarządzanej powiodła się po put.
ODŁÓŻ	Niepowodzenie	Niepowodzenie inicjowania obsługi administracyjnej wystąpienia aplikacji w dowolnym momencie.
PATCH	Powodzenie	Po pomyślnym wprowadzeniu poprawki w wystąpieniu aplikacji zarządzanej w celu zaktualizowania tagów, zasad dostępu just in time (JIT) lub tożsamości zarządzanej.
DELETE	Usuwanie	Gdy tylko użytkownik zainicjuje usunięcie wystąpienia aplikacji zarządzanej.
DELETE	Usunięte	Po pełnym i pomyślnym usunięciu aplikacji zarządzanej.
DELETE	Niepowodzenie	Po wystąpieniu błędu podczas procesu anulowania aprowizacji, który blokuje usunięcie.

Schemat powiadomień

Podczas tworzenia punktu końcowego elementu webhook do obsługi powiadomień należy przeanalizować ładunek, aby uzyskać ważne właściwości, aby następnie podjąć działania na podstawie powiadomienia. Katalog usług i powiadomienia aplikacji zarządzanej w witrynie Azure Marketplace zawierają wiele tych samych właściwości, ale istnieją pewne różnice. Właściwość applicationDefinitionId ma zastosowanie tylko do katalogu usług. Właściwości billingDetails i plan dotyczą tylko witryny Azure Marketplace.

Platforma Azure dołącza /resource do identyfikatora URI punktu końcowego powiadomień podanego w definicji aplikacji zarządzanej. Punkt końcowy elementu webhook musi mieć możliwość obsługi powiadomień w identyfikatorze /resource URI. Jeśli na przykład podano identyfikator URI punktu końcowego powiadomień, taki jak https://fabrikam.com identyfikator URI punktu końcowego elementu webhook to https://fabrikam.com/resource.

Schemat powiadomień aplikacji katalogu usług

Poniższy przykład przedstawia powiadomienie katalogu usług po pomyślnym aprowizacji wystąpienia aplikacji zarządzanej.

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

Jeśli aprowizowanie nie powiedzie się, do określonego punktu końcowego zostanie wysłane powiadomienie ze szczegółami błędu.

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

Schemat powiadomień aplikacji w witrynie Azure Marketplace

Poniższy przykład przedstawia powiadomienie katalogu usług po pomyślnym aprowizacji wystąpienia aplikacji zarządzanej.

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

Jeśli aprowizowanie nie powiedzie się, do określonego punktu końcowego zostanie wysłane powiadomienie ze szczegółami błędu.

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

Właściwości	opis
eventType	Typ zdarzenia, które wyzwoliło powiadomienie. Na przykład PUT, PATCH, DELETE.
applicationId	W pełni kwalifikowany identyfikator zasobu aplikacji zarządzanej, dla której zostało wyzwolone powiadomienie.
eventTime	Sygnatura czasowa zdarzenia, które wyzwoliło powiadomienie. Data i godzina w formacie ISO 8601 w formacie UTC.
provisioningState	Stan aprowizacji wystąpienia aplikacji zarządzanej. Na przykład Powodzenie, Niepowodzenie, Usuwanie, Usuwanie.
applicationDefinitionId	Określone tylko dla aplikacji zarządzanych katalogu usług. Reprezentuje w pełni kwalifikowany identyfikator zasobu definicji aplikacji, dla której zainicjowano aprowizację wystąpienia aplikacji zarządzanej.
billingDetails	Określono tylko aplikacje zarządzane w witrynie Azure Marketplace. Szczegóły rozliczeń wystąpienia aplikacji zarządzanej. Zawiera element resourceUsageId , którego można użyć do wykonywania zapytań dotyczących witryny Azure Marketplace w celu uzyskania szczegółowych informacji o użyciu.
plan	Określono tylko aplikacje zarządzane w witrynie Azure Marketplace. Reprezentuje wydawcę, ofertę, jednostkę SKU i wersję wystąpienia aplikacji zarządzanej.
error	Określono tylko wtedy, gdy parametr provisioningState ma wartość Failed (Niepowodzenie). Zawiera kod błędu, komunikat i szczegóły problemu, które spowodowały awarię.

Uwierzytelnianie punktu końcowego

Aby zabezpieczyć punkt końcowy elementu webhook i zapewnić autentyczność powiadomienia:

1. Podaj parametr zapytania na podstawie identyfikatora URI elementu webhook, w następujący sposób: https://your-endpoint.com?sig=Guid. W przypadku każdego powiadomienia sprawdź, czy parametr sig zapytania ma oczekiwaną wartość Guid.
2. Wydaj polecenie GET w wystąpieniu aplikacji zarządzanej przy użyciu polecenia applicationId. Sprawdź, czy provisioningState element jest zgodny provisioningState z powiadomieniem, aby zapewnić spójność.

Ponawianie prób powiadomień

Usługa powiadomień aplikacji zarządzanej oczekuje 200 OK odpowiedzi z punktu końcowego elementu webhook do powiadomienia. Usługa powiadomień ponawia próbę, jeśli punkt końcowy elementu webhook zwraca kod błędu HTTP większy lub równy 500, zwraca kod błędu 429 lub jeśli punkt końcowy jest tymczasowo nieosiągalny. Jeśli punkt końcowy elementu webhook nie stanie się dostępny w ciągu 10 godzin, komunikat powiadomienia zostanie porzucony i zatrzymanie ponownych prób.