HTTP API-referens

  • Artikel

Tillägget Durable Functions exponerar en uppsättning inbyggda HTTP-API:er som kan användas för att utföra hanteringsuppgifter på orkestreringar, entiteter och aktivitetshubbar. Dessa HTTP-API:er är utökningswebbhooks som är auktoriserade av Azure Functions-värden men hanteras direkt av Durable Functions-tillägget.

Bas-URL:en för de API:er som nämns i den här artikeln är samma som bas-URL:en för funktionsappen. När du utvecklar lokalt med Hjälp av Azure Functions Core Tools är bas-URL:en vanligtvis http://localhost:7071. I den azure functions-värdbaserade tjänsten är bas-URL:en vanligtvis https://{appName}.azurewebsites.net. Anpassade värdnamn stöds också om de konfigureras i App Service-appen.

Alla HTTP-API:er som implementeras av tillägget kräver följande parametrar. Datatypen för alla parametrar är string.

Parameter Parametertyp beskrivning
taskHub Frågesträng Namnet på aktivitetshubben. Om det inte anges antas den aktuella funktionsappens aktivitetshubbnamn.
connection Frågesträng Namnet på inställningen för anslutningsappen för serverdelslagringsprovidern. Om det inte anges antas standardanslutningskonfigurationen för funktionsappen.
systemKey Frågesträng Auktoriseringsnyckeln som krävs för att anropa API:et.

systemKey är en auktoriseringsnyckel som genereras automatiskt av Azure Functions-värden. Det ger specifikt åtkomst till API:erna för durable task-tillägget och kan hanteras på samma sätt som andra Azure Functions-åtkomstnycklar. Du kan generera URL:er som innehåller rätt taskHub, connectionoch systemKey frågesträngsvärden med hjälp av api:er för orkestreringsklientbindning, till exempel CreateCheckStatusResponse API:erna och CreateHttpManagementPayload i .NET, API:erna createCheckStatusResponse och createHttpManagementPayload i JavaScript osv.

De kommande avsnitten beskriver de specifika HTTP-API:er som stöds av tillägget och innehåller exempel på hur de kan användas.

Starta orkestrering

Börjar köra en ny instans av den angivna orchestrator-funktionen.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
functionName Webbadress Namnet på orkestreringsfunktionen som ska startas.
instanceId webbadress Valfri parameter. ID för orkestreringsinstansen. Om den inte anges börjar orkestreringsfunktionen med ett slumpmässigt instans-ID.
{content} Begära innehåll Valfritt. JSON-formaterad orchestrator-funktionsindata.

Response

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (accepterad): Den angivna orkestreringsfunktionen var schemalagd att börja köras. Svarshuvudet Location innehåller en URL för avsökning av orkestreringsstatusen.
  • HTTP 400 (felaktig begäran): Den angivna orchestrator-funktionen finns inte, det angivna instans-ID:t var inte giltigt eller så var begärandeinnehållet ogiltigt JSON.

Följande är en exempelbegäran som startar en RestartVMs orchestrator-funktion och innehåller JSON-objektnyttolast:

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

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

Svarsnyttolasten för HTTP 202-ärenden är ett JSON-objekt med följande fält:

Fält beskrivning
id ID för orkestreringsinstansen.
statusQueryGetUri Status-URL:en för orkestreringsinstansen.
sendEventPostUri URL:en för "raise event" för orkestreringsinstansen.
terminatePostUri Url:en "avsluta" för orkestreringsinstansen.
purgeHistoryDeleteUri URL:en för "rensningshistorik" för orkestreringsinstansen.
rewindPostUri (förhandsversion) Url:en "spola tillbaka" för orkestreringsinstansen.
suspendPostUri Url:en "pausa" för orkestreringsinstansen.
resumePostUri Url:en "återuppta" för orkestreringsinstansen.

Datatypen för alla fält är string.

Här är ett exempel på svarsnyttolast för en orkestreringsinstans med abc123 som sitt ID (formaterat för läsbarhet):

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

HTTP-svaret är avsett att vara kompatibelt med avsökningskonsumentmönstret. Den innehåller även följande viktiga svarshuvuden:

  • Plats: URL:en för statusslutpunkten. Den här URL:en innehåller samma värde som fältet statusQueryGetUri .
  • Försök igen: Antalet sekunder att vänta mellan avsökningsåtgärder. Standardvärdet är 10.

Mer information om det asynkrona HTTP-avsökningsmönstret finns i dokumentationen för HTTP-asynkron åtgärdsspårning .

Hämta instansstatus

Hämtar status för en angiven orkestreringsinstans.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
showInput Frågesträng Valfri parameter. Om värdet falseär inställt på inkluderas inte funktionsindata i svarsnyttolasten.
showHistory Frågesträng Valfri parameter. Om värdet är trueinställt på inkluderas orkestreringskörningshistoriken i svarsnyttolasten.
showHistoryOutput Frågesträng Valfri parameter. Om värdet är trueinställt på inkluderas funktionsutdata i orkestreringskörningshistoriken.
createdTimeFrom Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade instanser som skapades vid eller efter den angivna ISO8601 tidsstämpeln.
createdTimeTo Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade instanser som skapades vid eller före den angivna ISO8601 tidsstämpeln.
runtimeStatus Frågesträng Valfri parameter. När det anges filtrerar du listan över returnerade instanser baserat på deras körningsstatus. En lista över möjliga körningsstatusvärden finns i artikeln Fråga instanser .
returnInternalServerErrorOnFailure Frågesträng Valfri parameter. Om värdet är trueinställt på returnerar det här API:et ett HTTP 500-svar i stället för 200 om instansen är i ett feltillstånd. Den här parametern är avsedd för scenarier för automatisk statusavsökning.

Response

Flera möjliga statuskodvärden kan returneras.

  • HTTP 200 (OK): Den angivna instansen är i ett slutfört eller misslyckat tillstånd.
  • HTTP 202 (accepterad): Den angivna instansen pågår.
  • HTTP 400 (felaktig begäran): Den angivna instansen misslyckades eller avslutades.
  • HTTP 404 (hittades inte): Den angivna instansen finns inte eller har inte börjat köras.
  • HTTP 500 (internt serverfel): Returneras endast när returnInternalServerErrorOnFailure är inställt på true och den angivna instansen misslyckades med ett ohanterat undantag.

Svarsnyttolasten för HTTP 200 - och HTTP 202-fallen är ett JSON-objekt med följande fält:

Fält Datatyp beskrivning
runtimeStatus sträng Körningsstatus för instansen. Värden inkluderar körning, väntar, misslyckades, avbröts, avslutades, slutfördes, pausades.
input JSON JSON-data som används för att initiera instansen. Det här fältet är null om frågesträngsparametern showInput är inställd på false.
customStatus JSON JSON-data som används för anpassad orkestreringsstatus. Det här fältet är null om det inte har angetts.
output JSON JSON-utdata för instansen. Det här fältet är null om instansen inte är i ett slutfört tillstånd.
createdTime sträng Tidpunkten då instansen skapades. Använder iso 8601 utökad notation.
lastUpdatedTime sträng Tiden då instansen senast sparades. Använder iso 8601 utökad notation.
historyEvents JSON En JSON-matris som innehåller orkestreringskörningshistoriken. Det här fältet är null om inte showHistory frågesträngsparametern är inställd på true.

Här är ett exempel på svarsnyttolast, inklusive orkestreringskörningshistoriken och aktivitetsutdata (formaterade för läsbarhet):

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

HTTP 202-svaret innehåller också en platssvarsrubrik som refererar till samma URL som det statusQueryGetUri fält som nämndes tidigare.

Hämta alla instansstatusar

Du kan också fråga efter status för alla instanser genom att ta bort instanceId från begäran "Hämta instansstatus". I det här fallet är de grundläggande parametrarna samma som "Hämta instansstatus". Frågesträngsparametrar för filtrering stöds också.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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}

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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}

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
showInput Frågesträng Valfri parameter. Om värdet falseär inställt på inkluderas inte funktionsindata i svarsnyttolasten.
showHistoryOutput Frågesträng Valfri parameter. Om värdet är trueinställt på inkluderas funktionsutdata i orkestreringskörningshistoriken.
createdTimeFrom Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade instanser som skapades vid eller efter den angivna ISO8601 tidsstämpeln.
createdTimeTo Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade instanser som skapades vid eller före den angivna ISO8601 tidsstämpeln.
runtimeStatus Frågesträng Valfri parameter. När det anges filtrerar du listan över returnerade instanser baserat på deras körningsstatus. En lista över möjliga körningsstatusvärden finns i artikeln Fråga instanser .
instanceIdPrefix Frågesträng Valfri parameter. När det anges filtreras listan över returnerade instanser så att den endast innehåller instanser vars instans-ID börjar med den angivna prefixsträngen. Tillgänglig från och med version 2.7.2 av tillägget.
top Frågesträng Valfri parameter. När det anges begränsar du antalet instanser som returneras av frågan.

Response

Här är ett exempel på svarsnyttolaster, inklusive orkestreringsstatusen (formaterad för läsbarhet):

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

Kommentar

Den här åtgärden kan vara mycket dyr när det gäller Azure Storage I/O om du använder azure storage-standardprovidern och om det finns många rader i tabellen Instanser. Mer information om instanstabellen finns i dokumentationen för Azure Storage-providern .

Om det finns fler resultat returneras en fortsättningstoken i svarshuvudet. Namnet på rubriken är x-ms-continuation-token.

Varning

Frågeresultatet kan returnera färre objekt än den gräns som anges av top. När du får resultat bör du därför alltid kontrollera om det finns en fortsättningstoken.

Om du anger värdet för fortsättningstoken i nästa begärandehuvud kan du få nästa resultatsida. Det här namnet på begärandehuvudet är också x-ms-continuation-token.

Rensa enstaka instanshistorik

Tar bort historiken och relaterade artefakter för en angiven orkestreringsinstans.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.

Response

Följande HTTP-statuskodvärden kan returneras.

  • HTTP 200 (OK): Instanshistoriken har rensats.
  • HTTP 404 (hittades inte): Den angivna instansen finns inte.

Svarsnyttolasten för HTTP 200-fallet är ett JSON-objekt med följande fält:

Fält Datatyp beskrivning
instancesDeleted integer Antalet borttagna instanser. För det enskilda instansfallet ska det här värdet alltid vara 1.

Här är ett exempel på svarsnyttolast (formaterad för läsbarhet):

{
    "instancesDeleted": 1
}

Rensa flera instanshistoriker

Du kan också ta bort historiken och relaterade artefakter för flera instanser i en aktivitetshubb genom att ta bort {instanceId} från begäran "Rensa enskild instanshistorik". Om du vill rensa instanshistoriken selektivt använder du samma filter som beskrivs i begäran "Hämta alla instanser status".

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
createdTimeFrom Frågesträng Filtrerar listan över rensade instanser som skapades vid eller efter den angivna ISO8601 tidsstämpeln.
createdTimeTo Frågesträng Valfri parameter. När du anger det filtrerar du listan över rensade instanser som skapades vid eller före den angivna ISO8601 tidsstämpeln.
runtimeStatus Frågesträng Valfri parameter. När du anger det filtrerar du listan över rensade instanser baserat på deras körningsstatus. En lista över möjliga körningsstatusvärden finns i artikeln Fråga instanser .

Kommentar

Den här åtgärden kan vara mycket dyr när det gäller Azure Storage I/O om du använder azure storage-standardprovidern och om det finns många rader i tabellerna Instanser och/eller historik. Mer information om dessa tabeller finns i dokumentationen Prestanda och skalning i Durable Functions (Azure Functions).

Response

Följande HTTP-statuskodvärden kan returneras.

  • HTTP 200 (OK): Instanshistoriken har rensats.
  • HTTP 404 (hittades inte): Inga instanser hittades som matchar filteruttrycket.

Svarsnyttolasten för HTTP 200-fallet är ett JSON-objekt med följande fält:

Fält Datatyp beskrivning
instancesDeleted integer Antalet borttagna instanser.

Här är ett exempel på svarsnyttolast (formaterad för läsbarhet):

{
    "instancesDeleted": 250
}

Skapa händelse

Skickar ett händelsemeddelande till en orkestreringsinstans som körs.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
eventName webbadress Namnet på den händelse som målorkestreringsinstansen väntar på.
{content} Begära innehåll Den JSON-formaterade händelsenyttolasten.

Response

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (accepterad): Den upphöjda händelsen accepterades för bearbetning.
  • HTTP 400 (felaktig begäran): Begärandeinnehållet var inte av typen application/json eller var inte giltigt JSON.
  • HTTP 404 (hittades inte): Den angivna instansen hittades inte.
  • HTTP 410 (Borta): Den angivna instansen har slutförts eller misslyckats och kan inte bearbeta några upphöjda händelser.

Här är en exempelbegäran som skickar JSON-strängen "incr" till en instans som väntar på en händelse med namnet operation:

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

"incr"

Svaren för det här API:et innehåller inget innehåll.

Avsluta instans

Avslutar en orkestreringsinstans som körs.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parameter.

Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
reason Frågesträng Valfritt. Orsaken till att orkestreringsinstansen avslutas.

Response

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (godkänd): Begäran om att avsluta godkändes för bearbetning.
  • HTTP 404 (hittades inte): Den angivna instansen hittades inte.
  • HTTP 410 (Borta): Den angivna instansen har slutförts eller misslyckats.

Här är en exempelbegäran som avslutar en instans som körs och anger orsaken till buggy:

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

Svaren för det här API:et innehåller inget innehåll.

Pausa instans

Pausar en orkestreringsinstans som körs.

Begär

I version 2.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
reason Frågesträng Valfritt. Orsaken till att orkestreringsinstansen pausas.

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (godkänd): Begäran om paus accepterades för bearbetning.
  • HTTP 404 (hittades inte): Den angivna instansen hittades inte.
  • HTTP 410 (Borta): Den angivna instansen har slutförts, misslyckats eller avslutats.

Svaren för det här API:et innehåller inget innehåll.

Återuppta instans

Återupptar en pausad orkestreringsinstans.

Begär

I version 2.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
reason Frågesträng Valfritt. Orsaken till att orkestreringsinstansen återupptas.

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (godkänd): Begäran om återupptagning accepterades för bearbetning.
  • HTTP 404 (hittades inte): Den angivna instansen hittades inte.
  • HTTP 410 (Borta): Den angivna instansen har slutförts, misslyckats eller avslutats.

Svaren för det här API:et innehåller inget innehåll.

Spola tillbaka instansen (förhandsversion)

Återställer en misslyckad orkestreringsinstans till ett körningstillstånd genom att spela upp de senaste misslyckade åtgärderna.

Begär

För version 1.x av Functions-körningen formateras begäran enligt följande (flera rader visas för tydlighetens skull):

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

I version 2.x av Functions-körningen har URL-formatet samma parametrar men med ett något annorlunda prefix:

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parameter.

Fält Parametertyp beskrivning
instanceId Webbadress ID för orkestreringsinstansen.
reason Frågesträng Valfritt. Orsaken till att orkestreringsinstansen spolas tillbaka.

Response

Flera möjliga statuskodvärden kan returneras.

  • HTTP 202 (accepterad): Begäran om bakåtspolning accepterades för bearbetning.
  • HTTP 404 (hittades inte): Den angivna instansen hittades inte.
  • HTTP 410 (Borta): Den angivna instansen har slutförts eller avslutats.

Här är en exempelbegäran som spolar tillbaka en misslyckad instans och anger orsaken till att den är fast:

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

Svaren för det här API:et innehåller inget innehåll.

Signalentitet

Skickar ett envägsåtgärdsmeddelande till en varaktig entitet. Om entiteten inte finns skapas den automatiskt.

Kommentar

Varaktiga entiteter är tillgängliga från och med Durable Functions 2.0.

Begär

HTTP-begäran formateras på följande sätt (flera rader visas för tydlighetens skull):

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
entityName Webbadress Entitetens namn (typ).
entityKey webbadress Nyckeln (unikt ID) för entiteten.
op Frågesträng Valfritt. Namnet på den användardefinierade åtgärd som ska anropas.
{content} Begära innehåll Den JSON-formaterade händelsenyttolasten.

Här är en exempelbegäran som skickar ett användardefinierat "Lägg till"-meddelande till en entitet Counter med namnet steps. Innehållet i meddelandet är värdet 5. Om entiteten inte redan finns skapas den av den här begäran:

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

5

Kommentar

Som standard med klassbaserade entiteter i .NET tas tillståndet för en entitet bort om du anger op värdet delete för. Om entiteten definierar en åtgärd med namnet deleteanropas dock den användardefinierade åtgärden i stället.

Response

Den här åtgärden har flera möjliga svar:

  • HTTP 202 (accepterad): Signalåtgärden accepterades för asynkron bearbetning.
  • HTTP 400 (felaktig begäran): Begärandeinnehållet var inte av typen application/json, var inte giltig JSON eller hade ett ogiltigt entityKey värde.
  • HTTP 404 (hittades inte): Det angivna entityName gick inte att hitta.

En lyckad HTTP-begäran innehåller inget innehåll i svaret. En misslyckad HTTP-begäran kan innehålla JSON-formaterad felinformation i svarsinnehållet.

Hämta entitet

Hämtar tillståndet för den angivna entiteten.

Begär

HTTP-begäran formateras på följande sätt (flera rader visas för tydlighetens skull):

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

Response

Den här åtgärden har två möjliga svar:

  • HTTP 200 (OK): Den angivna entiteten finns.
  • HTTP 404 (hittades inte): Den angivna entiteten hittades inte.

Ett lyckat svar innehåller det JSON-serialiserade tillståndet för entiteten som dess innehåll.

Exempel

I följande exempel hämtar HTTP-begäran tillståndet för en befintlig Counter entitet med namnet steps:

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

Om entiteten Counter helt enkelt innehåller ett antal steg som sparats i ett currentValue fält kan svarsinnehållet se ut som följande (formaterat för läsbarhet):

{
    "currentValue": 5
}

Listentiteter

Du kan fråga efter flera entiteter efter entitetsnamnet eller efter det senaste åtgärdsdatumet.

Begär

HTTP-begäran formateras på följande sätt (flera rader visas för tydlighetens skull):

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

Begärandeparametrar för det här API:et inkluderar standarduppsättningen som nämnts tidigare samt följande unika parametrar:

Fält Parametertyp beskrivning
entityName Webbadress Valfritt. När det anges filtreras listan över returnerade entiteter efter deras entitetsnamn (skiftlägesokänslig).
fetchState Frågesträng Valfri parameter. Om värdet anges till trueinkluderas entitetstillståndet i svarsnyttolasten.
lastOperationTimeFrom Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade entiteter som bearbetade åtgärder efter den angivna ISO8601 tidsstämpeln.
lastOperationTimeTo Frågesträng Valfri parameter. När du anger det filtrerar du listan över returnerade entiteter som bearbetade åtgärder före den angivna ISO8601 tidsstämpeln.
top Frågesträng Valfri parameter. När det anges begränsar du antalet entiteter som returneras av frågan.

Response

Ett lyckat HTTP 200-svar innehåller en JSON-serialiserad matris med entiteter och eventuellt tillståndet för varje entitet.

Som standard returnerar åtgärden de första 100 entiteterna som matchar frågevillkoren. Anroparen kan ange ett frågesträngsparametervärde för för top att returnera ett annat maximalt antal resultat. Om det finns fler resultat än vad som returneras returneras även en fortsättningstoken i svarshuvudet. Namnet på rubriken är x-ms-continuation-token.

Om du anger värdet för fortsättningstoken i nästa begärandehuvud kan du få nästa resultatsida. Det här namnet på begärandehuvudet är också x-ms-continuation-token.

Exempel – visa en lista över alla entiteter

I följande exempel på HTTP-begäran visas alla entiteter i aktivitetshubben:

GET /runtime/webhooks/durabletask/entities

JSON-svaret kan se ut så här (formaterat för läsbarhet):

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

Exempel – filtrera listan över entiteter

I följande exempel visar HTTP-begäran bara de två första entiteterna av typen counter och hämtar även deras tillstånd:

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

JSON-svaret kan se ut så här (formaterat för läsbarhet):

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

Nästa steg

Lär dig hur du använder Application Insights för att övervaka dina varaktiga funktioner