Referencia a las API de HTTP

  • Artículo

La extensión Durable Functions expone un conjunto de API de HTTP integradas que se pueden usar para realizar tareas de administración en orquestaciones, entidades y centrales de tareas. Estas API de HTTP son webhooks de extensibilidad que están autorizados por el host de Azure Functions pero que se administran directamente mediante la extensión Durable Functions.

La dirección URL base de las API mencionadas en este artículo es la misma que la dirección URL base de la aplicación de funciones. Al desarrollar localmente con Azure Functions Core Tools, normalmente la URL base es http://localhost:7071. En el servicio hospedado de Azure Functions, la dirección URL base suele ser https://{appName}.azurewebsites.net. Los nombres de host personalizados también se admiten si están configurados en la aplicación de App Service.

Todas las API de HTTP que implementa la extensión requieren los siguientes parámetros. El tipo de datos de todos los parámetros es string.

Parámetro Tipo de parámetro Descripción
taskHub Cadena de consulta Nombre de la central de tareas. Si no se especifica, se toma el nombre de la central de tareas de la aplicación de función actual.
connection Cadena de consulta Nombre de la configuración de aplicación de conexión para el proveedor de almacenamiento de back-end. Si no se especifica, se toma el de la configuración de conexión predeterminada de la aplicación de funciones.
systemKey Cadena de consulta Clave de autorización necesaria para invocar la API.

systemKey es una clave de autorización que el host de Azure Functions genera automáticamente. En concreto, concede acceso a las API de la extensión Durable Tasks y se administra igual que las demás claves de acceso de Azure Functions. Puede generar direcciones URL que contengan los valores de cadena de consulta taskHub, connection y systemKey correctos mediante API de enlace de clientes de orquestación, como las API CreateCheckStatusResponse y CreateHttpManagementPayload en .NET o las API createCheckStatusResponse y createHttpManagementPayload en JavaScript, etc.

Las siguientes secciones tratan las API de HTTP específicas que admite la extensión y ofrecen ejemplos de uso.

Inicio de la orquestación

Inicia la ejecución de una nueva instancia de la función de orquestador especificada.

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
functionName URL El nombre de la función de orquestador que iniciar.
instanceId URL Parámetro opcional. Identificador de la instancia de orquestación. Si no se especifica, la función de orquestador se iniciará con un identificador de instancia aleatorio.
{content} Contenido de la solicitud Opcional. La entrada de la función de orquestador en formato JSON.

Response

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (aceptado) : la función de orquestador especificada estaba programada para empezar a ejecutarse. El encabezado de respuesta Location contiene una dirección URL para sondear el estado de la orquestación.
  • HTTP 400 (solicitud incorrecta) : la función de orquestador especificada no existe, el identificador de instancia especificado no era válido o el contenido de la solicitud no era JSON válido.

A continuación, se muestra una solicitud de ejemplo que inicia una función de orquestador RestartVMs e incluye la carga del objeto JSON:

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

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

La carga de respuesta para los casos HTTP 202 es un objeto JSON con los siguientes campos:

Campo Descripción
id Identificador de la instancia de orquestación.
statusQueryGetUri Dirección URL del estado de la instancia de orquestación.
sendEventPostUri Dirección URL de generación del evento de la instancia de orquestación.
terminatePostUri Dirección URL de finalización de la instancia de orquestación.
purgeHistoryDeleteUri La dirección URL del "historial de purga" de la instancia de orquestación.
rewindPostUri (versión preliminar) La dirección URL de "rebobinado" de la instancia de orquestación.
suspendPostUri Dirección URL de "suspender" de la instancia de orquestación.
resumePostUri Dirección URL de "reanudar"de la instancia de orquestación.

El tipo de datos de todos los campos es string.

A continuación, se muestra una carga de respuesta de ejemplo para una instancia de orquestación con abc123 como identificador (con formato para mejorar la legibilidad):

{
    "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 respuesta HTTP está diseñada para ser compatible con el patrón de consumidor de sondeo. También incluye los siguientes encabezados de respuesta significativos:

  • Ubicación: dirección URL del punto de conexión de estado. Esta dirección URL contiene el mismo valor que el campo statusQueryGetUri.
  • Retry-After: número de segundos que se va a esperar entre las operaciones de sondeo. El valor predeterminado es 10.

Para más información sobre el patrón de sondeo HTTP asincrónico, consulte la documentación de seguimiento de operaciones HTTP asincrónicas.

Obtención del estado de la instancia

Para obtener el estado de una instancia de orquestación específica:

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
showInput Cadena de consulta Parámetro opcional. Si se establece en false, la entrada de la función no se incluye en la carga de respuesta.
showHistory Cadena de consulta Parámetro opcional. Si se establece en true, el historial de ejecución de orquestación se incluirá en la carga de respuesta.
showHistoryOutput Cadena de consulta Parámetro opcional. Si se establece en true, las salidas de la función se incluyen en el historial de ejecución de la orquestación.
createdTimeFrom Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas que se crearon durante la marca de tiempo ISO8601 especificada o después de esta.
createdTimeTo Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas que se crearon durante la marca de tiempo ISO8601 especificada o antes de esta.
runtimeStatus Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas según su estado en tiempo de ejecución. Para ver la lista de valores posibles del estado en tiempo de ejecución, consulte el artículo Consulta de instancias.
returnInternalServerErrorOnFailure Cadena de consulta Parámetro opcional. Si se establece en true, esta API devolverá una respuesta HTTP 500, en lugar de HTTP 200, si la instancia esta en estado de error. Este parámetro está pensado para escenarios automatizados de sondeo de estado.

Response

Se pueden devolver varios valores de código de estado.

  • HTTP 200 (correcto) : la instancia especificada está en estado completado o de error.
  • HTTP 202 (aceptado) : la instancia especificada está en curso.
  • HTTP 400 (solicitud incorrecta) : se produjo un error en la instancia especificada o esta se ha finalizado.
  • HTTP 404 (no se encuentra) : la instancia especificada no existe o no ha empezado a ejecutarse.
  • HTTP 500 (error interno del servidor) : solo se devuelve cuando returnInternalServerErrorOnFailure está establecido en true y la instancia especificada ha generado una excepción no controlada.

La carga de respuesta para los casos HTTP 200 y HTTP 202 es un objeto JSON con los siguientes campos:

Campo Tipo de datos Descripción
runtimeStatus string Estado en tiempo de ejecución de la instancia. Los valores son Running, Pending, Failed, Canceled, Terminated, Completed, Suspended.
input JSON Datos JSON usados para inicializar la instancia. Este campo es null si el parámetro de cadena de consulta showInput esté establecido en false.
customStatus JSON Datos JSON que se usan en el estado de orquestación personalizada. Este campo es null si no se establece.
output JSON Salida JSON de la instancia. Este campo es null si el estado de la instancia no es Completado.
createdTime string Hora a la que se creó la instancia. Usa la notación ampliada de ISO 8601.
lastUpdatedTime string Hora a la que se almacenó la instancia por última vez. Usa la notación ampliada de ISO 8601.
historyEvents JSON Una matriz JSON que contiene el historial de ejecución de orquestación. Este campo es null a menos que el parámetro de cadena de consulta showHistory esté establecido en true.

Este es un ejemplo de una carga de respuesta que incluye las salidas de historial de ejecución de orquestación y de actividad (a la que se ha aplicado formato para mejorar la legibilidad):

{
  "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 respuesta HTTP 202 también incluye un encabezado de respuesta Location que hace referencia a la misma dirección URL que el campo statusQueryGetUri mencionado anteriormente.

Obtención de todos los estados de instancias

También puede consultar el estado de todas las instancias mediante la eliminación de instanceId de la solicitud "Obtener el estado de la instancia". En este caso, los parámetros básicos son los mismos que en "Obtener el estado de la instancia". También se admiten parámetros de cadena de consulta para filtrar.

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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}

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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}

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
showInput Cadena de consulta Parámetro opcional. Si se establece en false, la entrada de la función no se incluye en la carga de respuesta.
showHistoryOutput Cadena de consulta Parámetro opcional. Si se establece en true, las salidas de la función se incluyen en el historial de ejecución de la orquestación.
createdTimeFrom Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas que se crearon durante la marca de tiempo ISO8601 especificada o después de esta.
createdTimeTo Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas que se crearon durante la marca de tiempo ISO8601 especificada o antes de esta.
runtimeStatus Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias devueltas según su estado en tiempo de ejecución. Para ver la lista de valores posibles del estado en tiempo de ejecución, consulte el artículo Consulta de instancias.
instanceIdPrefix Cadena de consulta Parámetro opcional. Cuando se especifica, filtra la lista de instancias devueltas para incluir solo las instancias cuyo identificador de instancia comienza con la cadena de prefijo especificada. Disponible a partir de la versión 2.7.2 de la extensión.
top Cadena de consulta Parámetro opcional. Cuando se especifica, limita el número de instancias que devuelve la consulta.

Response

Este es un ejemplo de cargas de respuesta, incluido el estado de orquestación (con formato para mejorar la legibilidad):

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

Esta operación puede ser muy costosa en términos de E/S de Azure Storage si usa el proveedor predeterminado de Azure Storage y si hay muchas filas en la tabla Instancias. Puede encontrar más detalles sobre la tabla Instancia en la documentación del proveedor de Azure Storage.

Si existen más resultados, se devuelve un token de continuación en el encabezado de respuesta. El nombre del encabezado es x-ms-continuation-token.

Precaución

El resultado de la consulta puede devolver menos elementos que el límite especificado por top. Al recibir los resultados, por lo tanto siempre debe comprobar si hay un token de continuación.

Si establece el valor del token de continuación en el siguiente encabezado de solicitud, puede obtener la página de resultados siguiente. El nombre del encabezado de solicitud también es x-ms-continuation-token.

Purgado del historial de una instancia

Elimina el historial y los artefactos relacionados para una instancia de orquestación específica.

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.

Response

Se pueden devolver los siguientes valores de código de estado HTTP.

  • HTTP 200 (correcto) : El historial de la instancia se ha purgado correctamente.
  • HTTP 404 (no se encuentra) : La instancia especificada no existe.

La carga de respuesta para el caso HTTP 200 es un objeto JSON con el siguiente campo:

Campo Tipo de datos Descripción
instancesDeleted integer Número de instancias eliminadas. Para el caso de instancia única, este valor debe ser siempre 1.

Esta es una carga de respuesta de ejemplo (con formato para mejorar la legibilidad):

{
    "instancesDeleted": 1
}

Purgado de historiales de varias instancias

También puede eliminar el historial y los artefactos relacionados de varias instancias de una central de tareas mediante la eliminación de {instanceId} de la solicitud "Purge single instance history" (Purgar el historial de una instancia). Para purgar selectivamente el historial de instancia, use los mismos filtros que se describe en la solicitud "Obtener el estado de todas las instancias".

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
createdTimeFrom Cadena de consulta Se filtra la lista de instancias purgadas que se crearon durante la marca de tiempo ISO8601 especificada o después de esta.
createdTimeTo Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias purgadas que se crearon durante la marca de tiempo ISO8601 especificada o antes de esta.
runtimeStatus Cadena de consulta Parámetro opcional. Cuando se especifica, se filtra la lista de instancias purgadas según su estado en tiempo de ejecución. Para ver la lista de valores posibles del estado en tiempo de ejecución, consulte el artículo Consulta de instancias.

Nota

Esta operación puede ser muy costosa en términos de E/S de Azure Storage si usa el proveedor predeterminado de Azure Storage y si hay muchas filas en las tablas Instancias o Historial. Puede encontrar más detalles sobre estas tablas en la documentación Performance and scale in Durable Functions (Azure Functions) (Rendimiento y escalado horizontal en Durable Functions [Azure Functions]).

Response

Se pueden devolver los siguientes valores de código de estado HTTP.

  • HTTP 200 (correcto) : El historial de la instancia se ha purgado correctamente.
  • HTTP 404 (no se encuentra) : No se encontraron instancias que coincidan con la expresión de filtro.

La carga de respuesta para el caso HTTP 200 es un objeto JSON con el siguiente campo:

Campo Tipo de datos Descripción
instancesDeleted integer Número de instancias eliminadas.

Esta es una carga de respuesta de ejemplo (con formato para mejorar la legibilidad):

{
    "instancesDeleted": 250
}

Generación de eventos

Para enviar un mensaje de notificación de eventos a una instancia de orquestación en ejecución:

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
eventName URL Nombre del evento al que espera la instancia de orquestación de destino.
{content} Contenido de la solicitud Carga del evento con formato JSON.

Response

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (aceptado) : se aceptó el evento generado para su procesamiento.
  • HTTP 400 (solicitud incorrecta) : el contenido de la solicitud no era del tipo application/json o no tenía un valor JSON válido.
  • HTTP 404 (no se encuentra) : no se encontró la instancia especificada.
  • HTTP 410 (no existe) : la instancia especificada ha finalizado o se ha producido un error y no puede procesar los eventos generados.

Esta es una solicitud de ejemplo que envía la cadena JSON "incr" a una instancia que espera un evento denominado operation:

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

"incr"

Las respuestas para esta API no tienen contenido.

Finalización de instancias

Para terminar una instancia de orquestación en ejecución:

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como el siguiente parámetro único.

Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
reason Cadena de consulta Opcional. Motivo de finalización de la instancia de orquestación.

Response

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (aceptado) : se aceptó la solicitud de finalización para su procesamiento.
  • HTTP 404 (no se encuentra) : no se encontró la instancia especificada.
  • HTTP 410 (no existe) : la instancia especificada se ha completado o ha producido un error.

Esta es una solicitud de ejemplo que finaliza una instancia en ejecución y especifica un motivo buggy:

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

Las respuestas para esta API no tienen contenido.

Suspender instancia

Suspende una instancia de orquestación en ejecución.

Solicitud

En la versión 2.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
reason Cadena de consulta Opcional. Motivo para suspender la instancia de orquestación.

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (Accepted): se aceptó la solicitud de suspensión para su procesamiento.
  • HTTP 404 (no se encuentra) : no se encontró la instancia especificada.
  • HTTP 410 (Gone): la instancia especificada se completó, dio error o finalizó.

Las respuestas para esta API no tienen contenido.

Reanudar instancia

Reanuda una instancia de orquestación suspendida.

Solicitud

En la versión 2.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
reason Cadena de consulta Opcional. Motivo para reanudar la instancia de orquestación.

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (Accepted): se aceptó la solicitud de reanudación para su procesamiento.
  • HTTP 404 (no se encuentra) : no se encontró la instancia especificada.
  • HTTP 410 (Gone): la instancia especificada se completó, dio error o finalizó.

Las respuestas para esta API no tienen contenido.

Rebobinado de instancias (versión preliminar)

Restaura una instancia de orquestación errónea a un estado de ejecución mediante la reproducción de las operaciones erróneas más recientes.

Solicitud

Para la versión 1.x del entorno de ejecución de Functions, la solicitud tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

En la versión 2.x del entorno de ejecución de Functions, el formato de dirección URL tiene los mismos parámetros, pero un prefijo ligeramente diferente:

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como el siguiente parámetro único.

Campo Tipo de parámetro Descripción
instanceId URL Identificador de la instancia de orquestación.
reason Cadena de consulta Opcional. Motivo para rebobinar la instancia de orquestación.

Response

Se pueden devolver varios valores de código de estado.

  • HTTP 202 (aceptado) : se aceptó la solicitud de rebobinado para su procesamiento.
  • HTTP 404 (no se encuentra) : no se encontró la instancia especificada.
  • HTTP 410 (no existe) : la instancia especificada se completó o se terminó.

Esta es una solicitud de ejemplo que rebobina una instancia errónea y especifica un motivo de fixed:

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

Las respuestas para esta API no tienen contenido.

Entidad de señal

Envía un mensaje de operación unidireccional a una entidad duradera. Si la entidad no existe, se creará automáticamente.

Nota

Las entidades durables están disponibles a partir de Durable Functions 2.0.

Solicitud

La solicitud HTTP tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
entityName URL El nombre (tipo) de la entidad.
entityKey URL La clave (identificador único) de la entidad.
op Cadena de consulta Opcional. El nombre de la operación definida por el usuario que se va a invocar.
{content} Contenido de la solicitud Carga del evento con formato JSON.

A continuación se muestra una solicitud de ejemplo que envía un mensaje "Add" definido por el usuario a una entidad Counterdenominada steps. El contenido del mensaje es el valor 5. Si la entidad todavía no existe, se creará mediante esta solicitud:

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

5

Nota

De forma predeterminada en las entidades basadas en clases en .NET, al especificar el valor op de delete se eliminará el estado de una entidad. Sin embargo, si la entidad define una operación denominada delete, se invocará en su lugar la operación definida por el usuario.

Response

Esta operación tiene varias respuestas posibles:

  • HTTP 202 (aceptado) : la operación de la señal se aceptó para el procesamiento asincrónico.
  • HTTP 400 (solicitud incorrecta) : el contenido de la solicitud no era del tipo application/json, no tenía un valor JSON válido o no tenía un valor entityKey válido.
  • HTTP 404 (no se encuentra) : no se encontró el entityName especificado.

Una solicitud HTTP correcta no contiene nada en la respuesta. Una solicitud HTTP con error puede contener información de error con formato JSON en el contenido de la respuesta.

Obtención de la entidad

Obtiene el estado de la entidad especificada.

Solicitud

La solicitud HTTP tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

Response

Esta operación tiene dos respuestas posibles:

  • HTTP 200 (correcto) : la entidad especificada existe.
  • HTTP 404 (no se encuentra) : no se encontró la entidad especificada.

Una respuesta correcta contiene el estado serializado de JSON de la entidad como su contenido.

Ejemplo

El siguiente ejemplo de solicitud HTTP obtiene el estado de una entidad Counter existente denominada steps:

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

Si la entidad Counter simplemente contenía una serie de pasos guardados en un campo currentValue, el contenido de la respuesta podría ser similar al siguiente (con formato para facilitar la legibilidad):

{
    "currentValue": 5
}

Entidades de lista

Puede consultar varias entidades por el nombre de la entidad o por la fecha de la última operación.

Solicitud

La solicitud HTTP tiene el formato siguiente (se muestran varias líneas para mayor claridad):

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

Los parámetros de solicitud de esta API incluyen el conjunto predeterminado mencionado anteriormente, así como los siguientes parámetros únicos:

Campo Tipo de parámetro Descripción
entityName URL Opcional. Cuando se especifica, filtra la lista de entidades devueltas por su nombre de entidad (no distingue mayúsculas y minúsculas).
fetchState Cadena de consulta Parámetro opcional. Si se establece en true, el estado de la entidad se incluirá en la carga de respuesta.
lastOperationTimeFrom Cadena de consulta Parámetro opcional. Cuando se especifica, filtra la lista de entidades devueltas que procesaron operaciones después de la marca de tiempo ISO8601 especificada.
lastOperationTimeTo Cadena de consulta Parámetro opcional. Cuando se especifica, filtra la lista de entidades devueltas que procesaron operaciones antes de la marca de tiempo ISO8601 especificada.
top Cadena de consulta Parámetro opcional. Cuando se especifica, limita el número de entidades que devuelve la consulta.

Response

Una respuesta HTTP 200 correcta contiene una matriz de entidades serializada con JSON y, opcionalmente, el estado de cada entidad.

De forma predeterminada, la operación devuelve las 100 primeras entidades que coinciden con los criterios de consulta. El autor de la llamada puede especificar un valor de parámetro de cadena de consulta para que top devuelva un número máximo de resultados diferente. Si existen otros resultados más allá de lo que se devuelve, también se devuelve un token de continuación en el encabezado de respuesta. El nombre del encabezado es x-ms-continuation-token.

Si establece el valor del token de continuación en el siguiente encabezado de solicitud, puede obtener la página de resultados siguiente. El nombre del encabezado de solicitud también es x-ms-continuation-token.

Ejemplo: lista de todas las entidades

En la siguiente solicitud HTTP de ejemplo se enumeran todas las entidades de la central de tareas:

GET /runtime/webhooks/durabletask/entities

El JSON de respuesta puede tener un aspecto similar al siguiente (se ha dado formato para mejorar la legibilidad):

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

Ejemplo: filtrado de la lista de entidades

En la siguiente solicitud HTTP de ejemplo solo se enumeran las dos primeras entidades de tipo counter y también se captura su estado:

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

El JSON de respuesta puede tener un aspecto similar al siguiente (se ha dado formato para mejorar la legibilidad):

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

Pasos siguientes

Aprenda a usar Application Insights para supervisar sus instancias de Durable Functions