Delen via

HTTP API naslaginformatie

De Durable Functions-extensie bevat een set ingebouwde HTTP-API's die kunnen worden gebruikt om beheertaken uit te voeren op indelingen, entiteiten en taakhubs. Deze HTTP-API's zijn uitbreidbare webhooks die zijn geautoriseerd door de Azure Functions-host, maar rechtstreeks worden verwerkt door de Durable Functions-extensie.

De basis-URL voor de API's die in dit artikel worden genoemd, is hetzelfde als de basis-URL voor uw functie-app. Wanneer u lokaal ontwikkelt met behulp van de Azure Functions Core Tools, is de basis-URL doorgaans http://localhost:7071. In de gehoste Azure Functions-service is de basis-URL doorgaans https://{appName}.azurewebsites.net. Aangepaste hostnamen worden ook ondersteund als deze zijn geconfigureerd in uw App Service-app.

Voor alle HTTP-API's die door de extensie zijn geïmplementeerd, zijn de volgende parameters vereist. Het gegevenstype van alle parameters is string.

Kenmerk Parametertype Description
taskHub Querystring De naam van de taakhub. Als dit niet is opgegeven, wordt ervan uitgegaan dat de naam van de taakhub van de huidige functie-app wordt gebruikt.
connection Querystring De naam van de instelling van de verbindings-app voor de back-endopslagprovider. Als dit niet is opgegeven, wordt ervan uitgegaan dat de standaardverbindingsconfiguratie voor de functie-app wordt gebruikt.
systemKey Querystring De autorisatiesleutel die is vereist om de API aan te roepen.

systemKey is een autorisatiesleutel die automatisch wordt gegenereerd door de Azure Functions-host. Het verleent specifiek toegang tot de Durable Task-extensie-API's en kan op dezelfde manier worden beheerd als andere Azure Functions-toegangssleutels. U kunt URL's genereren die de juiste taskHub en systemKey querystringwaarden bevatten met behulp van orchestration client binding-API's, zoals de CreateCheckStatusResponse en CreateHttpManagementPayload API's in .NET, de createCheckStatusResponse en createHttpManagementPayload API's in JavaScript, enzovoort.

In de volgende secties worden de specifieke HTTP-API's beschreven die worden ondersteund door de extensie en geven voorbeelden van hoe ze kunnen worden gebruikt.

Orchestratie starten

Hiermee wordt een nieuw exemplaar van de opgegeven orchestratorfunctie uitgevoerd.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
functionName URL De naam van de orchestratorfunctie die moet worden gestart.
instanceId URL Optionele parameter. De ID van de orchestratie-instantie. Als dit niet is opgegeven, begint de orchestrator-functie met een willekeurige instantie-id.
{content} Inhoud aanvragen Optioneel. De invoer van de als JSON geformatteerde orchestratorfunctie.

Reactie

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de opgegeven orchestratorfunctie is gepland om te worden uitgevoerd. De Location antwoordheader bevat een URL voor het opvragen van de orkestratiestatus.
  • HTTP 400 (Ongeldige aanvraag): De opgegeven orchestratiefunctie bestaat niet, de opgegeven exemplaar-ID is ongeldig of de aanvraaginhoud is ongeldige JSON.

Hier volgt een voorbeeld van een aanvraag waarmee een RestartVMs orchestratorfunctie wordt gestart en de nettolading van JSON-objecten wordt opgenomen:

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

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

De nettolading van het antwoord voor de HTTP 202-gevallen is een JSON-object met de volgende velden:

Veld Description
id De ID van de orchestratie-instantie.
statusQueryGetUri De status URL van de orkestratie-instantie.
sendEventPostUri De URL voor het activeren van een gebeurtenis van het orchestratie-exemplaar.
terminatePostUri De 'terminate' URL van de orkestratie-instantie.
purgeHistoryDeleteUri De URL voor 'geschiedenis opschonen' van de orkestratie-instantie.
rewindPostUri (preview) De URL voor 'terugspoelen' van het orchestration-exemplaar.
suspendPostUri De URL om het orchestration-exemplaar te pauzeren.
resumePostUri De URL 'hervat' van de orkestratie-instantie.

Het gegevenstype van alle velden is string.

Hier volgt een voorbeeld van een antwoordbelasting voor een orkestratie-instantie met abc123 als ID (opgemaakt voor leesbaarheid):

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

Het HTTP-antwoord is bedoeld om compatibel te zijn met het Polling Consumer-patroon. Het bevat ook de volgende opvallende antwoordheaders:

  • Locatie: de URL van het statuseindpunt. Deze URL bevat dezelfde waarde als het statusQueryGetUri veld.
  • Retry-After: Het aantal seconden dat moet worden gewacht tussen pollingbewerkingen. De standaardwaarde is 10.

Zie de documentatie voor het bijhouden van asynchrone HTTP-bewerkingen voor meer informatie over het asynchrone HTTP-pollingpatroon.

Exemplaarstatus ophalen

Hiermee krijgt u de status van een opgegeven orchestratie-instantie.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
showInput Querystring Optionele parameter. Als deze optie is ingesteld op false, wordt de functie-invoer niet opgenomen in de payload van het antwoord.
showHistory Querystring Optionele parameter. Als ingesteld op true, wordt de uitvoeringsgeschiedenis van de orkestratie opgenomen in de antwoordpayload.
showHistoryOutput Querystring Optionele parameter. Als deze optie is ingesteld op true, worden de functie-uitvoer opgenomen in de orchestration-uitvoeringsgeschiedenis.
createdTimeFrom Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of vóór de opgegeven ISO8601 tijdstempel.
runtimeStatus Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren op basis van hun runtimestatus. Zie het artikel Querying-instanties voor de lijst met mogelijke statuswaarden tijdens runtime.
returnInternalServerErrorOnFailure Querystring Optionele parameter. Indien ingesteld op true, retourneert deze API een HTTP 500-antwoord in plaats van een 200 als het exemplaar een foutstatus heeft. Deze parameter is bedoeld voor scenario’s van geautomatiseerde statuspolling.

Reactie

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 200 (OK):het opgegeven exemplaar heeft de status Voltooid of Mislukt.
  • HTTP 202 (geaccepteerd): het opgegeven exemplaar wordt uitgevoerd.
  • HTTP 400 (ongeldige aanvraag):het opgegeven exemplaar is mislukt of is beëindigd.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar bestaat niet of is niet gestart.
  • HTTP 500 (interne serverfout): alleen geretourneerd wanneer de server is ingesteld op true en het opgegeven exemplaar is mislukt door een niet-afgehandelde uitzondering.

De nettolading van het antwoord voor de HTTP 200- en HTTP 202-gevallen is een JSON-object met de volgende velden:

Veld Gegevenstype Description
runtimeStatus touw De runtime-status van de instantie. Waarden zijn In uitvoering, In afwachting, Mislukt, Geannuleerd, Beëindigd, Voltooid, Onderbroken.
input JSON De JSON-gegevens die worden gebruikt om het exemplaar te initialiseren. Dit veld is null als de showInput querytekenreeksparameter is ingesteld op false.
customStatus JSON De JSON-gegevens voor de aangepaste orkestratiestatus. Dit veld is null indien niet ingesteld.
output JSON De JSON-uitvoer van het exemplaar. Dit veld is null als het exemplaar niet de status Voltooid heeft.
createdTime touw Het tijdstip waarop het exemplaar is gemaakt. Maakt gebruik van een uitgebreide ISO 8601-notatie.
lastUpdatedTime touw Het tijdstip waarop het exemplaar het laatst is bewaard. Maakt gebruik van een uitgebreide ISO 8601-notatie.
historyEvents JSON Een JSON-array met de uitvoeringsgeschiedenis van de orkestratie. Dit veld is null tenzij de showHistory querytekenreeksparameter is ingesteld op true.

Hier is een voorbeeld van een reactie-payload inclusief de uitvoeringsgeschiedenis van de orkestratie en de uitvoer van activiteiten (opgemaakt voor leesbaarheid).

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

Het HTTP 202-antwoord bevat ook een locatieantwoordheader die verwijst naar dezelfde URL als het statusQueryGetUri eerder genoemde veld.

Status van alle instanties ophalen

U kunt ook de status van alle exemplaren opvragen door de instanceId uit de aanvraag 'Exemplaarstatus ophalen' te verwijderen. In dit geval zijn de basisparameters hetzelfde als bij 'Status van exemplaar ophalen'. Queryreeksparameters voor filteren worden ook ondersteund.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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}

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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}

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
showInput Querystring Optionele parameter. Als deze optie is ingesteld false, wordt de invoer voor de functie niet opgenomen in de payload van het antwoord.
showHistoryOutput Querystring Optionele parameter. Als deze optie is ingesteld op true, wordt de uitvoer van functies opgenomen in de uitvoeringsgeschiedenis van de orchestratie.
createdTimeFrom Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of vóór de opgegeven ISO8601 tijdstempel.
runtimeStatus Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren op basis van hun runtimestatus. Zie het artikel Querying-exemplaren voor de lijst met mogelijke runtimestatuswaarden.
instanceIdPrefix Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren zodat alleen exemplaren worden opgenomen waarvan de exemplaar-id begint met de opgegeven voorvoegseltekenreeks. Beschikbaar vanaf versie 2.7.2 van de extensie.
top Querystring Optionele parameter. Wanneer dit is opgegeven, beperkt u het aantal exemplaren dat door de query wordt geretourneerd.

Reactie

Hier volgt een voorbeeld van antwoordladingen, inclusief de orkestratiestatus (opgemaakt voor leesbaarheid):

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

Opmerking

Deze bewerking kan erg duur zijn in termen van Azure Storage I/O als u de standaard Azure Storage-provider gebruikt en als er veel rijen in de tabel Exemplaren staan. Meer details over de Instance-tabel staan in de documentatie van de Azure Storage-provider.

Als er meer resultaten bestaan, wordt een vervolgtoken geretourneerd in de antwoordheader. De naam van de header is x-ms-continuation-token.

Waarschuwing

Het queryresultaat retourneert mogelijk minder items dan de limiet die is opgegeven door top. Bij het ontvangen van resultaten moet u daarom altijd controleren of er een vervolgtoken is.

Als u de waarde van het vervolgtoken instelt in de volgende verzoekheader, kunt u de volgende pagina met de resultaten ophalen. Deze naam van de aanvraagheader is ook x-ms-continuation-token.

Geschiedenis van één exemplaar opschonen

Hiermee verwijdert u de geschiedenis en bijbehorende artefacten van een opgegeven orchestration-exemplaar.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.

Reactie

De volgende HTTP-statuscodewaarden kunnen worden geretourneerd.

  • HTTP 200 (OK): de exemplaargeschiedenis is succesvol opgeschoond.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar bestaat niet.

De nettolading van het antwoord voor de HTTP 200-aanvraag is een JSON-object met het volgende veld:

Veld Gegevenstype Description
instancesDeleted integer Het aantal exemplaren dat is verwijderd. Voor het geval van één exemplaar moet deze waarde altijd zijn 1.

Dit is een voorbeeld van een responselading (opgemaakt voor leesbaarheid):

{
    "instancesDeleted": 1
}

Meerdere instantiegeschiedenissen opschonen

U kunt ook de geschiedenis en gerelateerde artefacten voor meerdere exemplaren in een taakhub verwijderen door {instanceId} te verwijderen uit de aanvraag voor 'Opschonen van één exemplaargeschiedenis'. Als u de exemplaargeschiedenis selectief wilt opschonen, gebruikt u dezelfde filters die worden beschreven in de aanvraag Alle exemplarenstatus ophalen.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
createdTimeFrom Querystring Hiermee filtert u de lijst met opgeschoonde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met opgeschoonde exemplaren die zijn gemaakt op of vóór de opgegeven ISO8601 tijdstempel.
runtimeStatus Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met opgeschoonde exemplaren op basis van hun runtimestatus. Zie voor de lijst met mogelijke runtimestatuswaarden het artikel Querying-instanties.

Opmerking

Deze bewerking kan erg duur zijn in termen van Azure Storage I/O als u de standaard Azure Storage-provider gebruikt en als er veel rijen in de tabellen Exemplaren en/of Geschiedenis staan. Meer informatie over deze tabellen vindt u in de documentatie over Prestaties en schalen in Durable Functions (Azure Functions ).

Reactie

De volgende HTTP-statuscodewaarden kunnen worden geretourneerd.

  • HTTP 200 (OK): De instancegeschiedenis is met succes verwijderd.
  • HTTP 404 (niet gevonden): er zijn geen exemplaren gevonden die overeenkomen met de filterexpressie.

De nettolading van het antwoord voor de HTTP 200-aanvraag is een JSON-object met het volgende veld:

Veld Gegevenstype Description
instancesDeleted integer Het aantal exemplaren dat is verwijderd.

Hier is een voorbeeld van een antwoordpayload (voor de leesbaarheid opgemaakt):

{
    "instancesDeleted": 250
}

Gebeurtenis activeren

Een bericht van een gebeurtenismelding wordt naar een actieve orchestratie-instantie verzonden.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
eventName URL De naam van de gebeurtenis waarop de doelorkestratie-instantie wacht.
{content} Inhoud aanvragen De eventlading in JSON-indeling.

Reactie

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de gegenereerde gebeurtenis is geaccepteerd voor verwerking.
  • HTTP 400 (ongeldige aanvraag): de aanvraaginhoud is niet van het type application/json of ongeldige JSON.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar is niet gevonden.
  • HTTP 410 (verdwenen): het opgegeven exemplaar is voltooid of mislukt en kan geen gegenereerde gebeurtenissen verwerken.

Hier volgt een voorbeeldaanvraag waarmee de JSON-tekenreeks "incr" wordt verzonden naar een exemplaar dat wacht op een gebeurtenis met de naam van een bewerking:

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

"incr"

De antwoorden voor deze API bevatten geen inhoud.

Instantie beëindigen

Hiermee wordt een actieve orkestratie-instantie beëindigd.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameter.

Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
reason Querystring Optioneel. De reden voor het beëindigen van het orkestratie-exemplaar.

Reactie

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de beëindigingsaanvraag is geaccepteerd voor verwerking.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar is niet gevonden.
  • HTTP 410 (verdwenen): het opgegeven exemplaar is voltooid of mislukt.

Hier volgt een voorbeeldaanvraag waarmee een actieve instantie wordt beëindigd en een reden van buggy wordt opgegeven:

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

De antwoorden voor deze API bevatten geen inhoud.

Instantie opschorten

Deactiveert een actieve orkestratie-instantie.

Aanvraag

In versie 2.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
reason Querystring Optioneel. De reden voor het onderbreken van de orkestratie-instance.

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de aanvraag voor onderbreken is geaccepteerd voor verwerking.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar is niet gevonden.
  • HTTP 410 (verdwenen): het opgegeven exemplaar is voltooid, mislukt of beëindigd.

De antwoorden voor deze API bevatten geen inhoud.

Instantie hervatten

Hiermee wordt een gepauzeerde orkestratie-instantie hervat.

Aanvraag

In versie 2.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
reason Querystring Optioneel. De reden voor het hervatten van de orkestratie-instantie.

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de cv-aanvraag is geaccepteerd voor verwerking.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar is niet gevonden.
  • HTTP 410 (verdwenen): het opgegeven exemplaar is voltooid, mislukt of beëindigd.

De antwoorden voor deze API bevatten geen inhoud.

Exemplaar terugspoelen (preview)

Herstelt een mislukte orkestratie-instantie in een werkende toestand door de meest recente mislukte operaties te herhalen.

Aanvraag

Voor versie 1.x van de Functions-runtime wordt de aanvraag als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

In versie 2.x van de Functions-runtime heeft de URL-indeling dezelfde parameters, maar met een iets ander voorvoegsel:

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameter.

Veld Parametertype Description
instanceId URL De ID van de orchestratie-instantie.
reason Querystring Optioneel. De reden voor het terugspoelen van het orkestratie-exemplaar.

Reactie

Er kunnen verschillende mogelijke statuscodewaarden worden geretourneerd.

  • HTTP 202 (geaccepteerd): de aanvraag voor terugspoelen is geaccepteerd voor verwerking.
  • HTTP 404 (niet gevonden): het opgegeven exemplaar is niet gevonden.
  • HTTP 410 (verdwenen): het opgegeven exemplaar is voltooid of is beëindigd.

Hier volgt een voorbeeld van een aanvraag waarmee een mislukt exemplaar wordt teruggespoeld en een reden van vast wordt opgegeven.

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

De antwoorden voor deze API bevatten geen inhoud.

Signaalentiteit

Hiermee wordt een éénrichtingsbewerkingsbericht verzonden naar een Durable Entity. Als de entiteit niet bestaat, wordt deze automatisch gemaakt.

Opmerking

Duurzame entiteiten zijn beschikbaar vanaf Durable Functions 2.0.

Aanvraag

De HTTP-aanvraag is als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
entityName URL De naam (het type) van de entiteit.
entityKey URL De sleutel (unieke id) van de entiteit.
op Querystring Optioneel. De naam van de door de gebruiker gedefinieerde bewerking die moet worden aangeroepen.
{content} Inhoud aanvragen De eventlading in JSON-indeling.

Hier volgt een voorbeeldaanvraag waarmee een door de gebruiker gedefinieerd bericht 'Toevoegen' wordt verzonden naar een entiteit met de Counter naam steps. De inhoud van het bericht is de waarde 5. Als de entiteit nog niet bestaat, wordt deze gemaakt door deze aanvraag:

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

5

Opmerking

Standaard wordt bij op klassen gebaseerde entiteiten in .NET, het specificeren van de op waarde van delete gebruikt voor het verwijderen van de status van een entiteit. Als de entiteit echter een bewerking definieert met de naam delete, wordt die door de gebruiker gedefinieerde bewerking in plaats daarvan aangeroepen.

Reactie

Deze bewerking heeft verschillende mogelijke antwoorden:

  • HTTP 202 (geaccepteerd): de signaalbewerking is geaccepteerd voor asynchrone verwerking.
  • HTTP 400 (ongeldige aanvraag): de aanvraaginhoud is niet van het type application/json, is ongeldige JSON of heeft een ongeldige entityKey waarde.
  • HTTP 404 (niet gevonden): de opgegeven entityName is niet gevonden.

Een geslaagde HTTP-aanvraag bevat geen inhoud in het antwoord. Een mislukte HTTP-aanvraag kan foutinformatie in JSON-indeling bevatten in de antwoordinhoud.

Entiteit ophalen

Hiermee haalt u de status van de opgegeven entiteit op.

Aanvraag

De HTTP-aanvraag is als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

Reactie

Deze bewerking heeft twee mogelijke antwoorden:

  • HTTP 200 (OK):de opgegeven entiteit bestaat.
  • HTTP 404 (niet gevonden): de opgegeven entiteit is niet gevonden.

Een geslaagd antwoord bevat de geserialiseerde JSON-status van de entiteit als inhoud.

Example

Het volgende voorbeeld van een HTTP-aanvraag haalt de status op van een bestaande Counter entiteit met de naam steps.

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

Als de Counter entiteit gewoon een aantal stappen bevat die zijn opgeslagen in een currentValue veld, kan de antwoordinhoud er als volgt uitzien (opgemaakt voor leesbaarheid):

{
    "currentValue": 5
}

Entiteiten weergeven

U kunt een query uitvoeren op meerdere entiteiten op basis van de naam van de entiteit of op de datum van de laatste bewerking.

Aanvraag

De HTTP-aanvraag is als volgt opgemaakt (er worden meerdere regels weergegeven voor duidelijkheid):

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

Aanvraagparameters voor deze API bevatten de eerder genoemde standaardset en de volgende unieke parameters:

Veld Parametertype Description
entityName URL Optioneel. Indien opgegeven, wordt de lijst van geretourneerde entiteiten gefilterd op hun entiteitsnaam (niet-hoofdlettergevoelig).
fetchState Querystring Optionele parameter. Indien ingesteld op true, wordt de entity status opgenomen in de payload van het antwoord.
lastOperationTimeFrom Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde entiteiten die bewerkingen hebben verwerkt na de gegeven ISO8601 tijdstempel.
lastOperationTimeTo Querystring Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde entiteiten die bewerkingen hebben verwerkt vóór de opgegeven ISO8601 tijdstempel.
top Querystring Optionele parameter. Wanneer dit is opgegeven, beperkt u het aantal entiteiten dat door de query wordt geretourneerd.

Reactie

Een geslaagd HTTP 200-antwoord bevat een door JSON geserialiseerde matrix met entiteiten en optioneel de status van elke entiteit.

De bewerking retourneert standaard de eerste 100 entiteiten die voldoen aan de querycriteria. De aanroeper kan een queryreeksparameterwaarde opgeven om top een ander maximum aantal resultaten te retourneren. Als er meer resultaten bestaan dan wat wordt geretourneerd, wordt er ook een vervolgtoken geretourneerd in de antwoordheader. De naam van de header is x-ms-continuation-token.

Als u de waarde van het vervolgtoken instelt in de volgende verzoekheader, kunt u de volgende pagina met de resultaten ophalen. Deze naam van de aanvraagheader is ook x-ms-continuation-token.

Voorbeeld: alle entiteiten weergeven

In het volgende voorbeeld van een HTTP-aanvraag worden alle entiteiten in de taakhub weergegeven:

GET /runtime/webhooks/durabletask/entities

De antwoord-JSON kan er als volgt uitzien (opgemaakt voor leesbaarheid):

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

Voorbeeld: de lijst met entiteiten filteren

In het volgende voorbeeld van een HTTP-aanvraag worden alleen de eerste twee entiteiten van het type counter weergegeven en wordt ook de status opgehaald:

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

De antwoord-JSON kan er als volgt uitzien (opgemaakt voor leesbaarheid):

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

Volgende stappen

Meer informatie over het gebruik van Application Insights om uw duurzame functies te bewaken

  • Last updated on