HTTP-API-Referenz

  • Artikel

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": "111deb5d-09df-4604-992e-a968345530a9"
}

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.

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.

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.