Referenční informace k rozhraní API HTTP

  • Článek

Rozšíření Durable Functions zveřejňuje sadu integrovaných rozhraní API HTTP, která se dají použít k provádění úloh správy v orchestracích, entitách a centrech úloh. Tato rozhraní HTTP API jsou webhooky rozšiřitelnosti, které jsou autorizované hostitelem služby Azure Functions, ale zpracovávají se přímo rozšířením Durable Functions.

Základní adresa URL pro rozhraní API uvedená v tomto článku je stejná jako základní adresa URL vaší aplikace funkcí. Při vývoji místně pomocí nástrojů Azure Functions Core Tools je obvykle http://localhost:7071základní adresa URL . V hostované službě Azure Functions je základní adresa URL obvykle https://{appName}.azurewebsites.net. Vlastní názvy hostitelů se podporují také v případě, že 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.

Parametr Typ parametru Popis
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.

systemKey je autorizační klíč automaticky vygenerovaný hostitelem Azure Functions. Konkrétně uděluje přístup k rozhraním API rozšíření Durable Task a dá se spravovat stejným způsobem jako ostatní přístupové klíče Azure Functions. Můžete vygenerovat adresy URL, které obsahují správné connectionsystemKeytaskHubhodnoty a řetězcové hodnoty dotazu pomocí rozhraní API pro vazby klienta orchestrace, jako CreateCheckStatusResponse jsou rozhraní API a CreateHttpManagementPayload rozhraní API v .NET, createCheckStatusResponse rozhraní API a createHttpManagementPayload rozhraní API v JavaScriptu atd.

V následujících několika částech najdete informace o konkrétních rozhraních API HTTP podporovaných rozšířením a uveďte příklady jejich použití.

Zahájení orchestrace

Spustí novou instanci zadané funkce orchestrátoru.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

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

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

Pole Typ parametru Popis
functionName Adresa URL Název funkce orchestrátoru, který se má spustit.
instanceId Adresa URL Volitelný parametr. ID instance orchestrace. Pokud není zadáno, funkce orchestrátoru začne s ID náhodné instance.
{content} Žádost o obsah Nepovinné. Vstup funkce orchestrátoru ve formátu JSON.

Response

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 nebylo platné nebo obsah požadavku nebyl platný 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": "111deb5d-09df-4604-992e-a968345530a9"
}

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

Pole Popis
id ID instance orchestrace.
statusQueryGetUri Adresa URL stavu instance orchestrace.
sendEventPostUri Adresa URL "vyvolání události" instance orchestrace.
terminatePostUri Adresa URL "terminate" instance orchestrace.
purgeHistoryDeleteUri Adresa URL "vyprázdnění historie" instance orchestrace.
rewindPostUri (Preview) Adresa URL "převinutí" instance orchestrace.
suspendPostUri Adresa URL pro pozastavení instance orchestrace.
resumePostUri Adresa URL "resume" 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 určená tak, aby byla kompatibilní se vzorem příjemce dotazování. Obsahuje také následující důležitá záhlaví odpovědí:

  • Umístění: Adresa URL koncového bodu stavu. Tato adresa URL obsahuje stejnou hodnotu jako statusQueryGetUri pole.
  • Opakování po: Počet sekund čekání mezi operacemi dotazování. 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.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

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 požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a také následující jedinečné parametry:

Pole Typ parametru Popis
instanceId Adresa URL ID instance orchestrace.
showInput Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota false, vstup funkce nebude zahrnut do datové části odpovědi.
showHistory Řetězec dotazu Volitelný parametr. Pokud je tato možnost nastavená true, bude historie provádění orchestrace zahrnuta do datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je tato možnost nastavená true, budou výstupy funkce zahrnuty do historie provádění orchestrace.
createdTimeFrom Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném ISO8601 časovém razítku nebo za tímto ISO8601.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném ISO8601 časové razítko nebo před tímto časovým razítkem.
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 odpověď HTTP 500 místo 200, pokud je instance ve stavu selhání. Tento parametr je určený pro scénáře automatizovaného dotazování stavu.

Response

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 v případě returnInternalServerErrorOnFailure , že je nastavená 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 Popis
runtimeStatus string Stav modulu runtime 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 showInput je parametr řetězce dotazu nastavený na falsehodnotu .
customStatus JSON Data JSON používaná pro vlastní stav orchestrace. Toto pole není null nastaveno.
output JSON Výstup JSON instance. Toto pole je null v případě, že instance není v dokončeném stavu.
createdTime string Čas vytvoření instance. Používá rozšířenou notaci ISO 8601.
lastUpdatedTime string Čas, kdy instance naposledy trvala. Používá rozšířenou notaci ISO 8601.
historyEvents JSON Pole JSON obsahující historii provádění orchestrace. Toto pole není null nastaveno showHistory na trueparametr řetězce dotazu .

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í

Stav všech instancí můžete také dotazovat odebráním instanceId požadavku Získat stav instance. V tomto případě jsou základní parametry stejné jako stav get instance. Podporují se také parametry řetězce dotazu pro filtrování.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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}

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

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 požadavku pro toto rozhraní API zahrnují výchozí sadu uvedenou dříve a také následující jedinečné parametry:

Pole Typ parametru Popis
showInput Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota false, vstup funkce nebude zahrnut do datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je tato možnost nastavená true, budou výstupy funkce zahrnuty do historie provádění orchestrace.
createdTimeFrom Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném ISO8601 časovém razítku nebo za tímto ISO8601.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném ISO8601 časové razítko nebo před tímto časovým razítkem.
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. Po zadání omezí počet instancí vrácených dotazem.

Response

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 velmi náročná z hlediska vstupně-výstupních operací služby Azure Storage, pokud používáte výchozího poskytovatele služby Azure Storage a pokud je v tabulce Instances hodně řádků. Další podrobnosti o tabulce instancí najdete v dokumentaci poskytovatele služby 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. Při příjmu výsledků byste proto měli 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ů. Tento 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.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

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

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

Pole Typ parametru Popis
instanceId Adresa URL ID instance orchestrace.

Response

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 Popis
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í více historie instancí

Můžete také odstranit historii a související artefakty pro více instancí v centru úloh odebráním {instanceId} požadavku vyprázdnit historii jedné instance. Pokud chcete selektivně vyprázdnit historii instancí, použijte stejné filtry popsané v požadavku Získat stav všech instancí.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

DELETE /runtime/webhooks/durabletask/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 také následující jedinečné parametry:

Pole Typ parametru Popis
createdTimeFrom Řetězec dotazu Filtruje seznam vyprázdněných instancí vytvořených v daném ISO8601 časovém razítku nebo za tímto ISO8601.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vyprázdněných instancí vytvořených před daným ISO8601 časovým razítkem.
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:

Tato operace může být velmi náročná z hlediska vstupně-výstupních operací služby Azure Storage, pokud používáte výchozího poskytovatele služby Azure Storage a pokud v tabulkách Instance a/nebo History existuje mnoho řádků. Další podrobnosti o těchto tabulkách najdete v dokumentaci k výkonu a škálování v Durable Functions (Azure Functions).

Response

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 Popis
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.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

POST /runtime/webhooks/durabletask/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 také následující jedinečné parametry:

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

Response

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 byla dokončena 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 pojmenovanou operaci události:

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.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

POST /runtime/webhooks/durabletask/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 také následující jedinečný parametr.

Pole Typ parametru Popis
instanceId Adresa URL ID instance orchestrace.
reason Řetězec dotazu Nepovinné. Důvod ukončení instance orchestrace.

Response

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 se dokončila 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.

Požádat

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 Popis
instanceId Adresa URL ID instance orchestrace.
reason Řetězec dotazu Nepovinné. Důvod pozastavení instance orchestrace.

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í.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance se dokončila, selhala nebo ukončila.

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

Obnovení instance

Obnoví pozastavenou instanci orchestrace.

Požádat

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 Popis
instanceId Adresa URL ID instance orchestrace.
reason Řetězec dotazu Nepovinné. Důvod obnovení instance orchestrace

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í.
  • HTTP 404 (Nenalezena):: Zadaná instance nebyla nalezena.
  • HTTP 410 (Pryč):: Zadaná instance se dokončila, selhala nebo ukončila.

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

Převinutí instance zpět (Preview)

Obnoví instanci orchestrace, která selhala, do spuštěného stavu tak, že přehraje nejnovější neúspěšné operace.

Požádat

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost je zobrazeno více řádků):

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

Ve verzi 2.x modulu runtime Functions má formát adresy URL všechny stejné parametry, ale s mírně odlišnou předponou:

POST /runtime/webhooks/durabletask/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 také následující jedinečný parametr.

Pole Typ parametru Popis
instanceId Adresa URL ID instance orchestrace.
reason Řetězec dotazu Nepovinné. Důvod pro převinutí instance orchestrace zpět.

Response

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.

Entita signal

Odešle jednosměrnou zprávu operace do Durable Entity. Pokud entita neexistuje, vytvoří se automaticky.

Poznámka:

Odolné entity jsou dostupné od Durable Functions 2.0.

Požádat

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 také následující jedinečné parametry:

Pole Typ parametru Popis
entityName Adresa URL Název (typ) entity.
entityKey Adresa URL Klíč (jedinečné ID) entity.
op Řetězec dotazu Nepovinné. 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ří se tímto požadavkem:

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 třídách v .NET určíte op hodnotu delete , že se odstraní stav entity. Pokud entita definuje operaci s názvem delete, bude však vyvolána operace definovaná uživatelem.

Response

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 obsahovat informace o chybách ve formátu JSON v obsahu odpovědi.

Získání entity

Získá stav zadané entity.

Požádat

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}

Response

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

Následující příklad požadavku HTTP získá stav 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
}

Entity seznamu

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

Požádat

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 také následující jedinečné parametry:

Pole Typ parametru Popis
entityName Adresa URL Nepovinné. 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, bude stav entity zahrnut do 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.

Response

Ú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ů. Tento název hlavičky požadavku je také x-ms-continuation-token.

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

Následující příklad požadavku HTTP obsahuje seznam všech entit v centru úloh:

GET /runtime/webhooks/durabletask/entities

JSON odpovědi může vypadat 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

Následující příklad požadavku HTTP uvádí pouze první dvě entity typu counter a také načte jejich stav:

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

JSON odpovědi může vypadat 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 }
    }
]

Další kroky

Naučte se používat application Přehledy k monitorování trvalých funkcí.