Referenční informace k rozhraní API HTTP

Rozšíření Durable Functions zveřejňuje sadu integrovaných rozhraní API HTTP, která můžou provádět úlohy správy na orchestrations, entities a task hubs. Tato rozhraní API HTTP jsou webhooky rozšiřitelnosti, které Azure Functions hostitel autorizuje, ale Durable Functions rozšíření zpracovává přímo.

Před použitím těchto rozhraní HTTP API se ujistěte, že máte:

Základní adresa URL a běžné parametry

Všechna rozhraní API HTTP sdílejí stejnou základní adresu URL jako vaše aplikace funkcí. Při místním vývoji pomocí nástrojů Azure Functions Core Tools je základní adresa URL obvykle http://localhost:7071. V hostované službě Azure Functions je základní adresa URL obvykle https://{appName}.azurewebsites.net. Rozšíření také podporuje vlastní názvy hostitelů, pokud jsou nakonfigurované v aplikaci App Service.

Všechna rozhraní HTTP API implementovaná rozšířením vyžadují následující parametry. Datový typ všech parametrů je string.

Parameter Typ parametru Description
taskHub Řetězec dotazu Název centra úloh. Pokud není zadaný, předpokládá se název centra úloh aktuální aplikace funkcí.
connection Řetězec dotazu Název nastavení aplikace připojení pro poskytovatele back-endového úložiště. Pokud není zadáno, předpokládá se výchozí konfigurace připojení pro aplikaci funkcí.
systemKey Řetězec dotazu Autorizační klíč potřebný k vyvolání rozhraní API.

Jak získat hodnoty parametrů

Použití vazeb klienta orchestrace (doporučeno): Automatické generování úplných adres URL pomocí rozhraní API pro vazby klienta orchestrace :

  • .NET: CreateCheckStatusResponse(), CreateHttpManagementPayload()
  • JavaScript: createCheckStatusResponse(), createHttpManagementPayload()

Ruční konstrukce adres URL:

  • taskHub: Načteno ze host.json souboru:

    • v2.x: extensions.durableTask.hubName
    • v1.x: durableTask.hubName
    • Dá se také nakonfigurovat prostřednictvím nastavení aplikace pomocí %AppSettingName% syntaxe.

  • connection: Název nastavení aplikace obsahující připojení k úložišti. Citováno z host.json:

    • v2.x: extensions.durableTask.storageProvider.connectionStringName (výchozí hodnota AzureWebJobsStorage je, pokud není zadána)
    • v1.x: durableTask.azureStorageConnectionStringName (výchozí hodnota AzureWebJobsStorage je v případě, že není zadána)
    • Může používat připojovací řetězce nebo připojení založená na identity (ověřování Microsoft Entra).

  • systemKey: Autorizační klíč specifický pro rozšíření pro rozhraní API durable task. Citováno z portálu Azure:

    1. Otevření aplikace funkcí
    2. Výběr funkcí → klávesy aplikace v nabídce vlevo
    3. V části Systémové klíče vyhledejte klíč (obvykle automaticky vygenerovaný pro rozšíření).
    4. Zkopírování hodnoty klíče

    ️ Zabezpečení poznámka: Systémový klíč uděluje přístup ke všem rozhraním API HTTP Durable Functions. Nesdílejte ho veřejně ani ho nezahrnujte do kódu na straně klienta.

Každé rozhraní HTTP API podporuje konzistentní sadu vzorů požadavků a odpovědí. Následující části obsahují informace pro každou operaci.

Běžný pracovní postup rozhraní API

Typický životní cyklus orchestrace se řídí tímto pořadím:

  1. Spuštění orchestrace → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → Vrátí ID instance a adresu URL stavu.
  2. Kontrola průběhu monitorování stavu → GET /runtime/webhooks/durabletask/instances/{instanceId} →
  3. Odeslání události (volitelné) → → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} odesílání externích signálů
  4. Vymazání (volitelné) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} historie vyprázdnění →

Podrobnosti o operacích a příklady požadavků a odpovědí najdete v následujících referenčních informacích.

Spustit orchestraci

Spustí novou instanci zadané funkce orchestrátoru.

Prosba

Důležité

Formát adresy URL se liší podle verze modulu runtime služby Functions. Vyberte formát, který odpovídá vašemu prostředí.

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
functionName URL Název funkce orchestrátora, kterou je třeba spustit.
instanceId URL Volitelný parametr. ID orchestrační instance. Pokud není zadáno, funkce orchestrátoru začíná id náhodné instance.
{content} Žádost o obsah Optional. Vstup funkce orchestrátoru ve formátu JSON.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (Přijato):: Zadaná funkce orchestrátoru byla naplánována tak, aby se spustila. Hlavička Location odpovědi obsahuje adresu URL pro dotazování stavu orchestrace.
  • HTTP 400 (Chybný požadavek):: Zadaná funkce orchestrátoru neexistuje, zadané ID instance není platné nebo obsah požadavku není platný ve formátu JSON.

Následuje příklad požadavku, který spustí funkci orchestrátoru RestartVMs a obsahuje datovou část objektu JSON:

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

{
    "resourceGroup": "myRG",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
}

Datová část odpovědi pro případy HTTP 202 je objekt JSON s následujícími poli:

Pole Description
id ID orchestrační instance.
statusQueryGetUri Adresa URL stavu instance orchestrace.
sendEventPostUri Adresa URL pro vyvolání události instance orchestrace.
terminatePostUri Adresa URL pro ukončení instance orchestrace.
purgeHistoryDeleteUri Adresa URL "historie vymazání" instance orkestrace.
rewindPostUri (Preview) Adresa URL "převinutí" instance orchestrace.
suspendPostUri Adresa URL pro pozastavení instance orchestrace.
resumePostUri Adresa URL pro obnovení instance orchestrace.

Datový typ všech polí je string.

Tady je příklad datové části odpovědi pro instanci orchestrace se abc123 svým ID (formátovaným pro čitelnost):

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

Odpověď HTTP je navržena tak, aby byla kompatibilní se Polling Consumer Pattern. Obsahuje také následující důležitá záhlaví odpovědí:

  • Umístění: Adresa URL koncového bodu stavu, která obsahuje stejnou hodnotu jako statusQueryGetUri pole.
  • Retry-After: Počet sekund, které čekáme mezi jednotlivými dotazovacími operacemi. Výchozí hodnota je 10.

Další informace o asynchronním vzoru dotazování HTTP najdete v dokumentaci ke sledování asynchronních operací HTTP .

Získání stavu instance

Získá stav zadané instance orchestrace. Slouží k monitorování průběhu orchestrace a načítání výsledků.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
instanceId URL ID orchestrační instance.
showInput Řetězec dotazu Volitelný parametr. Pokud je tato hodnota nastavená false, vstup funkce není součástí datové části odpovědi.
showHistory Řetězec dotazu Volitelný parametr. Pokud je tato možnost nastavená true, historie provádění orchestrace je zahrnuta do datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota true, výstupy funkce jsou zahrnuty v historii provádění orchestrace.
createdTimeFrom Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí, které byly vytvořeny v určený časový okamžik ISO8601 nebo po něm.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí, které byly vytvořeny v daném časovém razítku ISO8601 nebo před ním.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí na základě jejich stavu runtime. Seznam možných hodnot stavu modulu runtime najdete v článku Dotazování instancí .
returnInternalServerErrorOnFailure Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota true, vrátí toto rozhraní API místo 200 odpověď HTTP 500, pokud je instance ve stavu selhání. Tento parametr je určený pro scénáře automatizovaného dotazování stavu.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 200 (OK):: Zadaná instance je v dokončeném nebo neúspěšném stavu.
  • HTTP 202 (Přijato): Zadaná instance probíhá.
  • HTTP 400 (Chybný požadavek):: Zadaná instance se nezdařila nebo byla ukončena.
  • HTTP 404 (Nenalezena):: Zadaná instance neexistuje nebo se nespustila.
  • HTTP 500 (vnitřní chyba serveru): Vráceno pouze když je returnInternalServerErrorOnFailure nastavená na true a zadaná instance selhala s neošetřenou výjimkou.

Datová část odpovědi pro případy HTTP 200 a HTTP 202 je objekt JSON s následujícími poli:

Pole Datový typ Description
runtimeStatus řetězec Stav běhového prostředí instance. Mezi hodnoty patří Spuštěno, Čeká na vyřízení, Selhání, Zrušeno, Ukončeno, Dokončeno, Pozastaveno.
input JSON Data JSON použitá k inicializaci instance. Toto pole je null v případě, že parametr řetězce dotazu showInput je nastavený na hodnotu false.
customStatus JSON Data JSON používaná pro vlastní stav orchestrace. Toto pole je null, pokud není nastaveno.
output JSON JSON výstup instance. Toto pole je null v případě, že instance není v dokončeném stavu.
createdTime řetězec Čas vytvoření instance. Používá rozšířenou notaci ISO 8601.
lastUpdatedTime řetězec Čas, kdy instance naposledy přetrvala. Používá rozšířenou notaci ISO 8601.
historyEvents JSON Pole JSON obsahující historii provádění orchestrace. Pole je null, pokud není parametr řetězce dotazu showHistory nastaven na true.

Tady je příklad datové části odpovědi, včetně historie provádění orchestrace a výstupů aktivit (formátované pro čitelnost):

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

Odpověď HTTP 202 obsahuje také hlavičku odpovědi location , která odkazuje na stejnou adresu URL jako statusQueryGetUri pole uvedené výše.

Získání stavu všech instancí

Dotazuje stav více instancí orchestrace najednou. Výsledky můžete filtrovat podle stavu, času vytvoření a předpony ID instance. Pomocí této operace můžete monitorovat všechny aktivní orchestrace nebo vyhledat konkrétní instance.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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}

Modul runtime služby Functions 1.x (starší verze):

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}

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
showInput Řetězec dotazu Volitelný parametr. Pokud je tato hodnota nastavená false, vstup funkce není součástí datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota true, zahrnuje výstupy funkce v historii provádění orchestrace.
createdTimeFrom Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí, které byly vytvořeny v určený časový okamžik ISO8601 nebo po něm.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí, které byly vytvořeny v daném časovém razítku ISO8601 nebo před ním.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí na základě jejich stavu runtime. Seznam možných hodnot stavu modulu runtime najdete v článku Dotazování instancí .
instanceIdPrefix Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí tak, aby zahrnoval pouze instance, jejichž ID instance začíná zadaným řetězcem předpony. K dispozici od verze 2.7.2 rozšíření.
top Řetězec dotazu Volitelný parametr. Pokud je zadáno, omezí počet instancí vrácených dotazem.

odpověď

Tady je příklad datových částí odpovědí, včetně stavu orchestrace (naformátovaného pro čitelnost):

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

Poznámka:

Tato operace může být nákladná z hlediska Azure Storage vstupně-výstupních operací, pokud používáte poskytovatele Azure Storage a v tabulce Instances existuje mnoho řádků. Další informace o tabulce Instances najdete v dokumentaci k poskytovateli Azure Storage.

Pokud existuje více výsledků, v hlavičce odpovědi se vrátí token pro pokračování. Název záhlaví je x-ms-continuation-token.

Upozornění

Výsledek dotazu může vrátit méně položek, než je limit určený parametrem top. Když dostanete výsledky, měli byste vždy zkontrolovat, jestli existuje token pro pokračování.

Pokud nastavíte hodnotu tokenu pokračování v hlavičce dalšího požadavku, můžete získat další stránku výsledků. Název hlavičky požadavku je také x-ms-continuation-token.

Vymazání historie jedné instance

Odstraní historii a související artefakty pro zadanou instanci orchestrace. Tato operace uvolní prostředky úložiště a nedá se vrátit zpět.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
instanceId URL ID orchestrační instance.

odpověď

Je možné vrátit následující hodnoty stavového kódu HTTP.

  • HTTP 200 (OK): Historie instancí byla úspěšně vyprázdněna.
  • HTTP 404 (Nenalezena):: Zadaná instance neexistuje.

Datová část odpovědi pro případ HTTP 200 je objekt JSON s následujícím polem:

Pole Datový typ Description
instancesDeleted integer Počet odstraněných instancí. V případě jediné instance by tato hodnota měla být 1vždy .

Tady je příklad datové části odpovědi (formátovaná pro čitelnost):

{
    "instancesDeleted": 1
}

Vymazání historie více instancí

Odstraní historii a artefakty pro více instancí najednou, filtrované podle stavu, času vytvoření nebo předpony ID instance. Slouží k hromadnému vyčištění starých instancí a správě nákladů na úložiště.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
createdTimeFrom Řetězec dotazu Filtruje seznam odstraněných instancí, které byly vytvořeny v daném čase nebo po něm podle časového razítka ISO8601.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam odstraněných instancí, které byly vytvořeny v nebo před daným časovým razítkem ISO8601.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vyprázdněných instancí na základě jejich stavu runtime. Seznam možných hodnot stavu modulu runtime najdete v článku Dotazování instancí .

Poznámka:

Pokud používáte poskytovatele Azure Storage a v tabulkách Instance nebo Historie existuje mnoho řádků, může být tato operace nákladná z hlediska Azure Storage vstupně-výstupních operací. Další informace o těchto tabulkách najdete v tématu Performance a škálování v Durable Functions (Azure Functions).

odpověď

Je možné vrátit následující hodnoty stavového kódu HTTP.

  • HTTP 200 (OK): Historie instancí byla úspěšně vyprázdněna.
  • HTTP 404 (Nenalezena):: Nebyly nalezeny žádné instance, které odpovídají výrazu filtru.

Datová část odpovědi pro případ HTTP 200 je objekt JSON s následujícím polem:

Pole Datový typ Description
instancesDeleted integer Počet odstraněných instancí.

Tady je příklad datové části odpovědi (formátovaná pro čitelnost):

{
    "instancesDeleted": 250
}

Vyvolání události

Odešle zprávu s oznámením události do spuštěné instance orchestrace. Orchestrace musí čekat na tuto událost pomocí názvu nebo WaitForExternalEventwait_for_external_event.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
instanceId URL ID orchestrační instance.
eventName URL Název události, na kterou cílová instance orchestrace čeká.
{content} Žádost o obsah Datová část události ve formátu JSON.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (Accepted):: Událost vyvolání byla přijata ke zpracování.
  • HTTP 400 (Chybný požadavek):: Obsah požadavku nebyl typu application/json nebo nebyl platný JSON.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance se dokončila nebo selhala a nemůže zpracovat žádné vyvolané události.

Tady je příklad požadavku, který odešle řetězec "incr" JSON instanci, která čeká na událost pojmenovanou operace:

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

"incr"

Odpovědi pro toto rozhraní API neobsahují žádný obsah.

Ukončit instanci

Ukončí spuštěnou instanci orchestrace.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečný parametr.

Pole Typ parametru Description
instanceId URL ID orchestrační instance.
reason Řetězec dotazu Optional. Důvod ukončení instance orchestrace.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (přijato):: Žádost o ukončení byla přijata ke zpracování.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance byla dokončena nebo selhala.

Tady je příklad požadavku, který ukončí spuštěnou instanci a určuje důvod chyby:

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

Odpovědi pro toto rozhraní API neobsahují žádný obsah.

Pozastavení instance

Pozastaví spuštěnou instanci orchestrace bez ukončení. Instanci lze později obnovit pomocí resume operace.

Prosba

Ve verzi 2.x modulu runtime Functions je požadavek naformátovaný následujícím způsobem (pro přehlednost je zobrazeno více řádků):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Pole Typ parametru Description
instanceId URL ID orchestrační instance.
reason Řetězec dotazu Optional. Důvod pozastavení instance orchestrace.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (přijato):: Žádost o pozastavení byla přijata ke zpracování. Není vrácen žádný text odpovědi.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance se dokončila, selhala nebo ukončila a nelze ji pozastavit.

Ověření: Po přijetí http 202 zadejte dotaz na stav instance pomocí GET /runtime/webhooks/durabletask/instances/{instanceId} ověření, že runtimeStatus se změnil na "Suspended".

Obnovení instance

Obnoví provádění dříve pozastavené instance orchestrace.

Prosba

Ve verzi 2.x modulu runtime Functions je požadavek naformátovaný následujícím způsobem (pro přehlednost je zobrazeno více řádků):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Pole Typ parametru Description
instanceId URL ID orchestrační instance.
reason Řetězec dotazu Optional. Důvod obnovení instance orchestrace

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (přijato):: Žádost o obnovení byla přijata ke zpracování. Není vrácen žádný text odpovědi.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance se dokončila, selhala nebo ukončila a nelze ji obnovit.

Ověření: Po přijetí http 202 zadejte dotaz na stav instance pomocí GET /runtime/webhooks/durabletask/instances/{instanceId} ověření, že runtimeStatus se změnil na "Running".

Převinutí instance (náhled)

Obnoví instanci orchestrace, která selhala, do spuštěného stavu tak, že přehraje nejnovější neúspěšné operace. Tato funkce umožňuje obnovení z přechodných selhání bez ručního zásahu.

Prosba

Modul runtime služby Functions 2.x (doporučeno):

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

Modul runtime služby Functions 1.x (starší verze):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečný parametr.

Pole Typ parametru Description
instanceId URL ID orchestrační instance.
reason Řetězec dotazu Optional. Důvod pro převinutí instance orchestrace.

odpověď

Může se vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (Přijato):: Žádost o převinutí zpět byla přijata ke zpracování.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance byla dokončena nebo byla ukončena.

Tady je příklad požadavku, který převije instanci, která selhala, a určuje důvod pevného:

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

Odpovědi pro toto rozhraní API neobsahují žádný obsah.

Signální entita

Odešle jednosměrnou operační zprávu pro Durable Entity. Pokud entita neexistuje, vytvoří se automaticky. Operace entit se zpracovávají postupně a trvale se uchovávají.

Poznámka:

Odolné entity jsou dostupné od Durable Functions 2.0.

Prosba

Požadavek HTTP je naformátovaný následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
entityName URL Název (typ) entity.
entityKey URL Jedinečné ID (klíč) entity.
op Řetězec dotazu Optional. Název uživatelem definované operace, která se má vyvolat.
{content} Žádost o obsah Datová část události ve formátu JSON.

Tady je příklad požadavku, který odešle uživatelem definovanou zprávu Přidat do Counter entity s názvem steps. Obsah zprávy je hodnota 5. Pokud entita ještě neexistuje, vytvoří ji tato žádost:

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

5

Poznámka:

Ve výchozím nastavení s entitami založenými na class v .NET zadáte hodnotu opdelete odstraní stav entity. Pokud entita definuje operaci s názvem delete, je však vyvolána operace definovaná uživatelem.

odpověď

Tato operace má několik možných odpovědí:

  • HTTP 202 (přijato):: Operace signálu byla přijata pro asynchronní zpracování.
  • HTTP 400 (Chybný požadavek):: Obsah požadavku nebyl typu application/json, nebyl platný JSON nebo měl neplatnou entityKey hodnotu.
  • HTTP 404 (Nenalezena):: Zadaný entityName nebyl nalezen.

Úspěšný požadavek HTTP neobsahuje v odpovědi žádný obsah. Neúspěšný požadavek HTTP může v obsahu odpovědi obsahovat informace o chybách ve formátu JSON.

Získejte entitu

Získá stav zadané entity.

Prosba

Požadavek HTTP je naformátovaný následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

odpověď

Tato operace má dvě možné odpovědi:

  • HTTP 200 (OK):: Zadaná entita existuje.
  • HTTP 404 (Nenalezena):: Zadaná entita nebyla nalezena.

Úspěšná odpověď obsahuje serializovaný stav JSON entity jako jeho obsah.

Příklad

Získání stavu existující Counter entity s názvem steps:

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

Pokud entita Counter jednoduše obsahovala řadu kroků uložených v currentValue poli, může obsah odpovědi vypadat takto (formátovaný pro čitelnost):

{
    "currentValue": 5
}

Seznam entit

Dotaz na více entit můžete zadat podle názvu entity nebo data poslední operace.

Prosba

Požadavek HTTP je naformátovaný následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Parametry požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a následující jedinečné parametry:

Pole Typ parametru Description
entityName URL Optional. Po zadání filtruje seznam vrácených entit podle názvu entity (nerozlišují se malá a velká písmena).
fetchState Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota true, stav entity je součástí datové části odpovědi.
lastOperationTimeFrom Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených entit, které zpracovávaly operace po daném ISO8601 časovém razítku.
lastOperationTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených entit, které zpracovávaly operace před daným ISO8601 časovým razítkem.
top Řetězec dotazu Volitelný parametr. Po zadání omezí počet entit vrácených dotazem.

odpověď

Úspěšná odpověď HTTP 200 obsahuje serializované pole entit JSON a volitelně stav každé entity.

Ve výchozím nastavení vrátí operace prvních 100 entit, které odpovídají kritériím dotazu. Volající může zadat hodnotu parametru řetězce dotazu, aby top vrátil jiný maximální počet výsledků. Pokud nad rámec vrácených výsledků existuje více výsledků, vrátí se v hlavičce odpovědi také token pro pokračování. Název záhlaví je x-ms-continuation-token.

Pokud nastavíte hodnotu tokenu pokračování v hlavičce dalšího požadavku, můžete získat další stránku výsledků. Název hlavičky požadavku je také x-ms-continuation-token.

Příklad – výpis všech entit

Zobrazení seznamu všech entit v centru úloh:

GET /runtime/webhooks/durabletask/entities

JSON odpovědi může vypadat nějak takto (formátováno pro čitelnost):

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

Příklad – filtrování seznamu entit

Seznam prvních dvou counter entit a načtení jejich stavu:

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

JSON odpovědi může vypadat nějak takto (formátováno pro čitelnost):

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

Příklad kompletního pracovního postupu

Tento příklad ukazuje úplný životní cyklus orchestrace pomocí curl příkazů. Můžete také použít Postman, Thunder Client nebo jakýkoli klient HTTP.

1. Spuštění orchestrace

Spuštění nové ProcessOrder orchestrace se vstupními daty:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/orchestrators/ProcessOrder" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "amount": 150.00
  }'

Odpověď (HTTP 202):

{
  "id": "abc123def456",
  "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX",
  "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/{eventName}?code=XXX",
  "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/terminate?reason={text}&code=XXX"
}

Uložte ID instance: abc123def456

2. Hlasování o stavu

Kontrola průběhu orchestrace:

curl "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Odpověď při spuštění (HTTP 202):

{
  "runtimeStatus": "Running",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": null,
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:05Z"
}

Odpověď po dokončení (HTTP 200):

{
  "runtimeStatus": "Completed",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": { "status": "shipped", "trackingNumber": "TRK-98765" },
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:15Z"
}

3. Odeslání externí události (volitelné)

Pokud orchestrace čeká na schválení, odešlete událost schválení:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/ApprovalReceived?code=XXX" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true, "reviewer": "manager@contoso.com" }'

Odpověď: HTTP 202 (přijato)

4. Vyčištění historie (volitelné)

Po dokončení orchestrace vyprázdněte jeho historii:

curl -X DELETE "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Odpověď (HTTP 200):

{
  "instancesDeleted": 1
}

Další kroky

Naučte se používat Application Insights k monitorování trvalých funkcí.

  • Last updated on