HTTP-API-Referenz

Die Durable Functions erweiterung macht eine Reihe integrierter HTTP-APIs verfügbar, die Verwaltungsaufgaben für orchestrations, entities und task hubs ausführen können. Diese HTTP-APIs sind Erweiterbarkeitswebhooks, die der Azure Functions Host autorisiert, aber die Durable Functions Erweiterung behandelt direkt.

Bevor Sie diese HTTP-APIs verwenden, stellen Sie sicher, dass Sie folgendes haben:

• Grundlegendes Verständnis der Konzepte der Programmplanung für dauerhafte Aufgaben (Orchestratoren, Aktivitäten, Entitäten)
• Ein Durable Functions-Projekt mit konfigurierten Bindungen initialisiert
• Zugriff auf die Basis-URL, den Aufgabenhubnamen, die Verbindungseinstellungen und den Autorisierungsschlüssel Ihrer Funktions-App

Basis-URL und allgemeine Parameter

Alle HTTP-APIs verwenden dieselbe Basis-URL wie Ihre Funktions-App. Wenn Sie lokal mithilfe der Azure Functions Core Tools entwickeln, wird die Basis-URL in der Regel http://localhost:7071. Im Azure Functions gehosteten Dienst ist die Basis-URL in der Regel https://{appName}.azurewebsites.net. Die Erweiterung unterstützt auch benutzerdefinierte Hostnamen, wenn sie in Ihrer App Service-App konfiguriert sind.

Alle von der Erweiterung implementierten HTTP-APIs erfordern die folgenden Parameter. Der Datentyp aller Parameter lautet string.

Abrufen von Parameterwerten

Verwenden von Orchestrierungsclientbindungen (empfohlen): Generieren Sie vollständige URLs automatisch mithilfe von Orchestrierungsclientbindungs-APIs :

• .NET: CreateCheckStatusResponse(), CreateHttpManagementPayload()
• JavaScript: createCheckStatusResponse(), createHttpManagementPayload()

Manuelle URL-Konstruktion:

• taskHub: Aus host.json Datei abgerufen:

  • v2.x: extensions.durableTask.hubName
  • v1.x: durableTask.hubName
  • Kann auch mithilfe von Syntax über %AppSettingName% App-Einstellungen konfiguriert werden

• connection: Name der App-Einstellung, die die Speicherverbindung enthält. Abgerufen von host.json:

  • v2.x: extensions.durableTask.storageProvider.connectionStringName (Standardwert: AzureWebJobsStorage wenn nicht angegeben)
  • v1.x: durableTask.azureStorageConnectionStringName (Standardwert: AzureWebJobsStorage wenn nicht angegeben)
  • Kann Verbindungszeichenfolgen oder identity-basierte Verbindungen verwenden (Microsoft Entra Authentifizierung)

• systemKey: Erweiterungsspezifischer Autorisierungsschlüssel für dauerhafte Aufgaben-APIs. Abgerufen aus Azure Portal:

  1. Öffnen der Funktions-App
  2. Auswählen von Funktionen → App-Tasten im linken Menü
  3. Suchen Sie im Abschnitt "Systemschlüssel " den Schlüssel (normalerweise automatisch generiert für die Erweiterung)
  4. Kopieren des Schlüsselwerts

  ⚠️Security note: Der Systemschlüssel gewährt Zugriff auf alle Durable Functions HTTP-APIs. Geben Sie sie nicht öffentlich frei oder fügen Sie sie nicht in clientseitigen Code ein.

Jede HTTP-API unterstützt einen konsistenten Satz von Anforderungs-/Antwortmustern. Die folgenden Abschnitte enthalten Informationen für jeden Vorgang.

Allgemeiner API-Workflow

Ein typischer Orchestrierungslebenszyklus folgt dieser Sequenz:

1. Starten der Orchestrierung → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → Gibt Instanz-ID und Status-URL zurück.
2. Überprüfen des Status → GET /runtime/webhooks/durabletask/instances/{instanceId} → Überwachen des Status
3. Senden eines Ereignisses (optional) → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} → Senden externer Signale
4. Bereinigen (optional) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} → Bereinigungsverlaufs

Einzelheiten zu Vorgängen und Anforderungs-/Antwortbeispielen finden Sie in der nachstehenden Referenz.

Orchestrierung starten

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

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

• HTTP 202 (Akzeptiert): Die angegebene Orchestratorfunktion wurde für den Start der Ausführung geplant. Der Location Antwortheader enthält eine URL zum Abfragen des Orchestrierungsstatus.
• HTTP 400 (ungültige Anforderung):Die angegebene Orchestratorfunktion ist nicht vorhanden, die angegebene Instanz-ID ist ungültig, oder Anforderungsinhalte sind ungültig.

Es folgt eine Beispielanforderung, die eine RestartVMs Orchestratorfunktion startet und eine JSON-Objektnutzlast enthält:

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:

Der Datentyp aller Felder ist string.

Hier ist eine Beispiel-Antwort-Payload für eine Orchestrierungsinstanz mit der ID abc123, formatiert zur besseren Lesbarkeit.

{
    "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 soll mit dem Abfrage-Consumermuster kompatibel sein. Sie enthält auch die folgenden bemerkenswerten Antwortheader:

• Speicherort: Die URL des Statusendpunkts, der denselben Wert wie das statusQueryGetUri Feld enthält.
• Retry-After: Die Anzahl der Sekunden, die zwischen Abfragevorgängen gewartet werden sollen. Der Standardwert ist 10.

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

Instanzstatus abrufen

Ruft den Status einer angegebenen Orchestrierungsinstanz ab. Verwenden Sie dies, um den Orchestrierungsstatus zu überwachen und Ergebnisse abzurufen.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

GET /admin/extensions/DurableTaskExtension/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 umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

• HTTP 200 (OK): Die angegebene Instanz befindet sich in einem abgeschlossenen oder fehlgeschlagenen Zustand.
• HTTP 202 (Akzeptiert): Die angegebene Instanz wird ausgeführt.
• HTTP 400 (ungültige Anforderung):Die angegebene Instanz ist fehlgeschlagen oder wurde beendet.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz ist nicht vorhanden oder wurde nicht ausgeführt.
• HTTP 500 (Interner Serverfehler): Wird nur zurückgegeben, wenn returnInternalServerErrorOnFailure auf true gesetzt ist und die angegebene Instanz aufgrund einer unbehandelten Ausnahme fehlgeschlagen ist.

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

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 HTTP 202-Antwort enthält auch einen Location-Antwortheader, der auf dieselbe URL verweist wie das statusQueryGetUri zuvor erwähnte Feld.

Abrufen des Status aller Instanzen

Fragt den Status mehrerer Orchestrierungsinstanzen gleichzeitig ab. Sie können Ergebnisse nach Status, Erstellungszeit und Instanz-ID-Präfix filtern. Verwenden Sie diesen Vorgang, um alle aktiven Orchestrierungen zu überwachen oder bestimmte Instanzen zu suchen.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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}

Funktionslaufzeit 1.x (Legacy):

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}

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

Nachfolgend finden Sie ein Beispiel für Antwortnutzlasten, einschließlich des Orchestrierungsstatus (formatiert für die Lesbarkeit):

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

Wenn weitere Ergebnisse vorhanden sind, wird ein Fortsetzungstoken im Antwortheader zurückgegeben. Der Name der Kopfzeile lautet x-ms-continuation-token.

Wenn Sie den Fortsetzungstokenwert im nächsten Anforderungsheader festlegen, können Sie die nächste Seite mit Ergebnissen abrufen. Der Name des Anforderungsheaders ist ebenfalls x-ms-continuation-token.

Verlauf einzelner Instanzen löschen

Löscht die Historie und die damit assoziierten Artefakte für eine angegebene Orchestrierungsinstanz. Dieser Vorgang gibt Speicherressourcen frei und kann nicht rückgängig gemacht werden.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

• HTTP 200 (OK):Der Instanzverlauf wurde erfolgreich gelöscht.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz ist nicht vorhanden.

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

Hier ist eine Beispielantwort-Datenlast (formatiert für die Lesbarkeit):

{
    "instancesDeleted": 1
}

Protokolle mehrerer Instanzen löschen

Löscht Verlauf und Artefakte für mehrere Instanzen gleichzeitig, gefiltert nach Status, Erstellungszeit oder Instanz-ID-Präfix. Verwenden Sie dies, um alte Instanzen mit Massenbereinigung zu bereinigen und Speicherkosten zu verwalten.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

• HTTP 200 (OK):Der Instanzverlauf wurde erfolgreich gelöscht.
• HTTP 404 (Nicht gefunden):Es wurden keine Instanzen gefunden, die mit dem Filterausdruck übereinstimmen.

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

Hier ist eine Beispielantwort-Datenlast (formatiert für die Lesbarkeit):

{
    "instancesDeleted": 250
}

Ereignis auslösen

Sendet eine Ereignisbenachrichtigung an eine ausgeführte Orchestrierungsinstanz. Die Orchestrierung muss mit dem Namen oder wait_for_external_eventdem Namen WaitForExternalEvent auf dieses Ereignis warten.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

• HTTP 202 (Akzeptiert): Das ausgelöste Ereignis wurde zur Verarbeitung akzeptiert.
• HTTP 400 (ungültige Anforderung):Der Anforderungsinhalt war nicht vom Typ oder application/json war kein gültiger JSON-Code.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz wurde nicht gefunden.
• HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder fehlgeschlagen und kann keine ausgelösten Ereignisse verarbeiten.

Nachfolgend sehen Sie eine Beispielanforderung, die die JSON-Zeichenfolge "incr" an eine Instanz sendet, die auf einen Ereignisnamenvorgang 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 keine Inhalte.

Instanz beenden

Beendet eine laufende Orchestrierungsinstanz.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und den folgenden eindeutigen Parameter.

Antwort

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

• HTTP 202 (Akzeptiert): Die Beendigungsanforderung wurde zur Verarbeitung akzeptiert.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz wurde nicht gefunden.
• HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder fehlgeschlagen.

Im Folgenden sehen Sie eine Beispielanforderung, die eine ausgeführte Instanz beendet und einen Grund für Den Fehler angibt:

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

Die Antworten für diese API enthalten keine Inhalte.

Instanz anhalten

Hält eine ausgeführte Orchestrierungsinstanz an, ohne sie zu beenden. Die Instanz kann später mithilfe des resume Vorgangs fortgesetzt werden.

Anfrage

In Version 2.x der Funktionslaufzeit ist die Anforderung wie folgt formatiert (es werden mehrere Zeilen übersichtlich dargestellt):

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

Antwort

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

• HTTP 202 (Akzeptiert): Die Suspendierungsanforderung wurde zur Verarbeitung akzeptiert. Es wird kein Antworttext zurückgegeben.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz wurde nicht gefunden.
• HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen, fehlgeschlagen oder beendet und kann nicht angehalten werden.

Überprüfung: Fragen Sie nach dem Empfang von HTTP 202 den Instanzstatus ab GET /runtime/webhooks/durabletask/instances/{instanceId} , um zu überprüfen, ob runtimeStatus dies geändert wurde "Suspended".

Instanz wieder aufnehmen

Setzt die Ausführung einer zuvor angehaltenen Orchestrierungsinstanz fort.

Anfrage

In Version 2.x der Funktionslaufzeit ist die Anforderung wie folgt formatiert (es werden mehrere Zeilen übersichtlich dargestellt):

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

Antwort

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

• HTTP 202 (Akzeptiert): Die Wiederaufnahmeanforderung wurde zur Verarbeitung akzeptiert. Es wird kein Antworttext zurückgegeben.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz wurde nicht gefunden.
• HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen, fehlgeschlagen oder beendet und kann nicht fortgesetzt werden.

Überprüfung: Fragen Sie nach dem Empfang von HTTP 202 den Instanzstatus ab GET /runtime/webhooks/durabletask/instances/{instanceId} , um zu überprüfen, ob runtimeStatus dies geändert wurde "Running".

Instanz zurückspulen (Vorschau)

Stellt eine fehlerhafte Orchestrierungsinstanz in den Zustand „Wird ausgeführt“ zurück, indem die letzten fehlerhaften Vorgänge erneut durchgeführt werden. Dieses Feature ermöglicht die Wiederherstellung von vorübergehenden Fehlern ohne manuelle Eingriffe.

Anfrage

Funktionslaufzeit 2.x (empfohlen):

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

Funktionslaufzeit 1.x (Legacy):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und den folgenden eindeutigen Parameter.

Antwort

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

• HTTP 202 (Akzeptiert): Die Rewind-Anforderung wurde zur Verarbeitung akzeptiert.
• HTTP 404 (Nicht gefunden):Die angegebene Instanz wurde nicht gefunden.
• HTTP 410 (Gone): Die angegebene Instanz wurde abgeschlossen oder beendet.

Nachfolgend sehen Sie eine Beispielanforderung, die eine fehlgeschlagene Instanz zurückspult und einen Grund für behoben angibt.

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

Die Antworten für diese API enthalten keine Inhalte.

Signalentität

Sendet eine einseitige Nachricht an eine dauerhafte Entität. Wenn die Entität nicht vorhanden ist, wird sie automatisch erstellt. Entitätsvorgänge werden sequenziell verarbeitet und dauerhaft beibehalten.

Anfrage

Die HTTP-Anforderung ist wie folgt formatiert (mehrere Zeilen werden übersichtlich dargestellt):

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

Anforderungsparameter für diese API umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Hier ist eine Beispielanforderung, die eine benutzerdefinierte "Add"-Nachricht an eine Counter Entität mit dem Namen stepssendet. Der Inhalt der Nachricht ist der Wert 5. Wenn die Entität noch nicht vorhanden ist, erstellt diese Anforderung folgendes:

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

5

Antwort

Dieser Vorgang hat mehrere mögliche Antworten:

• HTTP 202 (Akzeptiert): Der Signalvorgang wurde für die asynchrone Verarbeitung akzeptiert.
• HTTP 400 (ungültige Anforderung): Der Anforderungsinhalt war nicht vom Typ application/json, war ungültiger JSON-Code oder hat einen ungültigen entityKey Wert.
• HTTP 404 (Nicht gefunden): Der angegebene entityName Parameter wurde nicht gefunden.

Eine erfolgreiche HTTP-Anforderung enthält keinen Inhalt in der Antwort. Eine fehlgeschlagene HTTP-Anforderung enthält möglicherweise JSON-formatierte Fehlerinformationen im Antwortinhalt.

Entität abrufen

Ruft den Status der angegebenen Entität ab.

Anfrage

Die HTTP-Anforderung ist wie folgt formatiert (mehrere Zeilen werden übersichtlich dargestellt):

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

Antwort

Dieser Vorgang hat zwei mögliche Antworten:

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

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

Example

So rufen Sie den Status einer vorhandenen Counter Entität mit dem Namen stepsab:

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

Wenn die Counter Entität einfach eine Reihe von Schritten enthielt, die in einem currentValue Feld gespeichert wurden, sieht der Antwortinhalt möglicherweise wie folgt aus (formatiert für die Lesbarkeit):

{
    "currentValue": 5
}

Entitäten auflisten

Sie können mehrere Entitäten nach dem Entitätsnamen oder nach dem datum des letzten Vorgangs abfragen.

Anfrage

Die HTTP-Anforderung ist wie folgt formatiert (mehrere Zeilen werden übersichtlich dargestellt):

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 umfassen den zuvor erwähnten Standardsatz und die folgenden eindeutigen Parameter:

Antwort

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

Standardmäßig gibt der Vorgang die ersten 100 Entitäten zurück, die den Abfragekriterien entsprechen. Der Aufrufer kann einen Parameterwert in der Abfragezeichenfolge für top angeben, um eine andere maximale Anzahl von Ergebnissen zurückzuerhalten. Wenn mehr Ergebnisse über das zurückgegebene Ergebnis hinausgehen, wird auch ein Fortsetzungstoken im Antwortheader zurückgegeben. Der Name der Kopfzeile lautet x-ms-continuation-token.

Wenn Sie den Fortsetzungstokenwert im nächsten Anforderungsheader festlegen, können Sie die nächste Seite mit Ergebnissen abrufen. Der Name des Anforderungsheaders ist ebenfalls x-ms-continuation-token.

Beispiel: Auflisten aller Entitäten

So listen Sie alle Entitäten im Aufgabenhub auf:

GET /runtime/webhooks/durabletask/entities

Der ANTWORT-JSON-Code sieht möglicherweise wie folgt aus (formatiert für die Lesbarkeit):

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

So listen Sie die ersten beiden counter Entitäten auf und rufen ihren Status ab:

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

Der ANTWORT-JSON-Code sieht möglicherweise wie folgt aus (formatiert für die Lesbarkeit):

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

Vollständiges Workflowbeispiel

In diesem Beispiel wird ein vollständiger Orchestrierungslebenszyklus mithilfe von curl Befehlen veranschaulicht. Sie können auch Postman, Thunder Client oder einen beliebigen HTTP-Client verwenden.

1. Starten einer Orchestrierung

Starten einer neuen ProcessOrder Orchestrierung mit Eingabedaten:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/orchestrators/ProcessOrder" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "amount": 150.00
  }'

Antwort (HTTP 202):

{
  "id": "abc123def456",
  "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX",
  "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/{eventName}?code=XXX",
  "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/terminate?reason={text}&code=XXX"
}

Speichern Sie die Instanz-ID: abc123def456

2. Abrufen des Status

Überprüfen des Orchestrierungsfortschritts:

curl "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Antwort während der Ausführung (HTTP 202):

{
  "runtimeStatus": "Running",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": null,
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:05Z"
}

Antwort nach Abschluss (HTTP 200):

{
  "runtimeStatus": "Completed",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": { "status": "shipped", "trackingNumber": "TRK-98765" },
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:15Z"
}

3. Senden eines externen Ereignisses (optional)

Wenn die Orchestrierung auf Genehmigung wartet, senden Sie ein Genehmigungsereignis:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/ApprovalReceived?code=XXX" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true, "reviewer": "manager@contoso.com" }'

Antwort: HTTP 202 (akzeptiert)

4. Bereinigen des Verlaufs (optional)

Nach Abschluss der Orchestrierung löschen Sie ihre Geschichte:

curl -X DELETE "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

Antwort (HTTP 200):

{
  "instancesDeleted": 1
}

Nächste Schritte