Informazioni di riferimento sulle API HTTP

  • Articolo

L'estensione Durable Functions espone un set di API HTTP predefinite che possono essere usate per eseguire attività di gestione su orchestrazioni, entità e hub attività. Queste API HTTP sono webhook di estendibilità autorizzati dall'host Funzioni di Azure ma gestiti direttamente dall'estensione Durable Functions.

L'URL di base per le API menzionate in questo articolo corrisponde all'URL di base per l'app per le funzioni. Quando si sviluppa in locale usando Funzioni di Azure Core Tools, l'URL di base è in http://localhost:7071genere . Nel servizio ospitato Funzioni di Azure, l'URL di base è in https://{appName}.azurewebsites.netgenere . I nomi host personalizzati sono supportati anche se configurati nell'app servizio app.

Tutte le API HTTP implementate dall'estensione richiedono i parametri seguenti. Il tipo di dati di tutti i parametri è string.

Parametro Tipo di parametro Descrizione
taskHub Stringa di query Nome dell'hub attività. Se non specificato, viene usato il nome dell'hub attività dell'app per le funzioni corrente.
connection Stringa di query Nome dell'impostazione dell'app di connessione per il provider di archiviazione back-end. Se non specificato, viene usata la configurazione di connessione predefinita per l'app per le funzioni.
systemKey Stringa di query Chiave di autorizzazione necessaria per richiamare l'API.

systemKeyè una chiave di autorizzazione generata automaticamente dall'host Funzioni di Azure. Concede in particolare l'accesso alle API di estensione Durable Task e può essere gestito allo stesso modo di altre chiavi di accesso Funzioni di Azure. È possibile generare URL che contengono i valori corretti taskHubdella stringa di connectionquery , e systemKey usando le API di associazione client di orchestrazione, ad esempio le CreateCheckStatusResponse API e CreateHttpManagementPayload in .NET, le createCheckStatusResponse API e createHttpManagementPayload in JavaScript e così via.

Le prossime sezioni illustrano le specifiche API HTTP supportate dall'estensione e offrono esempi su come possono essere usate.

Avviare l'orchestrazione

Avvia l'esecuzione di una nuova istanza della funzione dell'agente di orchestrazione specificata.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
functionName URL Nome della funzione dell'agente di orchestrazione da avviare.
instanceId URL Parametro facoltativo. ID dell'istanza di orchestrazione. Se non specificato, la funzione dell'agente di orchestrazione inizierà con un ID istanza casuale.
{content} Richiedere il contenuto Facoltativo. Input della funzione dell'agente di orchestrazione in formato JSON.

Response

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (Accettato): la funzione dell'agente di orchestrazione specificata è stata pianificata per l'avvio dell'esecuzione. L'intestazione Location della risposta contiene un URL per il polling dello stato di orchestrazione.
  • HTTP 400 (richiesta non valida): la funzione dell'agente di orchestrazione specificata non esiste, l'ID istanza specificato non è valido o il contenuto della richiesta non è valido JSON.

Di seguito è riportata una richiesta di esempio che avvia una RestartVMs funzione dell'agente di orchestrazione e include il payload dell'oggetto JSON:

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

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

Il payload della risposta per i case HTTP 202 è un oggetto JSON con i campi seguenti:

Campo Descrizione
id ID dell'istanza di orchestrazione.
statusQueryGetUri URL di stato dell'istanza di orchestrazione.
sendEventPostUri URL di generazione evento dell'istanza di orchestrazione.
terminatePostUri URL di terminazione dell'istanza di orchestrazione.
purgeHistoryDeleteUri URL di "ripulitura della cronologia" dell'istanza di orchestrazione.
rewindPostUri (anteprima) URL di riavvolgimento dell'istanza di orchestrazione.
suspendPostUri URL "suspend" dell'istanza di orchestrazione.
resumePostUri URL "resume" dell'istanza di orchestrazione.

Il tipo di dati di tutti i campi è string.

Di seguito è riportato un payload di risposta di esempio per un'istanza di orchestrazione con abc123 come ID (formattato per la leggibilità):

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

La risposta HTTP deve essere compatibile con il modello consumer di polling. Include anche le intestazioni di risposta rilevanti seguenti:

  • Percorso: URL dell'endpoint di stato. Questo URL contiene lo stesso valore del statusQueryGetUri campo.
  • Retry-After: numero di secondi di attesa tra le operazioni di polling. Il valore predefinito è 10.

Per altre informazioni sul modello di polling HTTP asincrono, vedere la documentazione relativa al rilevamento delle operazioni asincrone HTTP.

Get instance status (Ottieni stato istanza)

Ottiene lo stato di un'istanza di orchestrazione specificata.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
showInput Stringa di query Parametro facoltativo. Se impostato su false, l'input della funzione non verrà incluso nel payload della risposta.
showHistory Stringa di query Parametro facoltativo. Se impostato su true, la cronologia di esecuzione dell'orchestrazione verrà inclusa nel payload della risposta.
showHistoryOutput Stringa di query Parametro facoltativo. Se impostato su true, gli output della funzione verranno inclusi nella cronologia di esecuzione dell'orchestrazione.
createdTimeFrom Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite create in corrispondenza o dopo l'ISO8601 timestamp specificato.
createdTimeTo Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite create in corrispondenza o prima dell'ISO8601 timestamp specificato.
runtimeStatus Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite in base allo stato del runtime. Per visualizzare l'elenco dei possibili valori di stato di runtime, vedere l'articolo Querying instances (Istanze di query).
returnInternalServerErrorOnFailure Stringa di query Parametro facoltativo. Se impostato su true, questa API restituirà una risposta HTTP 500 anziché 200 se l'istanza è in uno stato di errore. Questo parametro è destinato agli scenari di polling dello stato automatizzato.

Response

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 200 (OK): l'istanza specificata si trova in uno stato completato o non riuscito.
  • HTTP 202 (Accettata ): l'istanza specificata è in esecuzione.
  • HTTP 400 (Richiesta non valida): l'istanza specificata ha avuto esito negativo o è stata terminata.
  • HTTP 404 (Non trovata): l'istanza specificata non esiste o l'esecuzione non è iniziata.
  • HTTP 500 (errore interno del server): restituito solo quando returnInternalServerErrorOnFailure è impostato su true e l'istanza specificata non è riuscita con un'eccezione non gestita.

Il payload di risposta per i casi HTTP 200 e HTTP 202 è un oggetto JSON con i campi seguenti:

Campo Tipo di dati Descrizione
runtimeStatus string Stato di runtime dell'istanza. I valori includono Running, Pending, Failed, Canceled, Terminate, Completed, Suspended.
input JSON Dati JSON usati per inizializzare l'istanza. Questo campo è null quando il parametro della stringa di query showInput è impostato su false.
customStatus JSON I dati JSON usati per lo stato dell'orchestrazione personalizzato. Se non impostato, il campo è null.
output JSON Output JSON dell'istanza. Questo campo è null se l'istanza non è in stato completato.
createdTime string Data e ora di creazione dell'istanza. Usa la notazione estesa ISO 8601.
lastUpdatedTime string Data e ora dell'ultimo stato persistente dell'istanza. Usa la notazione estesa ISO 8601.
historyEvents JSON Matrice JSON contenente la cronologia di esecuzione dell'orchestrazione. Questo campo è null a meno che il parametro della stringa di query showHistory non sia impostato su true.

Ecco un payload di risposta di esempio che include la cronologia di esecuzione dell'orchestrazione e gli output delle attività (formattato per migliorarne la leggibilità):

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

La risposta HTTP 202 include anche un'intestazione di risposta Location che referenzia lo stesso URL del campo statusQueryGetUri citato in precedenza.

Ottenere lo stato di tutte le istanze

È anche possibile eseguire una query sullo stato di tutte le istanze rimuovendo dalla instanceId richiesta 'Ottieni stato istanza'. In questo caso, i parametri di base sono uguali a "Ottenere lo stato dell'istanza". Sono supportati anche i parametri della stringa di query per il filtro.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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}

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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}

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
showInput Stringa di query Parametro facoltativo. Se impostato su false, l'input della funzione non verrà incluso nel payload della risposta.
showHistoryOutput Stringa di query Parametro facoltativo. Se impostato su true, gli output della funzione verranno inclusi nella cronologia di esecuzione dell'orchestrazione.
createdTimeFrom Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite create in corrispondenza o dopo l'ISO8601 timestamp specificato.
createdTimeTo Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite create in corrispondenza o prima dell'ISO8601 timestamp specificato.
runtimeStatus Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite in base allo stato del runtime. Per visualizzare l'elenco dei possibili valori di stato di runtime, vedere l'articolo Querying instances (Istanze di query).
instanceIdPrefix Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle istanze restituite in modo da includere solo le istanze il cui ID istanza inizia con la stringa di prefisso specificata. Disponibile a partire dalla versione 2.7.2 dell'estensione.
top Stringa di query Parametro facoltativo. Se specificato, limita il numero di istanze restituite dalla query.

Response

Di seguito è riportato un esempio di payload di risposta, compreso lo stato dell'orchestrazione (formattato per migliorare la leggibilità):

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

Nota

Questa operazione può essere molto costosa in termini di I/O Archiviazione di Azure se si usa il provider di Archiviazione di Azure predefinito e se nella tabella Istanze sono presenti molte righe. Per altre informazioni sulla tabella dell'istanza, vedere la documentazione del provider di Archiviazione di Azure.

Se esistono più risultati, nell'intestazione della risposta viene restituito un token di continuazione. Il nome dell’intestazione è x-ms-continuation-token.

Attenzione

Il risultato della query può restituire un numero inferiore di elementi rispetto al limite specificato da top. Quando si ricevono risultati, è quindi consigliabile verificare sempre se è presente un token di continuazione.

Se si imposta il valore del token di continuazione nell'intestazione della richiesta successiva, è possibile ottenere la pagina successiva dei risultati. Questo nome dell'intestazione della richiesta è anche x-ms-continuation-token.

Ripulire la cronologia delle singole istanze

Elimina la cronologia e gli artefatti correlati per un'istanza di orchestrazione specificata.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.

Response

È possibile restituire i valori del codice di stato HTTP seguenti.

  • HTTP 200 (OK): la cronologia delle istanze è stata eliminata correttamente.
  • HTTP 404 (Non trovato): l'istanza specificata non esiste.

Il payload della risposta per il caso HTTP 200 è un oggetto JSON con il campo seguente:

Campo Tipo di dati Descrizione
instancesDeleted integer Numero di istanze eliminate. Per il caso della singola istanza, questo valore deve essere 1sempre .

Di seguito è riportato un payload di risposta di esempio (formattato per migliorare la leggibilità):

{
    "instancesDeleted": 1
}

Eliminare più cronologie di istanze

È anche possibile eliminare la cronologia e gli artefatti correlati per più istanze all'interno di un hub attività rimuovendo la {instanceId} richiesta "Elimina cronologia istanza singola". Per eliminare in modo selettivo la cronologia delle istanze, usare gli stessi filtri descritti nella richiesta "Ottieni stato tutte le istanze".

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
createdTimeFrom Stringa di query Filtra l'elenco delle istanze eliminate create in corrispondenza o dopo il timestamp specificato ISO8601.
createdTimeTo Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco di istanze eliminate create in corrispondenza o prima del timestamp ISO8601 specificato.
runtimeStatus Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco di istanze eliminate in base al relativo stato di runtime. Per visualizzare l'elenco dei possibili valori di stato di runtime, vedere l'articolo Querying instances (Istanze di query).

Nota

Questa operazione può essere molto costosa in termini di I/O Archiviazione di Azure se si usa il provider di Archiviazione di Azure predefinito e se sono presenti molte righe nelle tabelle Istanze e/o Cronologia. Per altre informazioni su queste tabelle, vedere la documentazione prestazioni e scalabilità in Durable Functions (Funzioni di Azure).

Response

È possibile restituire i valori del codice di stato HTTP seguenti.

  • HTTP 200 (OK): la cronologia delle istanze è stata eliminata correttamente.
  • HTTP 404 (Non trovato): non sono state trovate istanze che corrispondono all'espressione di filtro.

Il payload della risposta per il caso HTTP 200 è un oggetto JSON con il campo seguente:

Campo Tipo di dati Descrizione
instancesDeleted integer Numero di istanze eliminate.

Di seguito è riportato un payload di risposta di esempio (formattato per migliorare la leggibilità):

{
    "instancesDeleted": 250
}

Raise event (Genera evento)

Invia un messaggio di notifica evento per un'istanza di orchestrazione in esecuzione.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
eventName URL Nome dell'evento atteso dall'istanza di orchestrazione di destinazione.
{content} Richiedere il contenuto Payload dell'evento in formato JSON.

Response

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (Accettata): l'evento generato è stato accettato per l'elaborazione.
  • HTTP 400 (Richiesta non valida): il contenuto della richiesta non è di tipo application/json o non è un oggetto JSON valido.
  • HTTP 404 (Non trovata): l'istanza specificata non è stata trovata.
  • HTTP 410 (Non disponibile): l'istanza specificata è stata completata o ha avuto esito negativo e non può elaborare gli eventi generati.

Ecco una richiesta di esempio che invia la stringa JSON "incr" a un'istanza in attesa di un evento denominato operation:

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

"incr"

Nelle risposte per questa API non è presente contenuto.

Arresta istanza

Termina un'istanza di orchestrazione in esecuzione.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti.

Campo Tipo di parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
reason Stringa di query Facoltativo. Motivo dell'interruzione dell'istanza di orchestrazione.

Response

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (Accettata): la richiesta di interruzione è stata accettata per l'elaborazione.
  • HTTP 404 (Non trovata): l'istanza specificata non è stata trovata.
  • HTTP 410 (Non disponibile): l'istanza specificata è stata completata o ha avuto esito negativo.

Ecco un esempio di richiesta che termina un'istanza in esecuzione e specifica il motivo buggy (con errori):

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

Nelle risposte per questa API non è presente contenuto.

Sospendi istanza

Sospende un'istanza di orchestrazione in esecuzione.

Richiedi

Nella versione 2.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo di parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
reason Stringa di query Facoltativo. Motivo della sospensione dell'istanza di orchestrazione.

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (accettato): la richiesta di sospensione è stata accettata per l'elaborazione.
  • HTTP 404 (Non trovata): l'istanza specificata non è stata trovata.
  • HTTP 410 (Gone): l'istanza specificata è stata completata, non riuscita o terminata.

Nelle risposte per questa API non è presente contenuto.

Riprendere l'istanza

Riprende un'istanza di orchestrazione sospesa.

Richiedi

Nella versione 2.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo di parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
reason Stringa di query Facoltativo. Motivo della ripresa dell'istanza di orchestrazione.

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (accettato): la richiesta di ripresa è stata accettata per l'elaborazione.
  • HTTP 404 (Non trovata): l'istanza specificata non è stata trovata.
  • HTTP 410 (Gone): l'istanza specificata è stata completata, non riuscita o terminata.

Nelle risposte per questa API non è presente contenuto.

Ripristinare un'istanza (anteprima)

Ripristina lo stato in corso di esecuzione di un'istanza di orchestrazione non riuscita riproducendo le operazioni non riuscite più recenti.

Richiedi

Per la versione 1.x del runtime di Funzioni, la richiesta viene formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Nella versione 2.x del runtime di Funzioni, il formato URL ha tutti gli stessi parametri, ma con un prefisso leggermente diverso:

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti.

Campo Tipo di parametro Descrizione
instanceId URL ID dell'istanza di orchestrazione.
reason Stringa di query Facoltativo. Motivo del ripristino dell'istanza di orchestrazione.

Response

Possono essere restituiti diversi valori di codice di stato.

  • HTTP 202 (Accettata): la richiesta di ripristino è stata accettata per l'elaborazione.
  • HTTP 404 (Non trovata): l'istanza specificata non è stata trovata.
  • HTTP 410 (Non disponibile): l'istanza specificata è stata completata o terminata.

Di seguito è riportato un esempio di richiesta che ripristina un'istanza non riuscita e specifica il motivo fixed (corretto):

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

Nelle risposte per questa API non è presente contenuto.

Entità Signal

Invia un messaggio di operazione unidirezionale a un'entità durevole. Se l'entità non esiste, verrà creata automaticamente.

Nota

Le entità durevoli sono disponibili a partire da Durable Functions 2.0.

Richiedi

La richiesta HTTP è formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
entityName URL Nome (tipo) dell'entità.
entityKey URL Chiave (ID univoco) dell'entità.
op Stringa di query Facoltativo. Nome dell'operazione definita dall'utente da richiamare.
{content} Richiedere il contenuto Payload dell'evento in formato JSON.

Di seguito è riportato un esempio di richiesta che invia un messaggio "Add" definito dall'utente a un'entità Counter denominata steps. Il contenuto del messaggio è il valore 5. Se l'entità non esiste già, verrà creata da questa richiesta:

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

5

Nota

Per impostazione predefinita con le entità basate su classi in .NET, specificando il op valore di delete eliminerà lo stato di un'entità. Se l'entità definisce un'operazione denominata delete, tuttavia, tale operazione definita dall'utente verrà richiamata.

Response

Questa operazione presenta diverse risposte possibili:

  • HTTP 202 (accettato): l'operazione di segnale è stata accettata per l'elaborazione asincrona.
  • HTTP 400 (richiesta non valida): il contenuto della richiesta non era di tipo application/json, non era valido JSON o aveva un valore non valido entityKey .
  • HTTP 404 (Non trovato): l'oggetto specificato entityName non è stato trovato.

Una richiesta HTTP riuscita non contiene contenuto nella risposta. Una richiesta HTTP non riuscita può contenere informazioni sull'errore in formato JSON nel contenuto della risposta.

Ottenere un'entità

Ottiene lo stato dell'entità specificata.

Richiedi

La richiesta HTTP è formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

Response

Questa operazione ha due possibili risposte:

  • HTTP 200 (OK):l'entità specificata esiste.
  • HTTP 404 (Non trovato): l'entità specificata non è stata trovata.

Una risposta con esito positivo contiene lo stato serializzato JSON dell'entità come contenuto.

Esempio

La richiesta HTTP di esempio seguente ottiene lo stato di un'entità esistente Counter denominata steps:

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

Se l'entità Counter contiene semplicemente una serie di passaggi salvati in un currentValue campo, il contenuto della risposta potrebbe essere simile al seguente (formattato per la leggibilità):

{
    "currentValue": 5
}

Elencare le entità

È possibile eseguire una query per più entità in base al nome dell'entità o alla data dell'ultima operazione.

Richiedi

La richiesta HTTP è formattata come segue (vengono visualizzate più righe per maggiore chiarezza):

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

I parametri della richiesta per questa API includono il set predefinito indicato in precedenza, nonché i parametri univoci seguenti:

Campo Tipo parametro Descrizione
entityName URL Facoltativo. Se specificato, filtra l'elenco delle entità restituite in base al nome dell'entità (senza distinzione tra maiuscole e minuscole).
fetchState Stringa di query Parametro facoltativo. Se impostato su true, lo stato dell'entità verrà incluso nel payload della risposta.
lastOperationTimeFrom Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle entità restituite che hanno elaborato le operazioni dopo il timestamp di ISO8601 specificato.
lastOperationTimeTo Stringa di query Parametro facoltativo. Se specificato, filtra l'elenco delle entità restituite che hanno elaborato le operazioni prima del timestamp ISO8601 specificato.
top Stringa di query Parametro facoltativo. Se specificato, limita il numero di entità restituite dalla query.

Response

Una risposta HTTP 200 con esito positivo contiene una matrice serializzata JSON di entità e, facoltativamente, lo stato di ogni entità.

Per impostazione predefinita, l'operazione restituisce le prime 100 entità che soddisfano i criteri di query. Il chiamante può specificare un valore di parametro della stringa di query per restituire top un numero massimo di risultati diverso. Se esistono più risultati oltre a quanto restituito, viene restituito anche un token di continuazione nell'intestazione della risposta. Il nome dell’intestazione è x-ms-continuation-token.

Se si imposta il valore del token di continuazione nell'intestazione della richiesta successiva, è possibile ottenere la pagina successiva dei risultati. Questo nome dell'intestazione della richiesta è anche x-ms-continuation-token.

Esempio: elencare tutte le entità

La richiesta HTTP di esempio seguente elenca tutte le entità nell'hub attività:

GET /runtime/webhooks/durabletask/entities

Il codice JSON della risposta può essere simile al seguente (formattato per la leggibilità):

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

Esempio: filtro dell'elenco di entità

L'esempio di richiesta HTTP seguente elenca solo le prime due entità di tipo counter e recupera anche il relativo stato:

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

Il codice JSON della risposta può essere simile al seguente (formattato per la leggibilità):

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

Passaggi successivi

Informazioni su come usare Application Insights per monitorare le funzioni durevoli