Delen via

HTTP-API-naslaginformatie

  • Artikel

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.

Parameter Parametertype Beschrijving
taskHub Queryreeks 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 Queryreeks 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 Queryreeks 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 taskHubwaarden voor tekenreeksen connectionbevatten en systemKey queryreekswaarden uitvoeren met behulp van clientbindings-API's voor orchestration, zoals de CreateCheckStatusResponse api's in CreateHttpManagementPayload .NET, de createCheckStatusResponse API's 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.

Indeling starten

Hiermee wordt een nieuw exemplaar van de opgegeven orchestratorfunctie uitgevoerd.

Aanvragen

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 Beschrijving
functionName URL De naam van de orchestratorfunctie die moet worden gestart.
instanceId URL Optionele parameter. De id van het indelingsexemplaar. Als dit niet is opgegeven, begint de orchestrator-functie met een willekeurige instantie-id.
{content} Inhoud aanvragen Optioneel. De invoer van de indeling JSON-orchestratorfunctie.

Respons

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 peilen van de indelingsstatus.
  • HTTP 400 (ongeldige aanvraag): de opgegeven orchestratorfunctie bestaat niet, de opgegeven exemplaar-id is ongeldig of 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": "111deb5d-09df-4604-992e-a968345530a9"
}

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

Veld Beschrijving
id De id van het indelingsexemplaar.
statusQueryGetUri De status-URL van het indelingsexemplaar.
sendEventPostUri De URL voor het genereren van gebeurtenissen van het orchestration-exemplaar.
terminatePostUri De URL 'beëindigen' van het orchestration-exemplaar.
purgeHistoryDeleteUri De URL 'geschiedenis opschonen' van het orchestration-exemplaar.
rewindPostUri (preview) De URL voor 'terugspoelen' van het orchestration-exemplaar.
suspendPostUri De URL 'onderbreken' van het orchestration-exemplaar.
resumePostUri De URL 'hervatten' van het indelingsexemplaar.

Het gegevenstype van alle velden is string.

Hier volgt een voorbeeld van een nettolading van een antwoord voor een indelingsexemplaar 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.
  • Opnieuw proberen na: 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 haalt u de status van een opgegeven indelingsinstantie op.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
showInput Queryreeks Optionele parameter. Als deze optie is ingesteld false, wordt de functie-invoer niet opgenomen in de nettolading van het antwoord.
showHistory Queryreeks Optionele parameter. Als deze optie is ingesteld true, wordt de uitvoeringsgeschiedenis van de indeling opgenomen in de nettolading van het antwoord.
showHistoryOutput Queryreeks Optionele parameter. Als deze optie is ingesteld true, worden de functie-uitvoer opgenomen in de uitvoeringsgeschiedenis van de orchestration.
createdTimeFrom Queryreeks Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Queryreeks 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 Queryreeks 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.
returnInternalServerErrorOnFailure Queryreeks 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 geautomatiseerde pollingscenario's voor statussen.

Respons

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 returnInternalServerErrorOnFailure server is ingesteld true op en het opgegeven exemplaar is mislukt met een niet-verwerkte uitzondering.

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

Veld Gegevenstype Beschrijving
runtimeStatus tekenreeks De runtimestatus van het exemplaar. Waarden zijn onder andere Actief, In behandeling, 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 die worden gebruikt voor de aangepaste indelingsstatus. Dit veld is null niet ingesteld.
output JSON De JSON-uitvoer van het exemplaar. Dit veld is null als het exemplaar niet de status Voltooid heeft.
createdTime tekenreeks Het tijdstip waarop het exemplaar is gemaakt. Maakt gebruik van een uitgebreide ISO 8601-notatie.
lastUpdatedTime tekenreeks Het tijdstip waarop het exemplaar het laatst is opgeslagen. Maakt gebruik van een uitgebreide ISO 8601-notatie.
historyEvents JSON Een JSON-matrix met de uitvoeringsgeschiedenis van de indeling. Dit veld is null tenzij de showHistory querytekenreeksparameter is ingesteld op true.

Hier volgt een voorbeeld van een nettolading van reacties, waaronder de uitvoeringsgeschiedenis van de indeling 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 exemplaren ophalen

U kunt ook een query uitvoeren op de status van alle exemplaren door de instanceId aanvraag Exemplaarstatus ophalen te verwijderen. In dit geval zijn de basisparameters hetzelfde als de status Van het exemplaar ophalen. Queryreeksparameters voor filteren worden ook ondersteund.

Aanvragen

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 Beschrijving
showInput Queryreeks Optionele parameter. Als deze optie is ingesteld false, wordt de functie-invoer niet opgenomen in de nettolading van het antwoord.
showHistoryOutput Queryreeks Optionele parameter. Als deze optie is ingesteld true, worden de functie-uitvoer opgenomen in de uitvoeringsgeschiedenis van de orchestration.
createdTimeFrom Queryreeks Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Queryreeks 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 Queryreeks 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 Queryreeks 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 Queryreeks Optionele parameter. Wanneer dit is opgegeven, beperkt u het aantal exemplaren dat door de query wordt geretourneerd.

Respons

Hier volgt een voorbeeld van nettoladingen van reacties, waaronder de indelingsstatus (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"
    }
]

Notitie

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 informatie over de tabel Exemplaar vindt u 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.

Let op

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 vervolgtokenwaarde instelt in de volgende aanvraagheader, kunt u de volgende pagina met resultaten ophalen. Deze naam van de aanvraagheader is ook x-ms-continuation-token.

Geschiedenis van één exemplaar opschonen

Hiermee verwijdert u de geschiedenis en gerelateerde artefacten voor een opgegeven orchestration-exemplaar.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.

Respons

De volgende HTTP-statuscodewaarden kunnen worden geretourneerd.

  • HTTP 200 (OK):de exemplaargeschiedenis is verwijderd.
  • 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 Beschrijving
instancesDeleted geheel getal Het aantal exemplaren dat is verwijderd. Voor het geval van één exemplaar moet deze waarde altijd zijn 1.

Hier volgt een voorbeeld van een nettolading van een antwoord (opgemaakt voor leesbaarheid):

{
    "instancesDeleted": 1
}

Meerdere exemplaargeschiedenissen opschonen

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

Aanvragen

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 Beschrijving
createdTimeFrom Queryreeks Hiermee filtert u de lijst met opgeschoonde exemplaren die zijn gemaakt op of na de opgegeven ISO8601 tijdstempel.
createdTimeTo Queryreeks 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 Queryreeks Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met opgeschoonde exemplaren op basis van hun runtimestatus. Zie het artikel Querying-exemplaren voor de lijst met mogelijke runtimestatuswaarden.

Notitie

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

Respons

De volgende HTTP-statuscodewaarden kunnen worden geretourneerd.

  • HTTP 200 (OK):de exemplaargeschiedenis is 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 Beschrijving
instancesDeleted geheel getal Het aantal exemplaren dat is verwijderd.

Hier volgt een voorbeeld van een nettolading van een antwoord (opgemaakt voor leesbaarheid):

{
    "instancesDeleted": 250
}

Gebeurtenis genereren

Hiermee wordt een bericht over een gebeurtenismelding verzonden naar een actieve orchestration-instantie.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
eventName URL De naam van de gebeurtenis waarop het doelindelingexemplaar wacht.
{content} Inhoud aanvragen De nettolading van de JSON-indeling.

Respons

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.

Exemplaar beëindigen

Hiermee wordt een actief orchestration-exemplaar beëindigd.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
reason Queryreeks Optioneel. De reden voor het beëindigen van het indelingsexemplaar.

Respons

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.

Exemplaar onderbreken

Onderbreekt een actieve orchestrationinstantie.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
reason Queryreeks Optioneel. De reden voor het onderbreken van het indelingsexemplaar.

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.

Exemplaar hervatten

Hiermee wordt een onderbroken indelingsexemplaar hervat.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
reason Queryreeks Optioneel. De reden voor het hervatten van het indelingsexemplaar.

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 mislukt indelingsexemplaar in een actieve status door de meest recente mislukte bewerkingen opnieuw af te spelen.

Aanvragen

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 Beschrijving
instanceId URL De id van het indelingsexemplaar.
reason Queryreeks Optioneel. De reden voor het terugspoelen van het orchestration-exemplaar.

Respons

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 teruggespoelen en een reden van een vast probleem 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.

Notitie

Duurzame entiteiten zijn beschikbaar vanaf Durable Functions 2.0.

Aanvragen

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 Beschrijving
entityName URL De naam (het type) van de entiteit.
entityKey URL De sleutel (unieke id) van de entiteit.
op Queryreeks Optioneel. De naam van de door de gebruiker gedefinieerde bewerking die moet worden aangeroepen.
{content} Inhoud aanvragen De nettolading van de 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

Notitie

Standaard met op klassen gebaseerde entiteiten in .NET, waarbij de op waarde wordt opgegeven voor delete 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.

Respons

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.

Aanvragen

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}

Respons

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.

Opmerking

In het volgende voorbeeld van een HTTP-aanvraag wordt de status van een bestaande Counter entiteit met de naam opgehaald 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 vermelden

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

Aanvragen

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 Beschrijving
entityName URL Optioneel. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde entiteiten op basis van hun entiteitsnaam (hoofdlettergevoelig).
fetchState Queryreeks Optionele parameter. Indien ingesteld op true, wordt de entiteitsstatus opgenomen in de nettolading van het antwoord.
lastOperationTimeFrom Queryreeks Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde entiteiten die bewerkingen hebben verwerkt na de gegeven ISO8601 tijdstempel.
lastOperationTimeTo Queryreeks Optionele parameter. Wanneer dit is opgegeven, filtert u de lijst met geretourneerde entiteiten die bewerkingen hebben verwerkt vóór de opgegeven ISO8601 tijdstempel.
top Queryreeks Optionele parameter. Wanneer dit is opgegeven, beperkt u het aantal entiteiten dat door de query wordt geretourneerd.

Respons

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 vervolgtokenwaarde instelt in de volgende aanvraagheader, kunt u de volgende pagina met 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