Dokumentacja interfejsu API HTTP

  • Artykuł

Rozszerzenie Durable Functions uwidacznia zestaw wbudowanych interfejsów API HTTP, które mogą służyć do wykonywania zadań zarządzania w aranżacjach, jednostkach i centrach zadań. Te interfejsy API HTTP to elementy webhook rozszerzalności, które są autoryzowane przez hosta usługi Azure Functions, ale obsługiwane bezpośrednio przez rozszerzenie Durable Functions.

Podstawowy adres URL interfejsów API wymienionych w tym artykule jest taki sam jak podstawowy adres URL aplikacji funkcji. Podczas opracowywania lokalnego przy użyciu narzędzi Azure Functions Core Tools podstawowy adres URL to zazwyczaj http://localhost:7071. W usłudze hostowanej w usłudze Azure Functions podstawowy adres URL to zazwyczaj https://{appName}.azurewebsites.net. Niestandardowe nazwy hostów są również obsługiwane w przypadku skonfigurowania w aplikacji usługi App Service.

Wszystkie interfejsy API HTTP zaimplementowane przez rozszerzenie wymagają następujących parametrów. Typ danych wszystkich parametrów to string.

Parametr Typ parametru opis
taskHub Ciąg zapytania Nazwa centrum zadań. Jeśli nie zostanie określona, przyjmuje się nazwę centrum zadań bieżącej aplikacji funkcji.
connection Ciąg zapytania Nazwa ustawienia aplikacji połączenia dla dostawcy magazynu zaplecza. Jeśli nie zostanie określona, przyjmuje się domyślną konfigurację połączenia dla aplikacji funkcji.
systemKey Ciąg zapytania Klucz autoryzacji wymagany do wywołania interfejsu API.

systemKey jest automatycznie generowanym kluczem autoryzacji przez hosta usługi Azure Functions. W szczególności udziela ona dostępu do interfejsów API rozszerzenia Durable Task i może być zarządzana w taki sam sposób jak inne klucze dostępu usługi Azure Functions. Możesz wygenerować adresy URL zawierające poprawne taskHubwartości ciągów , connectioni systemKey zapytań przy użyciu interfejsów API powiązań klienta orkiestracji, takich jak CreateCheckStatusResponse interfejsy API i CreateHttpManagementPayload na platformie .NET, createCheckStatusResponse interfejsy API i createHttpManagementPayload w języku JavaScript itp.

W następnych kilku sekcjach omówiono konkretne interfejsy API HTTP obsługiwane przez rozszerzenie i przedstawiono przykłady ich użycia.

Rozpocznij aranżację

Rozpoczyna wykonywanie nowego wystąpienia określonej funkcji orkiestratora.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
functionName Adres URL Nazwa funkcji orkiestratora do uruchomienia.
instanceId URL Opcjonalny parametr. Identyfikator wystąpienia aranżacji. Jeśli nie zostanie określony, funkcja orkiestratora rozpocznie się od identyfikatora wystąpienia losowego.
{content} Żądanie zawartości Opcjonalny. Dane wejściowe funkcji orkiestratora w formacie JSON.

Response

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): określona funkcja orkiestratora została zaplanowana na uruchomienie. Nagłówek Location odpowiedzi zawiera adres URL sondowania stanu aranżacji.
  • HTTP 400 (nieprawidłowe żądanie): określona funkcja orkiestratora nie istnieje, określony identyfikator wystąpienia był nieprawidłowy lub zawartość żądania była nieprawidłowa w formacie JSON.

Poniżej przedstawiono przykładowe żądanie, które uruchamia funkcję orkiestratora RestartVMs i zawiera ładunek obiektu JSON:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

Ładunek odpowiedzi dla przypadków HTTP 202 jest obiektem JSON z następującymi polami:

Pole opis
id Identyfikator wystąpienia aranżacji.
statusQueryGetUri Adres URL stanu wystąpienia aranżacji.
sendEventPostUri Adres URL "podnieś zdarzenie" wystąpienia orkiestracji.
terminatePostUri Adres URL "zakończ" wystąpienia orkiestracji.
purgeHistoryDeleteUri Adres URL "przeczyszczania historii" wystąpienia orkiestracji.
rewindPostUri (wersja zapoznawcza) Adres URL "przewijania" wystąpienia orkiestracji.
suspendPostUri Adres URL "suspend" wystąpienia orkiestracji.
resumePostUri Adres URL "resume" wystąpienia orkiestracji.

Typ danych wszystkich pól to string.

Oto przykładowy ładunek odpowiedzi dla wystąpienia orkiestracji z identyfikatorem abc123 (sformatowanym pod kątem czytelności):

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/suspend?reason={text}&code=XXX",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/resume?reason={text}&code=XXX"
}

Odpowiedź HTTP ma być zgodna ze wzorcem sondowania konsumenta. Zawiera również następujące istotne nagłówki odpowiedzi:

  • Lokalizacja: adres URL punktu końcowego stanu. Ten adres URL zawiera tę samą wartość co statusQueryGetUri pole.
  • Ponów próbę po: liczba sekund oczekiwania między operacjami sondowania. Domyślna wartość to 10.

Aby uzyskać więcej informacji na temat asynchronicznego wzorca sondowania HTTP, zobacz dokumentację śledzenia operacji asynchronicznych HTTP.

Uzyskiwanie stanu wystąpienia

Pobiera stan określonego wystąpienia orkiestracji.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
showInput Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono falsewartość , dane wejściowe funkcji nie zostaną uwzględnione w ładunku odpowiedzi.
showHistory Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono wartość true, historia wykonywania orkiestracji zostanie uwzględniona w ładunku odpowiedzi.
showHistoryOutput Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono wartość true, dane wyjściowe funkcji zostaną uwzględnione w historii wykonywania orkiestracji.
createdTimeFrom Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwróconych wystąpień, które zostały utworzone pod adresem lub po danym znaczniku czasu ISO8601.
createdTimeTo Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwróconych wystąpień, które zostały utworzone na lub przed danym ISO8601 sygnaturą czasową.
runtimeStatus Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwracanych wystąpień na podstawie ich stanu środowiska uruchomieniowego. Aby wyświetlić listę możliwych wartości stanu środowiska uruchomieniowego, zobacz artykuł Querying instances (Wykonywanie zapytań dotyczących wystąpień ).
returnInternalServerErrorOnFailure Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono truewartość , ten interfejs API zwróci odpowiedź HTTP 500 zamiast 200, jeśli wystąpienie jest w stanie awarii. Ten parametr jest przeznaczony dla scenariuszy automatycznego sondowania stanu.

Response

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 200 (OK): określone wystąpienie jest w stanie ukończonym lub niepowodzeniem.
  • HTTP 202 (Zaakceptowane): określone wystąpienie jest w toku.
  • HTTP 400 (nieprawidłowe żądanie): określone wystąpienie nie powiodło się lub zostało zakończone.
  • HTTP 404 (Nie znaleziono): określone wystąpienie nie istnieje lub nie zostało uruchomione.
  • HTTP 500 (wewnętrzny błąd serwera): zwracany tylko wtedy, gdy returnInternalServerErrorOnFailure jest ustawiona wartość true i określone wystąpienie nie powiodło się z nieobsługiwanym wyjątkiem.

Ładunek odpowiedzi dla przypadków HTTP 200 i HTTP 202 jest obiektem JSON z następującymi polami:

Pole Typ danych opis
runtimeStatus string Stan środowiska uruchomieniowego wystąpienia. Wartości obejmują Uruchomione, Oczekujące, Nieudane, Anulowane, Zakończone, Wstrzymane.
input JSON Dane JSON używane do inicjowania wystąpienia. To pole ma null wartość , jeśli showInput parametr ciągu zapytania ma wartość false.
customStatus JSON Dane JSON używane do niestandardowego stanu aranżacji. To pole jest null , jeśli nie jest ustawione.
output JSON Dane wyjściowe JSON wystąpienia. To pole jest null , jeśli wystąpienie nie jest w stanie ukończonym.
createdTime string Czas utworzenia wystąpienia. Używa rozszerzonej notacji ISO 8601.
lastUpdatedTime string Czas ostatniego utrwalonego wystąpienia. Używa rozszerzonej notacji ISO 8601.
historyEvents JSON Tablica JSON zawierająca historię wykonywania orkiestracji. To pole ma null wartość , chyba że showHistory parametr ciągu zapytania ma wartość true.

Oto przykładowy ładunek odpowiedzi, w tym historia wykonywania orkiestracji i dane wyjściowe działań (sformatowane pod kątem czytelności):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

Odpowiedź HTTP 202 zawiera również nagłówek odpowiedzi Lokalizacja, który odwołuje się do tego samego adresu URL co statusQueryGetUri wymienione wcześniej pole.

Pobieranie stanu wszystkich wystąpień

Możesz również wykonać zapytanie dotyczące stanu wszystkich wystąpień, usuwając element instanceId z żądania "Pobierz stan wystąpienia". W tym przypadku podstawowe parametry są takie same jak "Pobierz stan wystąpienia". Parametry ciągu zapytania do filtrowania są również obsługiwane.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
showInput Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono falsewartość , dane wejściowe funkcji nie zostaną uwzględnione w ładunku odpowiedzi.
showHistoryOutput Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono wartość true, dane wyjściowe funkcji zostaną uwzględnione w historii wykonywania orkiestracji.
createdTimeFrom Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwróconych wystąpień, które zostały utworzone pod adresem lub po danym znaczniku czasu ISO8601.
createdTimeTo Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwróconych wystąpień, które zostały utworzone na lub przed danym ISO8601 sygnaturą czasową.
runtimeStatus Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwracanych wystąpień na podstawie ich stanu środowiska uruchomieniowego. Aby wyświetlić listę możliwych wartości stanu środowiska uruchomieniowego, zobacz artykuł Querying instances (Wykonywanie zapytań dotyczących wystąpień ).
instanceIdPrefix Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwracanych wystąpień w celu uwzględnienia tylko wystąpień, których identyfikator wystąpienia rozpoczyna się od określonego ciągu prefiksu. Dostępne od wersji 2.7.2 rozszerzenia.
top Ciąg zapytania Opcjonalny parametr. Po określeniu ogranicza liczbę wystąpień zwracanych przez zapytanie.

Response

Oto przykład ładunków odpowiedzi, w tym stan aranżacji (sformatowany pod kątem czytelności):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Uwaga

Ta operacja może być bardzo kosztowna w zakresie operacji we/wy usługi Azure Storage, jeśli używasz domyślnego dostawcy usługi Azure Storage i jeśli w tabeli Instances znajduje się wiele wierszy. Więcej informacji na temat tabeli Wystąpienia można znaleźć w dokumentacji dostawcy usługi Azure Storage.

Jeśli istnieje więcej wyników, token kontynuacji zostanie zwrócony w nagłówku odpowiedzi. Nazwa nagłówka to x-ms-continuation-token.

Uwaga

Wynik zapytania może zwrócić mniej elementów niż limit określony przez top. Podczas odbierania wyników zawsze należy sprawdzić, czy istnieje token kontynuacji.

Jeśli ustawisz wartość tokenu kontynuacji w następnym nagłówku żądania, możesz uzyskać następną stronę wyników. Ta nazwa nagłówka żądania to również x-ms-continuation-token.

Przeczyszczanie historii pojedynczego wystąpienia

Usuwa historię i powiązane artefakty dla określonego wystąpienia orkiestracji.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.

Response

Można zwrócić następujące wartości kodu stanu HTTP.

  • HTTP 200 (OK): historia wystąpienia została pomyślnie przeczyszczone.
  • HTTP 404 (Nie znaleziono): określone wystąpienie nie istnieje.

Ładunek odpowiedzi dla przypadku HTTP 200 jest obiektem JSON z następującym polem:

Pole Typ danych opis
instancesDeleted integer Liczba usuniętych wystąpień. W przypadku pojedynczego wystąpienia ta wartość powinna zawsze mieć wartość 1.

Oto przykładowy ładunek odpowiedzi (sformatowany pod kątem czytelności):

{
    "instancesDeleted": 1
}

Przeczyszczanie wielu historii wystąpień

Możesz również usunąć historię i powiązane artefakty dla wielu wystąpień w centrum zadań, usuwając {instanceId} żądanie "Przeczyść historię pojedynczego wystąpienia". Aby selektywnie przeczyścić historię wystąpień, użyj tych samych filtrów opisanych w żądaniu "Pobierz wszystkie wystąpienia stanu".

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
createdTimeFrom Ciąg zapytania Filtruje listę przeczyszczonych wystąpień, które zostały utworzone pod adresem lub po danym znaczniku czasu ISO8601.
createdTimeTo Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę przeczyszczonych wystąpień, które zostały utworzone na lub przed danym ISO8601 sygnaturą czasową.
runtimeStatus Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę przeczyszczonych wystąpień na podstawie ich stanu środowiska uruchomieniowego. Aby wyświetlić listę możliwych wartości stanu środowiska uruchomieniowego, zobacz artykuł Querying instances (Wykonywanie zapytań dotyczących wystąpień ).

Uwaga

Ta operacja może być bardzo kosztowna pod względem operacji we/wy usługi Azure Storage, jeśli używasz domyślnego dostawcy usługi Azure Storage i jeśli istnieje wiele wierszy w tabelach Wystąpienia i/lub Historia. Więcej informacji na temat tych tabel można znaleźć w dokumentacji Dotyczącej wydajności i skalowania w usłudze Durable Functions (Azure Functions).

Response

Można zwrócić następujące wartości kodu stanu HTTP.

  • HTTP 200 (OK): historia wystąpienia została pomyślnie przeczyszczone.
  • HTTP 404 (Nie znaleziono): nie znaleziono wystąpień pasujących do wyrażenia filtru.

Ładunek odpowiedzi dla przypadku HTTP 200 jest obiektem JSON z następującym polem:

Pole Typ danych opis
instancesDeleted integer Liczba usuniętych wystąpień.

Oto przykładowy ładunek odpowiedzi (sformatowany pod kątem czytelności):

{
    "instancesDeleted": 250
}

Zgłoś zdarzenie

Wysyła komunikat powiadomienia o zdarzeniu do uruchomionego wystąpienia orkiestracji.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
eventName URL Nazwa zdarzenia, na które oczekuje wystąpienie orkiestracji docelowej.
{content} Żądanie zawartości Ładunek zdarzeń w formacie JSON.

Response

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): zgłoszone zdarzenie zostało zaakceptowane do przetworzenia.
  • HTTP 400 (nieprawidłowe żądanie): zawartość żądania nie była typu application/json lub była nieprawidłowa w formacie JSON.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonego wystąpienia.
  • HTTP 410 (Gone): określone wystąpienie zostało ukończone lub zakończone niepowodzeniem i nie może przetworzyć żadnych zgłoszonych zdarzeń.

Oto przykładowe żądanie, które wysyła ciąg "incr" JSON do wystąpienia oczekującego na zdarzenie o nazwie operation:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

Odpowiedzi dla tego interfejsu API nie zawierają żadnej zawartości.

Zakończenie wystąpienia

Przerywa uruchomione wystąpienie orkiestracji.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujący unikatowy parametr.

Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
reason Ciąg zapytania Opcjonalny. Przyczyna zakończenia wystąpienia orkiestracji.

Response

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): żądanie zakończenia zostało zaakceptowane do przetworzenia.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonego wystąpienia.
  • HTTP 410 (Gone): określone wystąpienie zostało ukończone lub nie powiodło się.

Oto przykładowe żądanie, które kończy uruchomione wystąpienie i określa przyczynę błędu:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Odpowiedzi dla tego interfejsu API nie zawierają żadnej zawartości.

Wstrzymywanie wystąpienia

Zawiesza uruchomione wystąpienie orkiestracji.

Zażądaj

W wersji 2.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
reason Ciąg zapytania Opcjonalny. Przyczyna zawieszenia wystąpienia orkiestracji.

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): żądanie zawieszenia zostało zaakceptowane do przetworzenia.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonego wystąpienia.
  • HTTP 410 (Gone): określone wystąpienie zostało ukończone, zakończone niepowodzeniem lub zakończone.

Odpowiedzi dla tego interfejsu API nie zawierają żadnej zawartości.

Wznów wystąpienie

Wznawia zawieszone wystąpienie orkiestracji.

Zażądaj

W wersji 2.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
reason Ciąg zapytania Opcjonalny. Przyczyna wznowienia wystąpienia aranżacji.

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): żądanie wznowienia zostało zaakceptowane do przetworzenia.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonego wystąpienia.
  • HTTP 410 (Gone): określone wystąpienie zostało ukończone, zakończone niepowodzeniem lub zakończone.

Odpowiedzi dla tego interfejsu API nie zawierają żadnej zawartości.

Ponowne przewijanie wystąpienia (wersja zapoznawcza)

Przywraca wystąpienie orkiestracji, które zakończyło się niepowodzeniem, w stanie uruchomienia przez odtworzenie najnowszych operacji, które zakończyły się niepowodzeniem.

Zażądaj

W przypadku wersji 1.x środowiska uruchomieniowego usługi Functions żądanie jest sformatowane w następujący sposób (wiele wierszy jest wyświetlanych w celu zapewnienia przejrzystości):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

W wersji 2.x środowiska uruchomieniowego usługi Functions format adresu URL ma wszystkie te same parametry, ale z nieco innym prefiksem:

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujący unikatowy parametr.

Pole Typ parametru opis
instanceId Adres URL Identyfikator wystąpienia aranżacji.
reason Ciąg zapytania Opcjonalny. Przyczyna ponownego przewijania wystąpienia aranżacji.

Response

Można zwrócić kilka możliwych wartości kodu stanu.

  • HTTP 202 (Zaakceptowane): żądanie przewijania zostało zaakceptowane do przetworzenia.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonego wystąpienia.
  • HTTP 410 (Gone): określone wystąpienie zostało ukończone lub zostało zakończone.

Oto przykładowe żądanie, które przewija wystąpienie, które zakończyło się niepowodzeniem i określa przyczynę naprawy:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Odpowiedzi dla tego interfejsu API nie zawierają żadnej zawartości.

Jednostka sygnału

Wysyła jednokierunkowy komunikat operacji do jednostki trwałej. Jeśli jednostka nie istnieje, zostanie utworzona automatycznie.

Uwaga

Jednostki trwałe są dostępne od wersji Durable Functions 2.0.

Zażądaj

Żądanie HTTP jest sformatowane w następujący sposób (w celu zapewnienia przejrzystości jest wyświetlanych wiele wierszy):

POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
entityName Adres URL Nazwa (typ) jednostki.
entityKey URL Klucz (unikatowy identyfikator) jednostki.
op Ciąg zapytania Opcjonalny. Nazwa operacji zdefiniowanej przez użytkownika do wywołania.
{content} Żądanie zawartości Ładunek zdarzeń w formacie JSON.

Oto przykładowe żądanie, które wysyła zdefiniowany przez użytkownika komunikat "Dodaj" do Counter jednostki o nazwie steps. Zawartość komunikatu to wartość 5. Jeśli jednostka jeszcze nie istnieje, zostanie utworzona przez następujące żądanie:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

Uwaga

Domyślnie w przypadku jednostek opartych na klasach na platformie .NET określenie op wartości delete spowoduje usunięcie stanu jednostki. Jeśli jednak jednostka definiuje operację o nazwie delete, zamiast tego zostanie wywołana operacja zdefiniowana przez użytkownika.

Response

Ta operacja ma kilka możliwych odpowiedzi:

  • HTTP 202 (Zaakceptowane): operacja sygnału została zaakceptowana do przetwarzania asynchronicznego.
  • HTTP 400 (nieprawidłowe żądanie): zawartość żądania nie była typu application/json, była nieprawidłowa w formacie JSON lub miała nieprawidłową entityKey wartość.
  • HTTP 404 (Nie znaleziono): Nie można odnaleźć określonego entityName elementu.

Pomyślne żądanie HTTP nie zawiera żadnej zawartości w odpowiedzi. Żądanie HTTP, które zakończyło się niepowodzeniem, może zawierać informacje o błędzie sformatowane w formacie JSON w zawartości odpowiedzi.

Pobieranie jednostki

Pobiera stan określonej jednostki.

Zażądaj

Żądanie HTTP jest sformatowane w następujący sposób (w celu zapewnienia przejrzystości jest wyświetlanych wiele wierszy):

GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Response

Ta operacja ma dwie możliwe odpowiedzi:

  • HTTP 200 (OK): określona jednostka istnieje.
  • HTTP 404 (Nie znaleziono): nie znaleziono określonej jednostki.

Pomyślna odpowiedź zawiera stan serializowany JSON jednostki jako jego zawartość.

Przykład

Następujące przykładowe żądanie HTTP pobiera stan istniejącej Counter jednostki o nazwie steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

Counter Jeśli jednostka zawiera po prostu kilka kroków zapisanych w currentValue polu, zawartość odpowiedzi może wyglądać następująco (sformatowana pod kątem czytelności):

{
    "currentValue": 5
}

Lista jednostek

Zapytania dotyczące wielu jednostek można wykonywać według nazwy jednostki lub daty ostatniej operacji.

Zażądaj

Żądanie HTTP jest sformatowane w następujący sposób (w celu zapewnienia przejrzystości jest wyświetlanych wiele wierszy):

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

Parametry żądania dla tego interfejsu API obejmują zestaw domyślny wymieniony wcześniej, a także następujące unikatowe parametry:

Pole Typ parametru opis
entityName Adres URL Opcjonalny. Po określeniu filtruje listę zwracanych jednostek według nazwy jednostki (bez uwzględniania wielkości liter).
fetchState Ciąg zapytania Opcjonalny parametr. Jeśli ustawiono wartość true, stan jednostki zostanie uwzględniony w ładunku odpowiedzi.
lastOperationTimeFrom Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwracanych jednostek, które przetwarzały operacje po danym znaczniku czasu ISO8601.
lastOperationTimeTo Ciąg zapytania Opcjonalny parametr. Po określeniu filtruje listę zwracanych jednostek, które przetwarzały operacje przed danym ISO8601 sygnaturą czasowa.
top Ciąg zapytania Opcjonalny parametr. Po określeniu ogranicza liczbę jednostek zwracanych przez zapytanie.

Response

Pomyślna odpowiedź HTTP 200 zawiera serializacji JSON tablicę jednostek i opcjonalnie stan każdej jednostki.

Domyślnie operacja zwraca pierwsze 100 jednostek, które spełniają kryteria zapytania. Obiekt wywołujący może określić wartość parametru ciągu zapytania, top aby zwrócić inną maksymalną liczbę wyników. Jeśli więcej wyników istnieje poza zwracanym elementem, token kontynuacji jest również zwracany w nagłówku odpowiedzi. Nazwa nagłówka to x-ms-continuation-token.

Jeśli ustawisz wartość tokenu kontynuacji w następnym nagłówku żądania, możesz uzyskać następną stronę wyników. Ta nazwa nagłówka żądania to również x-ms-continuation-token.

Przykład — wyświetlanie listy wszystkich jednostek

Następujące przykładowe żądanie HTTP wyświetla listę wszystkich jednostek w centrum zadań:

GET /runtime/webhooks/durabletask/entities

Kod JSON odpowiedzi może wyglądać następująco (sformatowany pod kątem czytelności):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

Przykład — filtrowanie listy jednostek

Następujące przykładowe żądanie HTTP zawiera tylko dwie pierwsze jednostki typu counter , a także pobiera ich stan:

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

Kod JSON odpowiedzi może wyglądać następująco (sformatowany pod kątem czytelności):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

Następne kroki

Dowiedz się, jak używać Szczegółowe informacje aplikacji do monitorowania trwałych funkcji