Udostępnij za pośrednictwem

Śledzenie asynchronicznych operacji platformy Azure

  • Artykuł

Niektóre operacje REST platformy Azure są uruchamiane asynchronicznie, ponieważ nie można szybko wykonać operacji. W tym artykule opisano sposób śledzenia stanu operacji asynchronicznych za pomocą wartości zwracanych w odpowiedzi.

Kody stanu dla operacji asynchronicznych

Operacja asynchroniczna początkowo zwraca kod stanu HTTP jednego z następujących elementów:

  • 201 (Utworzono)
  • 202 (zaakceptowane)

Jednak ten kod stanu nie musi oznaczać, że operacja jest asynchroniczna. Operacja asynchroniczna zwraca również wartość, provisioningState która wskazuje, że operacja nie została zakończona. Wartość może się różnić w zależności od operacji, ale nie obejmuje powodzenia, niepowodzenia lub anulowania. Te trzy wartości wskazują, że operacja została zakończona. Jeśli nie zostanie zwrócona żadna wartość dla provisioningState, operacja została zakończona i zakończona pomyślnie.

Po pomyślnym zakończeniu operacji zwraca ona jedną z następujących wartości:

  • 200 (OK)
  • 204 (brak zawartości)

Zapoznaj się z dokumentacją interfejsu API REST, aby wyświetlić odpowiedzi dotyczące wykonywanej operacji.

Po uzyskaniu kodu odpowiedzi 201 lub 202 możesz monitorować stan operacji.

Adres URL do monitorowania stanu

Istnieją dwa różne sposoby monitorowania stanu operacji asynchronicznej. Należy określić poprawne podejście, sprawdzając wartości nagłówka zwracane z oryginalnego żądania. Najpierw poszukaj:

  • Azure-AsyncOperation — adres URL sprawdzania bieżącego stanu operacji. Jeśli operacja zwraca tę wartość, użyj jej do śledzenia stanu operacji.
  • Retry-After - Liczba sekund oczekiwania przed sprawdzeniem stanu operacji asynchronicznej.

Jeśli Azure-AsyncOperation nie jest jedną z wartości nagłówka, wyszukaj następujące elementy:

  • Location — adres URL określania, kiedy operacja została ukończona. Użyj tej wartości tylko wtedy, gdy Azure-AsyncOperation nie zostanie zwrócona.
  • Retry-After - Liczba sekund oczekiwania przed sprawdzeniem stanu operacji asynchronicznej.

Gdy nagłówek nie zostanie zwrócony, zaimplementuj Retry-after własną logikę ponawiania prób.

Uwaga

Klient REST musi zaakceptować minimalny rozmiar adresu URL wynoszący 4 KB dla Azure-AsyncOperation i Location.

Uprawnienie do śledzenia stanu asynchronicznego

Aby śledzić stan operacji asynchronicznej, potrzebujesz wystarczających uprawnień na poziomie grupy zasobów. Jeśli masz tylko uprawnienia na poziomie zasobu, możesz rozpocząć operację, ale nie możesz śledzić jego stanu. Uprawnienia na poziomie grupy zasobów są wymagane, ponieważ adres URL stanu śledzenia nie jest zakresem zasobu.

Aby na przykład uruchomić maszynę wirtualną, potrzebna jest rola Współautor maszyny wirtualnej dla grupy zasobów zawierającej maszynę wirtualną. Adres URL śledzenia żądania uruchomienia nie zawiera maszyny wirtualnej w swojej ścieżce.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Żądanie i odpowiedź azure-AsyncOperation

Jeśli masz adres URL z wartości nagłówka Azure-AsyncOperation , wyślij żądanie GET do tego adresu URL. Użyj wartości z Retry-After , aby zaplanować częstotliwość sprawdzania stanu. Otrzymasz obiekt odpowiedzi, który wskazuje stan operacji. Podczas sprawdzania stanu operacji przy użyciu Location adresu URL jest zwracana inna odpowiedź. Aby uzyskać więcej informacji na temat odpowiedzi z adresu URL lokalizacji, zobacz Create storage account (202 with Location and Retry-After) (Tworzenie konta magazynu (202 z lokalizacją i ponawianie próby po).

Właściwości odpowiedzi mogą się różnić, ale zawsze zawierają stan operacji asynchronicznej.

{
    "status": "{status-value}"
}

W poniższym przykładzie przedstawiono inne wartości, które mogą zostać zwrócone z operacji:

{
    "id": "{resource path from GET operation}",
    "name": "{operation-id}",
    "status" : "Succeeded | Failed | Canceled | {resource provider values}",
    "startTime": "2017-01-06T20:56:36.002812+00:00",
    "endTime": "2017-01-06T20:56:56.002812+00:00",
    "percentComplete": {double between 0 and 100 },
    "properties": {
        /* Specific resource provider values for successful operations */
    },
    "error" : {
        "code": "{error code}",  
        "message": "{error description}"
    }
}

Obiekt błędu jest zwracany, gdy stan to Niepowodzenie lub Anulowano. Wszystkie inne wartości są opcjonalne. Otrzymana odpowiedź może wyglądać inaczej niż w przykładzie.

provisioningState wartości

Operacje, które tworzą, aktualizują lub usuwają (PUT, PATCH, DELETE) zasób zwykle zwracają provisioningState wartość. Po zakończeniu operacji zwracana jest jedna z następujących trzech wartości:

  • Powodzenie
  • Nie działa
  • Anulowany

Wszystkie inne wartości wskazują, że operacja jest nadal uruchomiona. Dostawca zasobów może zwrócić dostosowaną wartość, która wskazuje jego stan. Na przykład otrzymasz komunikat Zaakceptowane, gdy żądanie zostanie odebrane i uruchomione.

Przykładowe żądania i odpowiedzi

Uruchamianie maszyny wirtualnej (202 z usługą Azure-AsyncOperation)

W tym przykładzie pokazano, jak określić stan operacji uruchamiania maszyn wirtualnych. Początkowe żądanie ma następujący format:

POST 
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2019-12-01

Zwraca kod stanu 202. Wśród wartości nagłówka zobaczysz:

Azure-AsyncOperation : https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Aby sprawdzić stan operacji asynchronicznej, wyślij kolejne żądanie do tego adresu URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Treść odpowiedzi zawiera stan operacji:

{
  "startTime": "2017-01-06T18:58:24.7596323+00:00",
  "status": "InProgress",
  "name": "9a062a88-e463-4697-bef2-fe039df73a02"
}

Wdrażanie zasobów (201 za pomocą polecenia Azure-AsyncOperation)

W tym przykładzie pokazano, jak określić stan operacji wdrożeń na potrzeby wdrażania zasobów na platformie Azure. Początkowe żądanie ma następujący format:

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/microsoft.resources/deployments/{deployment-name}?api-version=2020-06-01

Zwraca kod stanu 201. Treść odpowiedzi obejmuje:

"provisioningState":"Accepted",

Wśród wartości nagłówka zobaczysz:

Azure-AsyncOperation: https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Aby sprawdzić stan operacji asynchronicznej, wysyłając kolejne żądanie do tego adresu URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Treść odpowiedzi zawiera stan operacji:

{
    "status": "Running"
}

Po zakończeniu wdrażania odpowiedź zawiera:

{
    "status": "Succeeded"
}

Utwórz konto magazynu (202 z lokalizacją i ponów próbę po)

W tym przykładzie pokazano, jak określić stan operacji tworzenia dla kont magazynu. Początkowe żądanie ma następujący format:

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-name}?api-version=2019-06-01

Treść żądania zawiera właściwości konta magazynu:

{
    "location": "South Central US",
    "properties": {},
    "sku": {
        "name": "Standard_LRS"
    },
    "kind": "Storage"
}

Zwraca kod stanu 202. Wśród wartości nagłówka są widoczne następujące dwie wartości:

Location: https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01
Retry-After: 17

Po oczekiwaniu na liczbę sekund określonych w poleceniu Ponów próbę sprawdź stan operacji asynchronicznej, wysyłając kolejne żądanie do tego adresu URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01

Jeśli żądanie jest nadal uruchomione, otrzymasz kod stanu 202. Jeśli żądanie zostanie ukończone, otrzymasz kod stanu 200. Treść odpowiedzi zawiera właściwości utworzonego konta magazynu.

Następne kroki