HTTP API-referencia

A Durable Functions bővítmény olyan beépített HTTP API-kat tesz elérhetővé, amelyek felügyeleti feladatokat végezhetnek orchestrations, entities és task Hubs. Ezek a HTTP API-k olyan bővíthetőségi webhookok, amelyeket a Azure Functions gazdagép engedélyez, de a Durable Functions bővítmény közvetlenül kezeli.

A HTTP API-k használata előtt győződjön meg arról, hogy a következőkre van szüksége:

Alap URL-cím és gyakori paraméterek

Minden HTTP API ugyanazzal az alap URL-címel rendelkezik, mint a függvényalkalmazás. Ha a Azure Functions Core Tools használatával fejleszt helyileg, az alap URL-cím általában http://localhost:7071. Az Azure Functions által üzemeltetett szolgáltatásban az alap URL-cím általában https://{appName}.azurewebsites.net. A bővítmény támogatja az egyéni gazdagépneveket is, ha az App Service-alkalmazásban van konfigurálva.

A bővítmény által implementált HTTP API-khoz a következő paraméterek szükségesek. Az összes paraméter adattípusa.string

Paraméter Paraméter típusa Description
taskHub Lekérdezési karakterlánc A tevékenységközpont neve. Ha nincs megadva, a függvényalkalmazás aktuális feladatközpontjának neve lesz feltételezve.
connection Lekérdezési karakterlánc A háttértár-szolgáltató kapcsolatalkalmazás-beállításának neve . Ha nincs megadva, a függvényalkalmazás alapértelmezett kapcsolatkonfigurációja lesz feltételezve.
systemKey Lekérdezési karakterlánc Az API meghívásához szükséges engedélyezési kulcs.

Paraméterértékek beszerzése

Vezénylési ügyfélkötések használata (ajánlott): Teljes URL-címek automatikus létrehozása vezénylési ügyfélkötési API-k használatával:

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

Manuális URL-konstrukció:

  • taskHub: Beolvasva a fájlból host.json :

    • v2.x: extensions.durableTask.hubName
    • v1.x: durableTask.hubName
    • Az alkalmazásbeállítások segítségével szintaxissal %AppSettingName% is konfigurálható

  • connection: A tárkapcsolatot tartalmazó alkalmazásbeállítás neve. Lekért forrás host.json:

    • v2.x: extensions.durableTask.storageProvider.connectionStringName (alapértelmezés szerint AzureWebJobsStorage , ha nincs megadva)
    • v1.x: durableTask.azureStorageConnectionStringName (alapértelmezés szerint AzureWebJobsStorage , ha nincs megadva)
    • Használhat kapcsolati sztringeket vagy identitás-alapú kapcsolatokat (Microsoft Entra hitelesítés)

  • systemKey: A Durable Task API-k bővítményspecifikus engedélyezési kulcsa. Lekérés Azure portálról:

    1. A függvényalkalmazás megnyitása
    2. A függvények → alkalmazáskulcsok kiválasztása a bal oldali menüben
    3. A Rendszerkulcsok szakaszban keresse meg a kulcsot (általában automatikusan generálva a bővítményhez)
    4. A kulcsérték másolása

    ️ Biztonsági megjegyzés: A rendszerkulcs hozzáférést biztosít az összes Durable Functions HTTP API-hoz. Ne ossza meg nyilvánosan, és ne foglalja bele az ügyféloldali kódba.

Minden HTTP API támogatja a kérelmek/válaszminták konzisztens készletét. A következő szakaszok az egyes műveletekre vonatkozó információkat tartalmaznak.

Gyakori API-munkafolyamat

Egy tipikus vezénylési életciklus a következő sorrendet követi:

  1. Vezénylés indítása → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → A példányazonosítót és az állapot URL-címét adja vissza
  2. Állapot ellenőrzése → GET /runtime/webhooks/durabletask/instances/{instanceId} → Figyelés állapota
  3. Esemény küldése (nem kötelező) → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} → Külső jelek küldése
  4. Törlési (nem kötelező) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} → törlési előzmények

A művelet részleteivel és a kérésekkel/válaszokkal kapcsolatos példákért tekintse meg az alábbi hivatkozást.

Orkesztráció indítása

Megkezdi a megadott orchestrátor függvény új példányának végrehajtását.

kérelem

Important

Az URL-formátum a Functions futtatókörnyezet verziója szerint eltérő. Válassza ki a környezetnek megfelelő formátumot.

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
functionName URL Az elindítandó vezénylő függvény neve.
instanceId URL Nem kötelező paraméter. A vezénylési példány azonosítója. Ha nincs megadva, a vezénylő függvény véletlenszerű példányazonosítóval kezdődik.
{content} Tartalom kérése Opcionális. A JSON-formátumú vezénylő függvény bemenete.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): A megadott vezénylőfüggvényt a rendszer úgy ütemezte, hogy elinduljon. A Location válaszfejléc egy URL-címet tartalmaz a vezénylési állapot lekérdezéséhez.
  • HTTP 400 (Hibás kérelem): A megadott vezénylő függvény nem létezik, a megadott példányazonosító érvénytelen, vagy a kérelem tartalma nem érvényes JSON.

Az alábbi példakérés elindít egy vezénylőfüggvényt RestartVMs , és tartalmaz egy hasznos JSON-objektumot:

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

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

A HTTP 202-esetek válaszában található adatok JSON-objektumként jelennek meg, a következő mezőket tartalmazva:

Field Description
id A vezénylési példány azonosítója.
statusQueryGetUri Az orchestration példány állapot URL-címe.
sendEventPostUri Az orchestrációs példány "eseményemelés" URL-címe.
terminatePostUri A vezénylési példány "megszakítás" URL-címe.
purgeHistoryDeleteUri A vezénylési példány "törlési előzményeinek" URL-címe.
rewindPostUri (előzetes verzió) A vezénylési példány "visszatekerési" URL-címe.
suspendPostUri Az orchestrációs példány "felfüggesztés" URL-címe.
resumePostUri A vezénylési példány "folytatás" URL-címe.

Az összes mező adattípusa.string

Íme egy példa válasz hasznos adata egy vezénylési példányra azonosítóként abc123 (olvashatóságra formázva):

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

A HTTP-válasznak kompatibilisnek kell lennie a lekérdezési fogyasztói mintával. A következő fontos válaszfejléceket is tartalmazza:

  • Hely: Az állapotvégpont URL-címe, amely ugyanazt az értéket tartalmazza, mint a statusQueryGetUri mező.
  • Újrapróbálkozás után: A lekérdezési műveletek közötti várakozási másodpercek száma. Az alapértelmezett érték a 10.

Az aszinkron HTTP-lekérdezési mintával kapcsolatos további információkért tekintse meg a HTTP aszinkron műveletkövetési dokumentációját.

Példány állapotának lekérése

Lekérdezi egy adott vezénylési példány állapotát. Ezzel figyelheti a vezénylés előrehaladását, és lekérheti az eredményeket.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
showInput Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van falseállítva, a függvény bemenete nem szerepel a válasz hasznos adatai között.
showHistory Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van trueállítva, a vezénylés végrehajtási előzményei szerepelnek a válasz hasznos adatai között.
showHistoryOutput Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van trueállítva, a függvénykimenetek szerepelnek a vezénylés végrehajtási előzményeiben.
createdTimeFrom Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri az adott ISO8601 időbélyegen vagy után létrehozott visszaadott példányok listáját.
createdTimeTo Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri az adott ISO8601 időbélyegen vagy előtt létrehozott visszaadott példányok listáját.
runtimeStatus Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, a visszaadott példányok listáját a futtatási állapotuk alapján szűri. A lehetséges futtatókörnyezeti állapotértékek listájának megtekintéséhez tekintse meg a Lekérdezéspéldányok című cikket.
returnInternalServerErrorOnFailure Lekérdezési karakterlánc Nem kötelező paraméter. Ha be truevan állítva, az API 200 helyett HTTP 500-választ ad vissza, ha a példány hibaállapotban van. Ez a paraméter automatizált állapot-lekérdezési forgatókönyvekhez készült.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 200 (OK): A megadott példány befejeződött vagy sikertelen állapotban van.
  • HTTP 202 (Elfogadva): A megadott példány folyamatban van.
  • HTTP 400 (hibás kérés): A megadott példány sikertelen lett vagy leállításra került.
  • HTTP 404 (Nem található): A megadott példány nem létezik vagy nem indult el.
  • HTTP 500 (belső kiszolgálóhiba): Csak akkor adja vissza, ha a returnInternalServerErrorOnFailure égyező true van beállítva, és az adott példány nem kezelt kivétellel meghiúsult.

A HTTP 200 és HTTP 202 (esetekben) válasz hasznos adatai egy JSON-objektum, amely a következő mezőket tartalmazza:

Field Adattípus Description
runtimeStatus karakterlánc A példány futtatókörnyezeti állapota. Az értékek közé tartozik a Fut, Függőben, Sikertelen, Megszakított, Megszüntetve, Befejezett, Felfüggesztett.
input JSON A példány inicializálásához használt JSON-adatok. Ez a mező akkor van null beállítva, ha a lekérdezési sztring showInput paramétere a következőre falsevan állítva: .
customStatus JSON Az egyéni vezénylési állapothoz használt JSON-adatok. Ez a mező null ha nincs beállítva.
output JSON A példány JSON-kimenete. Ez a mező null értékű, ha a példány nincs befejezett állapotban.
createdTime karakterlánc A példány létrehozásának időpontja. ISO 8601 kiterjesztett jelölést használ.
lastUpdatedTime karakterlánc A példány utolsó megőrzésének időpontja. ISO 8601 kiterjesztett jelölést használ.
historyEvents JSON A vezénylés végrehajtási előzményeit tartalmazó JSON-tömb. Ez a mező null, hacsak a lekérdezési sztring showHistory paramétere nincs beállítva true.

Íme egy példa válasz hasznos adataira, beleértve a vezénylés végrehajtási előzményeit és a tevékenységkimeneteket (olvashatóságra formázva):

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

A HTTP 202-válasz tartalmaz egy Hely válaszfejlécet is, amely ugyanarra az URL-címre hivatkozik, mint a statusQueryGetUri korábban említett mező.

Az összes példány állapotának lekérése

Egyszerre több vezénylési példány állapotát is lekérdezi. Az eredményeket állapot, létrehozási idő és példányazonosító előtag alapján szűrheti. Ezzel a művelettel figyelheti az összes aktív vezénylést, vagy megkeresheti az adott példányokat.

kérelem

Functions runtime 2.x (ajánlott):

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}

Functions runtime 1.x (örökölt):

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}

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
showInput Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van falseállítva, a függvény bemenete nem szerepel a válasz hasznos adatai között.
showHistoryOutput Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van trueállítva, tartalmazza a függvénykimeneteket a vezénylés végrehajtási előzményeiben.
createdTimeFrom Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri az adott ISO8601 időbélyegen vagy után létrehozott visszaadott példányok listáját.
createdTimeTo Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri az adott ISO8601 időbélyegen vagy előtt létrehozott visszaadott példányok listáját.
runtimeStatus Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, a visszaadott példányok listáját a futtatási állapotuk alapján szűri. A lehetséges futtatókörnyezeti állapotértékek listájának megtekintéséhez tekintse meg a Lekérdezéspéldányok című cikket.
instanceIdPrefix Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, a visszaadott példányok listáját úgy szűri, hogy csak azokat a példányokat tartalmazza, amelyek példányazonosítója a megadott előtag-sztringgel kezdődik. A bővítmény 2.7.2-es verziójától kezdve érhető el.
top Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, korlátozza a lekérdezés által visszaadott példányok számát.

Response

Íme egy példa a válasz hasznos adataira, beleértve az orkesztációs állapotát (az olvashatóság érdekében formázva):

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

Note

Ez a művelet Azure Storage I/O szempontjából költséges lehet, ha a Azure Storage szolgáltatót használja és a Példányok táblában számos sor található. A Példányok tábláról további információt a Azure Storage szolgáltató dokumentációjában talál.

Ha további eredmények léteznek, a válaszfejléc egy folytatási tokent ad vissza. A fejléc neve x-ms-continuation-token.

Caution

A lekérdezés eredménye kevesebb elemet adhat vissza, mint a megadott topkorlát. Ha eredményeket kap, mindig ellenőrizze, hogy van-e folytatási jogkivonat.

Ha a folytatási jogkivonat értékét a következő kérelemfejlécben állítja be, a következő találatoldalt is lekérheti. A kérelem fejlécének neve is x-ms-continuation-token.

Egyetlen példány előzményeinek törlése

Törli egy adott orchestrációs példány előzményeit és kapcsolódó összetevőit. Ez a művelet felszabadítja a tárolási erőforrásokat, és nem vonható vissza.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.

Response

A következő HTTP-állapotkódértékek adhatók vissza.

  • HTTP 200 (OK): A példányelőzmények kiürítése sikeresen megtörtént.
  • HTTP 404 (Nem található): A megadott példány nem létezik.

A HTTP 200-es eset választerhelése egy JSON objektum, amely a következő mezővel rendelkezik:

Field Adattípus Description
instancesDeleted egész szám A törölt példányok száma. Az egyetlen példány esetében ennek az értéknek mindig a következőnek kell lennie 1: .

Íme egy példa válasz payload (olvashatóságra formázva):

{
    "instancesDeleted": 1
}

Több példány előzményének törlése

Egyszerre több példány előzményeit és összetevőit törli, állapot, létrehozási idő vagy példányazonosító előtag alapján szűrve. Ezzel tömegesen törölheti a régi példányokat, és kezelheti a tárolási költségeket.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
createdTimeFrom Lekérdezési karakterlánc Szűri azoknak a kiürített példányoknak a listáját, amelyeket az adott ISO8601 időbélyegen vagy után hoztak létre.
createdTimeTo Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri azoknak a kiürített példányoknak a listáját, amelyeket az adott ISO8601 időbélyegen vagy előtt hoztak létre.
runtimeStatus Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, a futtatási állapotuk alapján szűri a törölt példányok listáját. A lehetséges futtatókörnyezeti állapotértékek listájának megtekintéséhez tekintse meg a Lekérdezéspéldányok című cikket.

Note

Ez a művelet Azure Storage I/O-érték szempontjából költséges lehet, ha a Azure Storage szolgáltatót használja és a Példányok vagy előzmények táblában számos sor található. További információ ezekről a táblákról: A Durable Functions (Azure Functions).

Response

A következő HTTP-állapotkódértékek adhatók vissza.

  • HTTP 200 (OK): A példányelőzmények kiürítése sikeresen megtörtént.
  • HTTP 404 (Nem található): Nem található olyan példány, amely megfelel a szűrőkifejezésnek.

A HTTP 200-es eset választerhelése egy JSON objektum, amely a következő mezővel rendelkezik:

Field Adattípus Description
instancesDeleted egész szám A törölt példányok száma.

Íme egy példa válasz payload (olvashatóságra formázva):

{
    "instancesDeleted": 250
}

Esemény emelése

Eseményértesítési üzenetet küld egy futó orchestrációs példánynak. A vezénylésnek név WaitForExternalEvent alapján kell várnia erre az eseményre, vagy wait_for_external_event.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
eventName URL Annak az eseménynek a neve, amelyen a cél orchestrációs példány várakozik.
{content} Tartalom kérése A JSON-formátumú esemény hasznos adatai.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): A létrehozott esemény feldolgozásra lett elfogadva.
  • HTTP 400 (Hibás kérés):: A kérelem tartalma nem volt típusú application/json , vagy nem volt érvényes JSON.
  • HTTP 404 (Nem található): A megadott példány nem található.
  • HTTP 410 (Gone): A megadott példány befejeződött vagy meghiúsult, és nem tudja feldolgozni a létrehozott eseményeket.

Íme egy példakérés, amely elküldi a JSON-sztringet "incr" egy olyan példánynak, amely egy esemény nevesített műveletre vár:

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

"incr"

Az API válaszai nem tartalmaznak tartalmat.

Példány leállítása

Leállítja a futó orchestrációs példányt.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és az alábbi egyedi paraméter.

Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
reason Lekérdezési karakterlánc Opcionális. Az orkesztrációs példány megszüntetésének oka.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): A leállítási kérelem feldolgozásra lett elfogadva.
  • HTTP 404 (Nem található): A megadott példány nem található.
  • HTTP 410 (Gone): A megadott példány befejeződött vagy meghiúsult.

Íme egy példakérés, amely leállítja a futó példányt, és megadja a hiba okát:

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

Az API válaszai nem tartalmaznak tartalmat.

Példány felfüggesztése

Szüneteltet egy futó vezénylési példányt anélkül, hogy megszüntette volna. A példány később a művelettel resume folytatható.

kérelem

A Functions-futtatókörnyezet 2.x-es verziójában a kérés a következőképpen van formázva (az egyértelműség érdekében több sor jelenik meg):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
reason Lekérdezési karakterlánc Opcionális. A vezénylési példány felfüggesztésének oka.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): A felfüggesztési kérelem feldolgozásra lett elfogadva. A rendszer nem ad vissza választörzset.
  • HTTP 404 (Nem található): A megadott példány nem található.
  • HTTP 410 (Gone): A megadott példány befejeződött, meghiúsult vagy leállt, és nem lehet felfüggeszteni.

Ellenőrzés: A HTTP 202 fogadása után lekérdezheti a példány állapotát GET /runtime/webhooks/durabletask/instances/{instanceId} annak ellenőrzéséhez, hogy runtimeStatus"Suspended"megváltozott-e.

Példány folytatása

Egy korábban felfüggesztett vezénylési példány végrehajtását folytatja.

kérelem

A Functions-futtatókörnyezet 2.x-es verziójában a kérés a következőképpen van formázva (az egyértelműség érdekében több sor jelenik meg):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
reason Lekérdezési karakterlánc Opcionális. A vezénylési példány újraindításának oka.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): Az önéletrajz-kérelem feldolgozásra lett elfogadva. A rendszer nem ad vissza választörzset.
  • HTTP 404 (Nem található): A megadott példány nem található.
  • HTTP 410 (Gone): A megadott példány befejeződött, meghiúsult vagy leállt, és nem folytatható.

Ellenőrzés: A HTTP 202 fogadása után lekérdezheti a példány állapotát GET /runtime/webhooks/durabletask/instances/{instanceId} annak ellenőrzéséhez, hogy runtimeStatus"Running"megváltozott-e.

Példány visszatekerése (előzetes verzió)

Visszaállít egy sikertelen vezénylési példányt futó állapotba a legutóbbi sikertelen műveletek újbóli elvégzése által. Ez a funkció manuális beavatkozás nélkül teszi lehetővé az átmeneti hibák utáni helyreállítást.

kérelem

Functions runtime 2.x (ajánlott):

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

Functions runtime 1.x (örökölt):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és az alábbi egyedi paraméter.

Field Paraméter típusa Description
instanceId URL A vezénylési példány azonosítója.
reason Lekérdezési karakterlánc Opcionális. A vezénylési példány visszatekerésének oka.

Response

Több lehetséges állapotkódérték is visszaadható.

  • HTTP 202 (Elfogadva): A visszatekerési kérelem feldolgozásra lett elfogadva.
  • HTTP 404 (Nem található): A megadott példány nem található.
  • HTTP 410 (Gone): A megadott példány befejeződött vagy leállt.

Íme egy példakérés, amely visszateker egy sikertelen példányt, és megadja a javítás okát:

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

Az API válaszai nem tartalmaznak tartalmat.

Jel entitás

Egyirányú műveletüzenetet küld egy tartós entitásnak. Ha az entitás nem létezik, automatikusan létrejön. Az entitásműveleteket a rendszer szekvenciálisan és tartósan feldolgozza.

Note

A Tartós entitások a Durable Functions 2.0-tól érhetők el.

kérelem

A HTTP-kérés a következőképpen van formázva (az egyértelműség érdekében több sor jelenik meg):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
entityName URL Az entitás neve (típusa).
entityKey URL Az entitás kulcsa (egyedi azonosítója).
op Lekérdezési karakterlánc Opcionális. A meghívandó felhasználó által megadott művelet neve.
{content} Tartalom kérése A JSON-formátumú esemény hasznos adatai.

Íme egy példakérés, amely egy felhasználó által definiált "Hozzáadás" üzenetet küld egy Counter nevű stepsentitásnak. Az üzenetben lévő tartalom az érték 5. Ha az entitás még nem létezik, ez a kérés létrehozza:

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

5

Note

Alapértelmezés szerint a .NET osztály-alapú entitások esetében a értékének megadásával törli az entitás állapotát. Ha az entitás egy elnevezett deleteműveletet határoz meg, a rendszer ehelyett a felhasználó által megadott műveletet hívja meg.

Response

Ez a művelet több lehetséges választ is ad:

  • HTTP 202 (Elfogadva): A jelművelet aszinkron feldolgozásra lett elfogadva.
  • HTTP 400 (Hibás kérés):: A kérelem tartalma nem típusú application/jsonvolt, nem volt érvényes JSON, vagy érvénytelen entityKey érték volt.
  • HTTP 404 (Nem található): A megadott entityName nem található.

A sikeres HTTP-kérések nem tartalmaznak tartalmat a válaszban. A sikertelen HTTP-kérések JSON-formátumú hibainformációkat tartalmazhatnak a válasz tartalmában.

Entitás lekérése

Lekéri a megadott entitás állapotát.

kérelem

A HTTP-kérés a következőképpen van formázva (az egyértelműség érdekében több sor jelenik meg):

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

Response

Ez a művelet két lehetséges választ ad:

  • HTTP 200 (OK): A megadott entitás létezik.
  • HTTP 404 (Nem található): A megadott entitás nem található.

A sikeres válasz tartalma az entitás JSON-szerializált állapotát tartalmazza.

Example

Egy meglévő Counter entitás állapotának lekérése a következő néven steps:

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

Ha az Counter entitás egyszerűen tartalmazott egy mezőben mentett currentValue lépések számát, a válasz tartalma a következőhöz hasonlóan nézhet ki (olvashatóságra formázva):

{
    "currentValue": 5
}

Entitások listázása

Több entitást is lekérdezhet az entitás neve vagy az utolsó művelet dátuma alapján.

kérelem

A HTTP-kérés a következőképpen van formázva (az egyértelműség érdekében több sor jelenik meg):

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

Az API kérésparaméterei közé tartozik a korábban említett alapértelmezett készlet és a következő egyedi paraméterek:

Field Paraméter típusa Description
entityName URL Opcionális. Ha meg van adva, a visszaadott entitások listáját az entitás neve alapján szűri (kis- és nagybetűkre nem érzékeny).
fetchState Lekérdezési karakterlánc Nem kötelező paraméter. Ha be van trueállítva, az entitás állapota szerepel a válasz hasznos adatai között.
lastOperationTimeFrom Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri azon visszaadott entitások listáját, amelyek a megadott ISO8601 időbélyeg után dolgozták fel a műveletet.
lastOperationTimeTo Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, szűri azoknak a visszaadott entitásoknak a listáját, amelyek a megadott ISO8601 időbélyeg előtt dolgozták fel a műveleteket.
top Lekérdezési karakterlánc Nem kötelező paraméter. Ha meg van adva, korlátozza a lekérdezés által visszaadott entitások számát.

Response

A sikeres HTTP 200-válasz egy JSON-szerializált entitástömböt és opcionálisan az egyes entitások állapotát tartalmazza.

Alapértelmezés szerint a művelet a lekérdezési feltételeknek megfelelő első 100 entitást adja vissza. A hívó megadhat egy lekérdezési sztring paraméterértéket top , amely eltérő maximális számú eredményt ad vissza. Ha vannak további eredmények a visszaadott eredményeken túl, a válaszfejlécben egy folytatási token is megjelenik. A fejléc neve x-ms-continuation-token.

Ha a folytatási jogkivonat értékét a következő kérelemfejlécben állítja be, a következő találatoldalt is lekérheti. A kérelem fejlécének neve is x-ms-continuation-token.

Példa – az összes entitás listázása

A tevékenységközpont összes entitásának listázása:

GET /runtime/webhooks/durabletask/entities

A válasz JSON-ja a következőhöz hasonló lehet (olvashatóságra formázva):

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

Példa – az entitások listájának szűrése

Az első két counter entitás listázása és állapotuk lekérése:

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

A válasz JSON-ja a következőhöz hasonló lehet (olvashatóságra formázva):

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

Teljes munkafolyamat-példa

Ez a példa egy teljes vezénylési életciklust curl mutat be parancsokkal. Használhatja a Postmant, a Thunder-ügyfelet vagy bármely HTTP-ügyfelet is.

1. Vezénylés indítása

Új ProcessOrder vezénylés indítása bemeneti adatokkal:

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
  }'

Válasz (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"
}

Mentse a példányazonosítót: abc123def456

2. Állapot lekérdezése

Vezénylési folyamat ellenőrzése:

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

Válasz futás közben (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"
}

Válasz befejeződött (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. Külső esemény küldése (nem kötelező)

Ha a vezénylés jóváhagyásra vár, küldjön egy jóváhagyási eseményt:

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

Válasz: HTTP 202 (Elfogadva)

4. Előzmények törlése (nem kötelező)

A vezénylés befejezése után törölje az előzményeit:

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

Válasz (HTTP 200):

{
  "instancesDeleted": 1
}

Következő lépések

Megtudhatja, hogyan monitorozhat tartós függvényeket az Application Insights használatával

  • Last updated on