Referenční informace k rozhraní HTTP API

  • Článek
  • 16 min ke čtení

Rozšíření Durable Functions zveřejňuje sadu integrovaných rozhraní HTTP API, která se dají použít k provádění úloh správy na 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 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.

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 generovat adresy URL obsahující správné taskHubconnectionhodnoty řetězce a systemKey řetězce dotazů pomocí rozhraní API pro orchestraci klientských vazeb, jako jsou rozhraní CreateCheckStatusResponse 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 konkrétní rozhraní HTTP API podporovaná rozšířením a uveďte příklady toho, jak je lze použít.

Zahájení orchestrace

Spustí novou instanci zadané funkce orchestratoru.

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 URL Název funkce orchestrátoru, který se má spustit.
instanceId 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ý parametr. Vstup funkce orchestrátoru ve formátu JSON.

Odpověď

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

  • HTTP 202 (přijato):: Zadaná funkce orchestrátoru byla naplánována na spuštění. 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 Description
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 "historie vymazání" instance orchestrace.
rewindPostUri (Preview) Adresa URL "rewind" instance orchestrace.

Datový typ všech polí je string.

Tady je příklad datové části odpovědi pro instanci orchestrace s abc123 JEHO ID (formátováno 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"
}

Odpověď HTTP je určená tak, aby byla kompatibilní se vzorem příjemce dotazování. Obsahuje také následující užitečné hlavičky odpovědi:

  • Umístění: Adresa URL koncového bodu stavu. Tato adresa URL obsahuje stejnou hodnotu jako statusQueryGetUri pole.
  • Opakování: 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.

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 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 nastavená hodnota true, historie provádění orchestrace bude zahrnuta do datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota 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 časovém razítku ISO8601 nebo po nich.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném časovém razítku ISO8601 nebo před tím.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí na základě stavu běhu. Seznam možných hodnot stavu modulu runtime najdete v článku o dotazování instancí .
returnInternalServerErrorOnFailure Řetězec dotazu Volitelný parametr. Pokud je nastavená hodnota true, toto rozhraní API vrátí odpověď HTTP 500 místo 200, pokud je instance ve stavu selhání. Tento parametr je určený pro scénáře automatického dotazování na stav.

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 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 Description
runtimeStatus řetězec Stav modulu runtime instance. Mezi hodnoty patří Spuštěno, Čekající, Neúspěšné, Zrušeno, Ukončeno, Dokončeno.
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 false.
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 řetězec Čas vytvoření instance. Používá rozšířenou notaci ISO 8601.
lastUpdatedTime řetězec Č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 Načíst stav instance. V tomto případě jsou základní parametry stejné jako "Získat stav instance". Podporují se také parametry řetězce dotazu pro filtrování.

Žádost

Pro modul runtime Functions verze 1.x je požadavek formátován 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
instanceId URL ID instance orchestrace.
showInput Řetězec dotazu Volitelný parametr. Pokud je nastavená falsehodnota , vstup funkce nebude zahrnut do datové části odpovědi.
showHistory Řetězec dotazu Volitelný parametr. Pokud je nastavená truehodnota , historie provádění orchestrace bude zahrnuta do datové části odpovědi.
showHistoryOutput Řetězec dotazu Volitelný parametr. Pokud je nastavená truehodnota , výstupy funkce budou zahrnuty v historii 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 časovém razítku ISO8601 nebo po tomto časovém razítku ISO8601.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí vytvořených v daném časovém razítku ISO8601 nebo před daným časovým razítkem ISO8601.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených instancí na základě jejich stavu modulu runtime. Seznam možných hodnot stavu modulu runtime najdete v článku o dotazování instancí .
instanceIdPrefix Řetězec dotazu Volitelný parametr. Při 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. Při zadání omezí počet instancí vrácených dotazem.

Odpověď

Tady je příklad datových částí odpovědí, včetně stavu orchestrace (formátované 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 instance najdete v dokumentaci k výkonu a škálování v Durable Functions (Azure Functions).

Pokud existují další výsledky, vrátí se v hlavičce odpovědi 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.

Vymazání historie jedné instance

Odstraní historii a související artefakty pro zadanou instanci orchestrace.

Žádost

Pro modul runtime Functions verze 1.x je požadavek formátován 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 URL ID instance orchestrace.

Odpověď

Můžete 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ě jednoho případu 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í

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

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 Description
createdTimeFrom Řetězec dotazu Filtruje seznam vyprázdněných instancí vytvořených v daném časovém razítku ISO8601 nebo po nich.
createdTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vyprázdněných instancí, které byly vytvořeny v daném časovém razítku ISO8601 nebo před tímto časovým razítkem ISO8601.
runtimeStatus Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vyprázdněných instancí na základě stavu běhu. Seznam možných hodnot stavu modulu runtime najdete v článku o dotazování instancí .

Poznámka

Tato operace může být velmi nákladná 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 Historie 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).

Odpověď

Můžete 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.

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 URL ID instance orchestrace.
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ůžete vrátit několik možných hodnot stavových kódů.

  • HTTP 202 (přijato): Vyvoláná událost 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 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.

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 URL ID instance orchestrace.
reason Řetězec dotazu Nepovinný parametr. Důvod ukončení instance orchestrace.

Odpověď

Můžete 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.

Rewind instance (Preview)

Obnoví neúspěšnou instanci orchestrace do spuštěného stavu tak, že přehraje poslední neúspěšné operace.

Žádost

Pro modul runtime Functions verze 1.x se požadavek naformátuje následujícím způsobem (pro přehlednost se zobrazí 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 URL ID instance orchestrace.
reason Řetězec dotazu Nepovinný parametr. Důvod opětovného převinutí instance orchestrace.

Odpověď

Můžete 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 ukončena.

Tady je příklad požadavku, který převije neúspěšnou instanci 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 signálu

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.

Žádost

Požadavek HTTP je naformátován 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 URL Název (typ) entity.
entityKey URL Klíč (jedinečné ID) entity.
op Řetězec dotazu Nepovinný parametr. 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 entitě Counter 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í se u entit založených na třídách v .NET určuje op hodnota delete , která odstraní stav entity. Pokud entita definuje operaci s názvem delete, bude 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 obsahovat informace o chybách ve formátu JSON v obsahu odpovědi.

Získání entity

Získá stav zadané entity.

Žádost

Požadavek HTTP je naformátován 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 obsahu.

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 několik kroků uložených v currentValue poli, může obsah odpovědi vypadat takto (formátovaný pro čitelnost):

{
    "currentValue": 5
}

Vytvoření seznamu entit

Můžete se dotazovat na více entit podle názvu entity nebo podle data poslední operace.

Žádost

Požadavek HTTP je naformátován 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 URL Nepovinný parametr. Po zadání filtruje seznam vrácených entit podle názvu entity (nerozlišující 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 zadaném časovém razítku ISO8601.
lastOperationTimeTo Řetězec dotazu Volitelný parametr. Po zadání filtruje seznam vrácených entit, které zpracovávaly operace před daným časovým razítkem ISO8601.
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 json entit 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 pro top vrácení jiného maximálního počtu výsledků. Pokud více výsledků existuje nad rámec toho, co se vrátí, vrátí se v hlavičce odpovědi také token pokračování. Název záhlaví je x-ms-continuation-token.

Pokud nastavíte hodnotu tokenu pokračování v záhlaví 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 uvádí všechny entity v centru úloh:

GET /runtime/webhooks/durabletask/entities

Kód JSON odpovědi může vypadat takto (formátovaný 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

Kód JSON odpovědi může vypadat takto (formátovaný 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 Insights k monitorování trvalých funkcí.