HTTP-API-Referenz

Artikel
06/01/2023

Die Durable Functions-Erweiterung macht eine Reihe integrierter HTTP-APIs verfügbar, die verwendet werden können, um Verwaltungsaufgaben für Orchestrierungen, Entitäten und Aufgabenhubs auszuführen. Diese HTTP-APIs sind Erweiterbarkeitswebhooks, die vom Azure Functions-Host autorisiert, aber direkt von der Durable Functions-Erweiterung verarbeitet werden.

Die Basis-URL für die in diesem Artikel erwähnten APIs ist mit der Basis-URL für Ihre Funktions-App identisch. Bei der lokalen Entwicklung mithilfe der Azure Functions Core Tools lautet die Basis-URL in der Regel http://localhost:7071. Im von Azure Functions gehosteten Dienst lautet die Basis-URL in der Regel https://{appName}.azurewebsites.net. Benutzerdefinierte Hostnamen werden auch unterstützt, wenn sie für Ihre App Service-App konfiguriert sind.

Alle HTTP-APIs, die von der Erweiterung implementiert werden, benötigen die folgenden Parameter. Alle Parameter haben den Datentyp string.

Parameter	Parametertyp	BESCHREIBUNG
`taskHub`	Abfragezeichenfolge	Der Name des Aufgabenhub. Wenn er nicht angegeben ist, wird der Name des Aufgabenhub der aktuellen Funktionen-App verwendet.
`connection`	Abfragezeichenfolge	Dies ist der Name der Einstellung der Verbindungs-App für den Back-End-Speicheranbieter. Wenn nichts angegeben ist, wird die Standardverbindungskonfiguration für die Funktions-App genutzt.
`systemKey`	Abfragezeichenfolge	Der Autorisierungsschlüssel, der zum Aufrufen der API erforderlich ist.

systemKey ist ein Autorisierungsschlüssel, der vom Azure Functions-Host automatisch generiert wird. Der Name gewährt spezifischen Zugriff auf die APIs der Erweiterung „Durable Task“ und kann genauso wie andere Azure Functions-Zugriffsschlüssel verwaltet werden. Sie können URLs, die die korrekten Werte der Abfragezeichenfolge für taskHub, connection und systemKey enthalten, mithilfe von Orchestrierungsclientbindungs-APIs wie z. B. der CreateCheckStatusResponse- und CreateHttpManagementPayload-APIs in .NET oder der createCheckStatusResponse- und createHttpManagementPayload-APIs in JavaScript generieren.

In den nächsten Abschnitten werden die spezifischen HTTP-APIs behandelt, die von der Erweiterung unterstützt werden, und es sind Anwendungsbeispiele vorhanden.

Starten der Orchestrierung

Startet die Ausführung einer neuen Instanz der angegebenen Orchestratorfunktion.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`functionName`	URL	Der Name der zu startenden Orchestratorfunktion.
`instanceId`	URL	Dieser Parameter ist optional. ID der Orchestrierungsinstanz Wenn kein Wert angegeben wird, beginnt die Orchestratorfunktion mit einer zufälligen Instanz-ID.
`{content}`	Inhalt anfordern	Dies ist optional. Die Eingabe für die JSON-formatierte Orchestratorfunktion.

Antwort

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Der Beginn der Ausführung der angegebenen Orchestratorfunktion wurde geplant. Der Location-Antwortheader enthält eine URL zum Abrufen des Orchestrierungsstatus.
HTTP 400 (Bad request): Die angegebene Orchestratorfunktion ist nicht vorhanden, die angegebene Instanz-ID war ungültig oder der Anforderungsinhalt war kein gültiger JSON-Code.

Die folgende Beispielanforderung startet eine RestartVMs-Orchestratorfunktion und umfasst die JSON-Objektnutzdaten:

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

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

Die Antwortnutzlast für die HTTP 202-Fälle ist ein JSON-Objekt mit den folgenden Feldern:

Feld	BESCHREIBUNG
`id`	ID der Orchestrierungsinstanz
`statusQueryGetUri`	Status-URL der Orchestrierungsinstanz
`sendEventPostUri`	URL der Orchestrierungsinstanz für die „Ereignisauslösung“
`terminatePostUri`	URL der Orchestrierungsinstanz für die „Beendigung“
`purgeHistoryDeleteUri`	URL der Orchestrierungsinstanz für den „Bereinigungsverlauf“
`rewindPostUri`	(Vorschauversion) URL der Orchestrierungsinstanz für den „Rücklauf“
`suspendPostUri`	Die URL vom Typ „Anhalten“ der Orchestrierungsinstanz.
`resumePostUri`	Die URL vom Typ „Fortsetzen“ der Orchestrierungsinstanz.

Der Datentyp aller Felder lautet string.

Diese Beispielantwortnutzlast für eine Orchestrierungsinstanz hat abc123 als ID (zur besseren Lesbarkeit formatiert):

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

Die HTTP-Antwort muss mit dem Polling Consumer Pattern (Consumerabrufmuster) kompatibel sein. Sie enthält auch die folgenden bedeutenden Antwortheader:

Location (Standort): Hierbei handelt es sich um die URL des Statusendpunkts. Diese URL enthält denselben Wert wie das statusQueryGetUri-Feld.
Retry-After (Wiederholung nach): Hierbei handelt es sich um die Anzahl der Sekunden, für die zwischen Abrufvorgängen gewartet werden soll. Standardwert: 10.

Weitere Informationen zum asynchronen HTTP-Abrufmuster finden Sie in der Dokumentation Nachverfolgen von asynchronen Vorgängen.

Abrufen des Instanzstatus (Get instance status)

Dient zum Abrufen des Status einer angegebenen Orchestrierungsinstanz.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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 Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`showInput`	Abfragezeichenfolge	Dieser Parameter ist optional. Bei Festlegung auf `false` wird die Funktionseingabe nicht die Antwortnutzlast aufgenommen.
`showHistory`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn diese Option auf `true` gesetzt ist, wird der Ausführungsverlauf der Orchestrierung in die Antwortnutzlast aufgenommen.
`showHistoryOutput`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn diese Option auf `true` festgelegt ist, werden die Funktionsausgaben in den Ausführungsverlauf der Orchestrierung aufgenommen.
`createdTimeFrom`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen Instanzen, die am oder nach dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`createdTimeTo`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen-Instanzen, die am oder vor dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`runtimeStatus`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen Instanzen auf der Grundlage ihres Laufzeitstatus. Die Liste der möglichen Werte für den Laufzeitstatus finden Sie im Artikel Abfragen von Instanzen.
`returnInternalServerErrorOnFailure`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn dieser Wert auf `true` festgelegt ist, gibt diese API eine HTTP 500-Antwort anstelle von 200 zurück, wenn sich die Instanz in einem Fehlerzustand befindet. Dieser Parameter ist für automatisierte Status-Abrufszenarios vorgesehen.

Antwort

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 200 (OK) : Die angegebene Instanz befindet sich im Status „Completed“ (Abgeschlossen) oder „Failed“ (Fehlgeschlagen).
HTTP 202 (Accepted): Die angegebene Instanz befindet sich in der Bearbeitung.
HTTP 400 (Bad Request): Für die angegebene Instanz ist ein Fehler aufgetreten, oder sie wurde beendet.
HTTP 404 (Not Found): Die angegebene Instanz ist nicht vorhanden, oder die Ausführung wurde noch nicht gestartet.
HTTP 500 (Internal Server Error) : Wird nur zurückgegeben, wenn returnInternalServerErrorOnFailure auf true festgelegt ist und bei der angegebenen Instanz ein Ausnahmefehler aufgetreten ist.

Die Antwortnutzlast für die Fälle HTTP 200 und HTTP 202 ist ein JSON-Objekt mit den folgenden Feldern:

Feld	Datentyp	Beschreibung
`runtimeStatus`	Zeichenfolge	Der Laufzeitstatus der Instanz. Mögliche Werte sind Running, Pending, Failed, Canceled, Terminated, Completed und Suspended.
`input`	JSON	Die JSON-Daten, die zum Initialisieren der Instanz verwendet werden. Dieses Feld lautet `null`, wenn der Abfragezeichenfolgenparameter `showInput` auf `false` festgelegt ist.
`customStatus`	JSON	Die für den benutzerdefinierten Orchestrierungsstatus verwendeten JSON-Daten. Dieses Feld ist `null`, sofern nichts anderes festgelegt wurde.
`output`	JSON	Die JSON-Ausgabe der Instanz. Dieses Feld ist `null`, wenn die Instanz nicht den Status „Completed“ (Abgeschlossen) aufweist.
`createdTime`	Zeichenfolge	Der Zeitpunkt, zu dem die Instanz erstellt wurde. Es wird die erweiterte ISO 8601-Notation verwendet.
`lastUpdatedTime`	Zeichenfolge	Der Zeitpunkt, zu dem die Instanz zuletzt persistent gemacht wurde. Es wird die erweiterte ISO 8601-Notation verwendet.
`historyEvents`	JSON	Ein JSON-Array, das den Ausführungsverlauf der Orchestrierung enthält. Dieses Feld ist `null`, sofern der Abfragezeichenfolgen-Parameter `showHistory` auf `true` festgelegt ist.

Hier sehen Sie ein Beispiel für eine Antwortnutzlast mit dem Ausführungsverlauf der Orchestrierung und den Aktivitätsausgaben (zur besseren Lesbarkeit formatiert):

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

Die Antwort HTTP 202 enthält auch den Antwortheader Location, in dem auf die gleiche URL wie im oben erwähnten Feld statusQueryGetUri verwiesen wird.

Abrufen aller Instanzstatus

Sie können auch den Status aller Instanzen abfragen, indem Sie die instanceId aus der Anforderung „Get instance status“ (Abrufen des Instanzstatus) entfernen. In diesem Fall entsprechen die grundlegenden Parameter der Anforderung „Get instance status“. Abfragezeichenfolgeparameter zum Filtern werden auch unterstützt.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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 Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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}

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`showInput`	Abfragezeichenfolge	Dieser Parameter ist optional. Bei Festlegung auf `false` wird die Funktionseingabe nicht die Antwortnutzlast aufgenommen.
`showHistoryOutput`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn diese Option auf `true` festgelegt ist, werden die Funktionsausgaben in den Ausführungsverlauf der Orchestrierung aufgenommen.
`createdTimeFrom`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen Instanzen, die am oder nach dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`createdTimeTo`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen-Instanzen, die am oder vor dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`runtimeStatus`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der zurückgegebenen Instanzen auf der Grundlage ihres Laufzeitstatus. Die Liste der möglichen Werte für den Laufzeitstatus finden Sie im Artikel Abfragen von Instanzen.
`instanceIdPrefix`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn angegeben, wird die Liste der zurückgegebenen Instanzen so gefiltert, dass nur Instanzen angezeigt werden, deren Instanz-ID mit der angegebenen Präfixzeichenfolge beginnt. Verfügbar ab Version 2.7.2 der Erweiterung.
`top`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn er angegeben wird, begrenzt er die Anzahl von Instanzen, die von der Abfrage zurückgegeben werden.

Antwort

Hier ist ein Beispiel für Antwortnutzlasten einschließlich des Orchestrierungsstatus (für bessere Lesbarkeit formatiert):

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

Hinweis

Dieser Vorgang kann im Hinblick auf die Azure Storage-E/A sehr teuer sein, wenn Sie den standardmäßigen Azure Storage-Anbieter verwenden und viele Zeilen in der Instances-Tabelle vorhanden sind. Weitere Details zur Instanztabelle finden Sie in der Azure Storage-Anbieter-Dokumentation.

Wenn mehr Ergebnisse vorhanden sind, wird ein Fortsetzungstoken im Antwortheader zurückgegeben. Der Name des Headers lautet x-ms-continuation-token.

Achtung

Das Abfrageergebnis kann weniger Elemente zurückgeben als die durch top angegebene Grenze. Beim Empfangen von Ergebnissen sollten Sie daher immer überprüfen, ob ein Fortsetzungstoken vorhanden ist.

Wenn Sie den Wert des Fortsetzungstokens im nächsten Anforderungsheader festlegen, können Sie die nächste Seite mit Ergebnissen abrufen. Dieser Name für den Anforderungsheader ist auch x-ms-continuation-token.

Löschen des Verlaufs für eine einzelne Instanz

Löscht den Verlauf und zugehörige Artefakte für eine bestimmte Orchestrierungsinstanz.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz

Antwort

Die folgenden HTTP-Statuscodewerte können zurückgegeben werden:

HTTP 200 (OK): Der Instanzverlauf wurde erfolgreich gelöscht.
HTTP 404 (Not Found): Die angegebene Instanz existiert nicht.

Die Antwortnutzlast für den Fall HTTP 200 ist ein JSON-Objekt mit dem folgenden Feld:

Feld	Datentyp	BESCHREIBUNG
`instancesDeleted`	integer	Die Anzahl der gelöschten Instanzen. Für eine einzelne Instanz sollte dieser Wert immer `1` sein.

Hier ist ein Beispiel für eine Antwortnutzlast angegeben (zur besseren Lesbarkeit formatiert):

{
    "instancesDeleted": 1
}

Löschen der Verläufe für mehrere Instanzen

Sie können auch den Verlauf und zugehörige Artefakte für mehrere Instanzen in einem Aufgabenhub löschen, indem Sie die {instanceId} aus der Anforderung „Purge single instance history“ (Löschen des Verlaufs für eine einzelne Instanz) entfernen. Verwenden Sie die gleichen Filter, die in der Anforderung „Get all instances status“ (Abrufen aller Instanzstatus) beschrieben sind, um selektiv den Verlauf einer Instanz zu löschen.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`createdTimeFrom`	Abfragezeichenfolge	Filtert die Liste der gelöschten Instanzen, die am oder nach dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`createdTimeTo`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der gelöschten Instanzen, die am oder vor dem angegebenen ISO8601-Zeitstempel erstellt wurden.
`runtimeStatus`	Abfragezeichenfolge	Dieser Parameter ist optional. Filtert, wenn er angegeben wird, die Liste der gelöschten Instanzen auf der Grundlage ihres Laufzeitstatus. Die Liste der möglichen Werte für den Laufzeitstatus finden Sie im Artikel Abfragen von Instanzen.

Hinweis

Dieser Vorgang kann im Hinblick auf die Azure Storage-E/A sehr teuer sein, wenn Sie den standardmäßigen Azure Storage-Anbieter verwenden und viele Zeilen in den Instances- und/oder History-Tabellen vorhanden sind. Weitere Informationen zu diesen Tabellen finden Sie in der Dokumentation Leistung und Skalierbarkeit in Durable Functions (Azure Functions).

Antwort

Die folgenden HTTP-Statuscodewerte können zurückgegeben werden:

HTTP 200 (OK): Der Instanzverlauf wurde erfolgreich gelöscht.
HTTP 404 (Not Found): Es wurden keine Instanzen gefunden, die dem Filterausdruck entsprechen.

Die Antwortnutzlast für den Fall HTTP 200 ist ein JSON-Objekt mit dem folgenden Feld:

Feld	Datentyp	BESCHREIBUNG
`instancesDeleted`	integer	Die Anzahl der gelöschten Instanzen.

Hier ist ein Beispiel für eine Antwortnutzlast angegeben (zur besseren Lesbarkeit formatiert):

{
    "instancesDeleted": 250
}

Auslösen eines Ereignisses (Raise event)

Sendet eine Ereignisbenachrichtigung an eine ausgeführte Orchestrierungsinstanz.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`eventName`	URL	Der Name des Ereignisses, das die Zielorchestrierungsinstanz erwartet.
`{content}`	Inhalt anfordern	Ereignisnutzlast in JSON-Formatierung

Antwort

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Das ausgelöste Ereignis wurde zur Verarbeitung akzeptiert.
HTTP 400 (Bad request): Der Anforderungsinhalt hatte nicht den Typ application/json oder war kein gültiger JSON-Code.
HTTP 404 (Not Found): Die angegebene Instanz wurde nicht gefunden.
HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen, oder es ist ein Fehler aufgetreten, sodass keine ausgelösten Ereignisse verarbeitet werden können.

Hier ist eine Beispielanforderung angegeben, bei der die JSON-Zeichenfolge "incr" an eine Instanz gesendet wird, die auf ein Ereignis mit dem Namen operation wartet:

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

"incr"

Die Antworten für diese API enthalten keinen Inhalt.

Beenden der Instanz (Terminate instance)

Dient zum Beenden einer ausgeführten Orchestrierungsinstanz.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`reason`	Abfragezeichenfolge	Dies ist optional. Gibt den Grund für die Beendigung der Orchestrierungsinstanz an.

Antwort

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Die Beendigungsanforderung wurde zur Verarbeitung akzeptiert.
HTTP 404 (Not Found): Die angegebene Instanz wurde nicht gefunden.
HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen, oder es ist ein Fehler aufgetreten.

Hier ist eine Beispielanforderung angegeben, mit der eine ausgeführte Instanz beendet und als Grund buggy (fehlerhaft) angegeben wird:

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

Die Antworten für diese API enthalten keinen Inhalt.

Instanz anhalten

Dient zum Anhalten einer aktuell ausgeführten Orchestrierungsinstanz.

Anforderung

In Version 2.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`reason`	Abfragezeichenfolge	Dies ist optional. Gibt den Grund für das Anhalten der Orchestrierungsinstanz an.

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Die Anforderung zum Anhalten wurde zur Verarbeitung akzeptiert.
HTTP 404 (Not Found): Die angegebene Instanz wurde nicht gefunden.
HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder beendet oder war fehlerhaft.

Die Antworten für diese API enthalten keinen Inhalt.

Instanz fortsetzen

Setzt eine angehaltene Orchestrierungsinstanz fort.

Anforderung

In Version 2.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`reason`	Abfragezeichenfolge	Dies ist optional. Gibt den Grund für das Fortsetzen der Orchestrierungsinstanz an.

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Die Anforderung zum Fortsetzen wurde zur Verarbeitung akzeptiert.
HTTP 404 (Not Found): Die angegebene Instanz wurde nicht gefunden.
HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder beendet oder war fehlerhaft.

Die Antworten für diese API enthalten keinen Inhalt.

Rewind-Instanz (Vorschau)

Stellt eine fehlerhafte Orchestrierungsinstanz in den Zustand „Wird ausgeführt“ zurück, indem die letzten fehlerhaften Vorgänge erneut durchgeführt werden.

Anforderung

Für Version 1.x der Azure Functions-Runtime ist die Anforderung wie folgt formatiert (der besseren Übersichtlichkeit halber werden mehrere Zeilen angezeigt):

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

In Version 2.x der Azure Functions-Runtime hat das URL-Format die gleichen Parameter, jedoch mit einem etwas anderen Präfix:

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`instanceId`	URL	ID der Orchestrierungsinstanz
`reason`	Abfragezeichenfolge	Dies ist optional. Gibt den Grund für das Zurückspulen der Orchestrierungsinstanz an.

Antwort

Es können mehrere mögliche Statuscodewerte zurückgegeben werden.

HTTP 202 (Accepted): Die Anforderung zum Zurückspulen wurde zur Verarbeitung akzeptiert.
HTTP 404 (Not Found): Die angegebene Instanz wurde nicht gefunden.
HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder abgebrochen.

Hier ist eine Beispielanforderung angegeben, die eine fehlerhafte Instanz zurückspult und einen Grund für fixed (behoben) angibt:

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

Die Antworten für diese API enthalten keinen Inhalt.

Signalentität

Sendet eine unidirektionale Vorgangsmeldung an eine dauerhafte Entität. Wenn die Entität nicht vorhanden ist, wird sie automatisch erstellt.

Hinweis

Dauerhafte Entitäten sind ab Durable Functions 2.0 verfügbar.

Anforderung

Die HTTP-Anforderung wird wie folgt formatiert (aus Gründen der Übersichtlichkeit werden mehrere Zeilen angezeigt):

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`entityName`	URL	Der Name (Typ) der Entität
`entityKey`	URL	Der Schlüssel (eindeutige ID) der Entität
`op`	Abfragezeichenfolge	Dies ist optional. Der Name des aufzurufenden benutzerdefinierten Vorgangs
`{content}`	Inhalt anfordern	Ereignisnutzlast in JSON-Formatierung

Nachfolgend sehen Sie eine Beispielanforderung, die eine benutzerdefinierte Meldung vom Typ „Add“ (Hinzufügen) an eine Counter-Entität namens steps sendet. Der Inhalt der Meldung ist der Wert 5. Wenn die Entität nicht bereits vorhanden ist, wird sie von dieser Anforderung erstellt:

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

5

Hinweis

Bei klassenbasierten Entitäten in .NET wird der Zustand einer Entität durch Festlegen des op-Werts von delete standardmäßig gelöscht. Wenn die Entität jedoch einen Vorgang namens delete definiert, wird stattdessen der benutzerdefinierte Vorgang aufgerufen.

Antwort

Für diesen Vorgang sind mehrere Antworten möglich:

HTTP 202 (Accepted): Der Signalvorgang wurde für die asynchrone Verarbeitung akzeptiert.
HTTP 400 (Bad request): Der Anforderungsinhalt war nicht vom Typ application/json, war kein gültiger JSON-Code oder enthielt einen ungültigen entityKey-Wert.
HTTP 404 (Not Found): Die angegebene entityName-Entität wurde nicht gefunden.

Bei einer erfolgreichen HTTP-Anforderung enthält die Antwort keinen Inhalt. Eine fehlgeschlagene HTTP-Anforderung kann im Antwortinhalt JSON-formatierte Fehlerinformationen enthalten.

Entität abrufen

Ruft den Zustand der angegebenen Entität ab.

Anforderung

Die HTTP-Anforderung wird wie folgt formatiert (aus Gründen der Übersichtlichkeit werden mehrere Zeilen angezeigt):

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

Antwort

Für diesen Vorgang sind zwei Antworten möglich:

HTTP 200 (OK): Die angegebene Entität ist vorhanden.
HTTP 404 (Not Found): Die angegebene Entität wurde nicht gefunden.

Eine erfolgreiche Antwort enthält den JSON-serialisierten Zustand der Entität als Inhalt.

Beispiel

Das folgende Beispiel einer HTTP-Anforderung ruft den Zustand einer vorhandenen Counter-Entität namens steps ab:

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

Wenn die Entität Counter einfach eine Reihe von Schritten enthält, die im Feld currentValue gespeichert wurden, kann der Antwortinhalt wie folgt aussehen (zur besseren Lesbarkeit formatiert):

{
    "currentValue": 5
}

Auflisten von Entitäten

Sie können mehrere Entitäten anhand des Entitätsnamens oder des Datums des letzten Vorgangs abfragen.

Anforderung

Die HTTP-Anforderung wird wie folgt formatiert (aus Gründen der Übersichtlichkeit werden mehrere Zeilen angezeigt):

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

Anforderungsparameter für diese API enthalten den bereits erwähnten Standardsatz sowie die folgenden eindeutigen Parameter:

Feld	Parametertyp	BESCHREIBUNG
`entityName`	URL	Dies ist optional. Wenn dieser Parameter angegeben wird, wird die Liste der zurückgegebenen Entitäten anhand der Entitätsnamen gefiltert (dabei wird die Groß-/Kleinschreibung nicht beachtet).
`fetchState`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn dieser Parameter auf `true` festgelegt wird, wird der Zustand der Entität in die Antwortnutzlast eingefügt.
`lastOperationTimeFrom`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn dieser Parameter angegeben wird, werden die Entitäten aus der Liste der zurückgegebenen Entitäten herausgefiltert, die Vorgänge nach dem angegebenen ISO8601-Zeitstempel verarbeitet haben.
`lastOperationTimeTo`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn dieser Parameter angegeben wird, wird die Liste der zurückgegebenen Entitäten gefiltert, die Vorgänge vor dem angegebenen ISO8601-Zeitstempel verarbeitet haben.
`top`	Abfragezeichenfolge	Dieser Parameter ist optional. Wenn dieser Parameter angegeben wird, wird die Anzahl der von der Abfrage zurückgegebenen Entitäten eingeschränkt.

Antwort

Eine erfolgreiche HTTP 200-Antwort enthält ein JSON-serialisiertes Array von Entitäten und optional den Zustand jeder Entität.

Der Vorgang gibt standardmäßig die ersten 100 Entitäten zurück, die mit den Abfragekriterien übereinstimmen. Der Aufrufer kann einen Abfragezeichenfolgen-Parameterwert für top festlegen, um eine andere maximale Anzahl an Ergebnissen zurückzugeben. Wenn mehr Ergebnisse vorhanden sind, als zurückgegeben werden, wird zusätzlich ein Fortsetzungstoken im Antwortheader zurückgegeben. Der Name des Headers lautet x-ms-continuation-token.

Beispiel: Auflisten aller Entitäten

Mit der folgenden HTTP-Beispielanforderung werden alle Entitäten im Aufgabenhub aufgelistet:

GET /runtime/webhooks/durabletask/entities

Die JSON-Antwort sollte wie folgt aussehen (zur besseren Lesbarkeit formatiert):

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

Beispiel: Filtern der Liste der Entitäten

Die folgende HTTP-Beispielanforderung führt nur die ersten zwei Entitäten vom Typ counter auf und ruft ihren Zustand ab:

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

Die JSON-Antwort sollte wie folgt aussehen (zur besseren Lesbarkeit formatiert):

[
    {
        "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ächste Schritte

Erfahren Sie, wie Sie mit Application Insights ihre Durable Functions-Instanzen überwachen.

Freigeben über

HTTP-API-Referenz

Starten der Orchestrierung

Anforderung

Antwort

Abrufen des Instanzstatus (Get instance status)

Anforderung

Antwort

Abrufen aller Instanzstatus

Anforderung

Antwort

Löschen des Verlaufs für eine einzelne Instanz

Anforderung

Antwort

Löschen der Verläufe für mehrere Instanzen

Anforderung

Antwort

Auslösen eines Ereignisses (Raise event)

Anforderung

Antwort

Beenden der Instanz (Terminate instance)

Anforderung

Antwort

Instanz anhalten

Anforderung

Instanz fortsetzen

Anforderung

Rewind-Instanz (Vorschau)

Anforderung

Antwort

Signalentität

Anforderung

Antwort

Entität abrufen

Anforderung

Antwort

Beispiel

Auflisten von Entitäten

Anforderung

Antwort

Beispiel: Auflisten aller Entitäten

Beispiel: Filtern der Liste der Entitäten

Nächste Schritte

Feedback

Zusätzliche Ressourcen