Referência da API HTTP

A extensão Durable Functions expõe um conjunto de APIs HTTP internas que podem ser usadas para executar tarefas de gerenciamento em orquestrações, entidades e hubs de tarefas. Essas APIs HTTP são webhooks de extensibilidade que são autorizados pelo host do Azure Functions, mas manipulados diretamente pela extensão Durable Functions.

A URL base para as APIs mencionadas neste artigo é a mesma que a URL base para seu aplicativo de função. Ao desenvolver localmente usando as Ferramentas Principais do Azure Functions, a URL base normalmente http://localhost:7071é . No serviço hospedado do Azure Functions, a URL base normalmente https://{appName}.azurewebsites.neté . Nomes de host personalizados também são suportados se configurados em seu aplicativo do Serviço de Aplicativo.

Todas as APIs HTTP implementadas pela extensão requerem os seguintes parâmetros. O tipo de dados de todos os parâmetros é string.

Parâmetro	Tipo de parâmetro	Description
taskHub	Cadeias de consulta	O nome do hub de tarefas. Se não for especificado, o nome do hub de tarefas do aplicativo de função atual será assumido.
connection	Cadeias de consulta	O nome da configuração do aplicativo de conexão para o provedor de armazenamento de back-end. Se não for especificado, a configuração de conexão padrão para o aplicativo de função será assumida.
systemKey	Cadeias de consulta	A chave de autorização necessária para invocar a API.

systemKey é uma chave de autorização gerada automaticamente pelo host do Azure Functions. Ele concede especificamente acesso às APIs de extensão de Tarefa Durável e pode ser gerenciado da mesma forma que outras chaves de acesso do Azure Functions. Você pode gerar URLs que contenham os valores corretos taskHub, connectione consultar cadeias de caracteres usando APIs de vinculação de cliente de orquestração, como as APIs e em .NET, as CreateCheckStatusResponse APIs e systemKey CreateHttpManagementPayload createHttpManagementPayload em JavaScript, etccreateCheckStatusResponse.

As próximas seções abordam as APIs HTTP específicas suportadas pela extensão e fornecem exemplos de como elas podem ser usadas.

Iniciar orquestração

Inicia a execução de uma nova instância da função orchestrator especificada.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
functionName	URL	O nome da função orquestradora a ser iniciada.
instanceId	URL	Parâmetro opcional. A ID da instância de orquestração. Se não for especificado, a função orchestrator começará com um ID de instância aleatório.
{content}	Solicitar conteúdo	Opcional. A entrada da função orquestrador formatada em JSON.

Response

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): A função orquestradora especificada foi agendada para iniciar a execução. O Location cabeçalho da resposta contém uma URL para sondar o status da orquestração.
• HTTP 400 (solicitação incorreta): A função orquestradora especificada não existe, o ID da instância especificado não era válido ou o conteúdo da solicitação não era JSON válido.

A seguir está um exemplo de solicitação que inicia uma RestartVMs função orchestrator e inclui carga útil do objeto JSON:

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

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

A carga útil de resposta para os casos HTTP 202 é um objeto JSON com os seguintes campos:

Campo	Descrição
id	A ID da instância de orquestração.
statusQueryGetUri	A URL de status da instância de orquestração.
sendEventPostUri	A URL "raise event" da instância de orquestração.
terminatePostUri	A URL "terminate" da instância de orquestração.
purgeHistoryDeleteUri	A URL "purge history" da instância de orquestração.
rewindPostUri	(pré-visualização) A URL "rewind" da instância de orquestração.
suspendPostUri	A URL "suspender" da instância de orquestração.
resumePostUri	A URL "resume" da instância de orquestração.

O tipo de dados de todos os campos é string.

Aqui está um exemplo de carga útil de resposta para uma instância de orquestração com abc123 seu ID (formatado para legibilidade):

{
    "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 resposta HTTP destina-se a ser compatível com o Padrão do Consumidor de Sondagem. Ele também inclui os seguintes cabeçalhos de resposta notáveis:

• Local: A URL do ponto de extremidade de status. Este URL contém o mesmo valor que o statusQueryGetUri campo.
• Retry-After: O número de segundos de espera entre as operações de sondagem. O valor predefinido é 10.

Para obter mais informações sobre o padrão de sondagem HTTP assíncrona, consulte a documentação de rastreamento de operação assíncrona HTTP.

Obter o status da instância

Obtém o status de uma instância de orquestração especificada.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente 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]

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
showInput	Cadeias de consulta	Parâmetro opcional. Se definido como false, a entrada da função não será incluída na carga útil de resposta.
showHistory	Cadeias de consulta	Parâmetro opcional. Se definido como true, o histórico de execução da orquestração será incluído na carga útil de resposta.
showHistoryOutput	Cadeias de consulta	Parâmetro opcional. Se definido como true, as saídas da função serão incluídas no histórico de execução da orquestração.
createdTimeFrom	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas que foram criadas no ou após o carimbo de data/hora de ISO8601 determinado.
createdTimeTo	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas que foram criadas no ou antes do carimbo de data/hora do ISO8601 determinado.
runtimeStatus	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas com base em seu status de tempo de execução. Para ver a lista de possíveis valores de status de tempo de execução, consulte o artigo Consultando instâncias .
returnInternalServerErrorOnFailure	Cadeias de consulta	Parâmetro opcional. Se definida como true, essa API retornará uma resposta HTTP 500 em vez de 200 se a instância estiver em um estado de falha. Este parâmetro destina-se a cenários automatizados de sondagem de status.

Response

Vários valores de código de status possíveis podem ser retornados.

• HTTP 200 (OK): A instância especificada está em um estado concluído ou com falha.
• HTTP 202 (Aceito): A instância especificada está em andamento.
• HTTP 400 (Solicitação incorreta): A instância especificada falhou ou foi encerrada.
• HTTP 404 (Não encontrado): A instância especificada não existe ou não começou a ser executada.
• HTTP 500 (Erro Interno do Servidor): Retornado somente quando o returnInternalServerErrorOnFailure está definido como true e a instância especificada falhou com uma exceção não tratada.

A carga útil de resposta para os casos HTTP 200 e HTTP 202 é um objeto JSON com os seguintes campos:

Campo	Tipo de dados	Description
runtimeStatus	string	O status de tempo de execução da instância. Os valores incluem Running, Pending, Failed, Canceled, Terminated, Completed, Suspended.
input	JSON	Os dados JSON usados para inicializar a instância. Este campo é null se o parâmetro da cadeia de caracteres de showInput consulta estiver definido como false.
customStatus	JSON	Os dados JSON usados para o status de orquestração personalizada. Este campo está null se não estiver definido.
output	JSON	A saída JSON da instância. Este campo é null se a instância não estiver em um estado concluído.
createdTime	string	O momento em que a instância foi criada. Usa a notação estendida ISO 8601.
lastUpdatedTime	string	O momento em que a instância persistiu pela última vez. Usa a notação estendida ISO 8601.
historyEvents	JSON	Uma matriz JSON contendo o histórico de execução da orquestração. Este campo é null a menos que o parâmetro da cadeia de caracteres de showHistory consulta esteja definido como true.

Aqui está um exemplo de carga útil de resposta, incluindo o histórico de execução da orquestração e as saídas de atividade (formatadas para legibilidade):

{
  "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 resposta HTTP 202 também inclui um cabeçalho de resposta de localização que faz referência à mesma URL que o statusQueryGetUri campo mencionado anteriormente.

Obter o status de todas as instâncias

Você também pode consultar o status de todas as instâncias removendo a instanceId solicitação 'Obter status da instância'. Nesse caso, os parâmetros básicos são os mesmos que o 'Get instance status'. Os parâmetros de cadeia de caracteres de consulta para filtragem também são suportados.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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}

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente 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}

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
showInput	Cadeias de consulta	Parâmetro opcional. Se definido como false, a entrada da função não será incluída na carga útil de resposta.
showHistoryOutput	Cadeias de consulta	Parâmetro opcional. Se definido como true, as saídas da função serão incluídas no histórico de execução da orquestração.
createdTimeFrom	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas que foram criadas no ou após o carimbo de data/hora de ISO8601 determinado.
createdTimeTo	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas que foram criadas no ou antes do carimbo de data/hora do ISO8601 determinado.
runtimeStatus	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas com base em seu status de tempo de execução. Para ver a lista de possíveis valores de status de tempo de execução, consulte o artigo Consultando instâncias .
instanceIdPrefix	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas para incluir apenas instâncias cujo ID de instância começa com a cadeia de caracteres de prefixo especificada. Disponível a partir da versão 2.7.2 da extensão.
top	Cadeias de consulta	Parâmetro opcional. Quando especificado, limita o número de instâncias retornadas pela consulta.

Response

Aqui está um exemplo de cargas úteis de resposta, incluindo o status de orquestração (formatado para legibilidade):

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

Se existirem mais resultados, um token de continuação será retornado no cabeçalho da resposta. O nome do cabeçalho é x-ms-continuation-token.

Se você definir o valor do token de continuação no cabeçalho da próxima solicitação, poderá obter a próxima página de resultados. Este nome do cabeçalho da solicitação também x-ms-continuation-tokené .

Limpar histórico de instância única

Exclui o histórico e os artefatos relacionados de uma instância de orquestração especificada.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.

Response

Os seguintes valores de código de status HTTP podem ser retornados.

• HTTP 200 (OK): O histórico da instância foi limpo com êxito.
• HTTP 404 (Não encontrado): A instância especificada não existe.

A carga útil de resposta para o caso HTTP 200 é um objeto JSON com o seguinte campo:

Campo	Tipo de dados	Description
instancesDeleted	integer	O número de instâncias excluídas. Para o caso de instância única, esse valor deve ser 1sempre .

Aqui está um exemplo de carga útil de resposta (formatada para legibilidade):

{
    "instancesDeleted": 1
}

Limpar vários históricos de instâncias

Você também pode excluir o histórico e os artefatos relacionados para várias instâncias dentro de um hub de tarefas removendo a {instanceId} solicitação 'Limpar histórico de instância única'. Para limpar seletivamente o histórico de instâncias, use os mesmos filtros descritos na solicitação 'Obter status de todas as instâncias'.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
createdTimeFrom	Cadeias de consulta	Filtra a lista de instâncias limpas que foram criadas no ou após o carimbo de data/hora do ISO8601 determinado.
createdTimeTo	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias limpas que foram criadas no ou antes do carimbo de data/hora do ISO8601 determinado.
runtimeStatus	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias limpas com base em seu status de tempo de execução. Para ver a lista de possíveis valores de status de tempo de execução, consulte o artigo Consultando instâncias .

Response

Os seguintes valores de código de status HTTP podem ser retornados.

• HTTP 200 (OK): O histórico da instância foi limpo com êxito.
• HTTP 404 (Não encontrado): Não foram encontradas instâncias que correspondam à expressão de filtro.

A carga útil de resposta para o caso HTTP 200 é um objeto JSON com o seguinte campo:

Campo	Tipo de dados	Description
instancesDeleted	integer	O número de instâncias excluídas.

Aqui está um exemplo de carga útil de resposta (formatada para legibilidade):

{
    "instancesDeleted": 250
}

Evento de aumento

Envia uma mensagem de notificação de evento para uma instância de orquestração em execução.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
eventName	URL	O nome do evento que a instância de orquestração de destino está aguardando.
{content}	Solicitar conteúdo	A carga útil do evento formatado em JSON.

Response

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): O evento gerado foi aceito para processamento.
• HTTP 400 (Solicitação incorreta): O conteúdo da solicitação não era do tipo application/json ou não era JSON válido.
• HTTP 404 (Não encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Gone): A instância especificada foi concluída ou falhou e não pode processar nenhum evento gerado.

Aqui está uma solicitação de exemplo que envia a cadeia de caracteres "incr" JSON para uma instância aguardando um evento chamado operação:

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

"incr"

As respostas para esta API não contêm qualquer conteúdo.

Encerrar instância

Encerra uma instância de orquestração em execução.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como o seguinte parâmetro exclusivo.

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
reason	Cadeias de consulta	Opcional. O motivo para encerrar a instância de orquestração.

Response

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): A solicitação de encerramento foi aceita para processamento.
• HTTP 404 (Não encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Gone): A instância especificada foi concluída ou falhou.

Aqui está um exemplo de solicitação que encerra uma instância em execução e especifica um motivo de bug:

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

As respostas para esta API não contêm qualquer conteúdo.

Suspender instância

Suspende uma instância de orquestração em execução.

Pedir

Na versão 2.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
reason	Cadeias de consulta	Opcional. O motivo da suspensão da instância de orquestração.

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): A solicitação de suspensão foi aceita para processamento.
• HTTP 404 (Não encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Gone): A instância especificada foi concluída, falhou ou foi encerrada.

As respostas para esta API não contêm qualquer conteúdo.

Retomar instância

Retoma uma instância de orquestração suspensa.

Pedir

Na versão 2.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
reason	Cadeias de consulta	Opcional. A razão para retomar a instância de orquestração.

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): A solicitação de currículo foi aceita para processamento.
• HTTP 404 (Não encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Gone): A instância especificada foi concluída, falhou ou foi encerrada.

As respostas para esta API não contêm qualquer conteúdo.

Instância de retrocesso (visualização)

Restaura uma instância de orquestração com falha em um estado de execução repetindo as operações com falha mais recentes.

Pedir

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Na versão 2.x do tempo de execução do Functions, o formato URL tem todos os mesmos parâmetros, mas com um prefixo ligeiramente diferente:

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como o seguinte parâmetro exclusivo.

Campo	Tipo de parâmetro	Description
instanceId	URL	A ID da instância de orquestração.
reason	Cadeias de consulta	Opcional. A razão para rebobinar a instância de orquestração.

Response

Vários valores de código de status possíveis podem ser retornados.

• HTTP 202 (Aceito): A solicitação de retrocesso foi aceita para processamento.
• HTTP 404 (Não encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Gone): A instância especificada foi concluída ou encerrada.

Aqui está um exemplo de solicitação que retrocede uma instância com falha e especifica um motivo de correção:

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

As respostas para esta API não contêm qualquer conteúdo.

Entidade de sinal

Envia uma mensagem de operação unidirecional para uma Entidade Durável. Se a entidade não existir, ela será criada automaticamente.

Pedir

A solicitação HTTP é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
entityName	URL	O nome (tipo) da entidade.
entityKey	URL	A chave (ID exclusiva) da entidade.
op	Cadeias de consulta	Opcional. O nome da operação definida pelo usuário a ser invocada.
{content}	Solicitar conteúdo	A carga útil do evento formatado em JSON.

Aqui está um exemplo de solicitação que envia uma mensagem "Adicionar" definida pelo usuário para uma Counter entidade chamada steps. O conteúdo da mensagem é o valor 5. Se a entidade ainda não existir, será criada por este pedido:

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

5

Response

Esta operação tem várias respostas possíveis:

• HTTP 202 (Aceito): A operação de sinal foi aceita para processamento assíncrono.
• HTTP 400 (Solicitação incorreta): O conteúdo da solicitação não era do tipo application/json, não era JSON válido ou tinha um valor inválido entityKey .
• HTTP 404 (Não encontrado): O especificado entityName não foi encontrado.

Uma solicitação HTTP bem-sucedida não contém nenhum conteúdo na resposta. Uma solicitação HTTP com falha pode conter informações de erro formatadas em JSON no conteúdo da resposta.

Obter entidade

Obtém o estado da entidade especificada.

Pedir

A solicitação HTTP é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Response

Esta operação tem duas respostas possíveis:

• HTTP 200 (OK): A entidade especificada existe.
• HTTP 404 (Não encontrado): A entidade especificada não foi encontrada.

Uma resposta bem-sucedida contém o estado serializado por JSON da entidade como seu conteúdo.

Exemplo

O exemplo de solicitação HTTP a seguir obtém o estado de uma entidade existente Counter chamada steps:

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

Se a entidade simplesmente contiver várias etapas salvas em um currentValue campo, o conteúdo da resposta poderá ter a Counter seguinte aparência (formatado para legibilidade):

{
    "currentValue": 5
}

Listar entidades

Você pode consultar várias entidades pelo nome da entidade ou pela data da última operação.

Pedir

A solicitação HTTP é formatada da seguinte forma (várias linhas são mostradas para clareza):

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

Os parâmetros de solicitação para esta API incluem o conjunto padrão mencionado anteriormente, bem como os seguintes parâmetros exclusivos:

Campo	Tipo de parâmetro	Description
entityName	URL	Opcional. Quando especificado, filtra a lista de entidades retornadas pelo nome da entidade (não diferencia maiúsculas de minúsculas).
fetchState	Cadeias de consulta	Parâmetro opcional. Se definido como true, o estado da entidade será incluído na carga útil de resposta.
lastOperationTimeFrom	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de entidades retornadas que processaram operações após o carimbo de data/hora de ISO8601 determinado.
lastOperationTimeTo	Cadeias de consulta	Parâmetro opcional. Quando especificado, filtra a lista de entidades retornadas que processaram operações antes do carimbo de data/hora de ISO8601 determinado.
top	Cadeias de consulta	Parâmetro opcional. Quando especificado, limita o número de entidades retornadas pela consulta.

Response

Uma resposta HTTP 200 bem-sucedida contém uma matriz serializada de entidades JSON e, opcionalmente, o estado de cada entidade.

Por padrão, a operação retorna as primeiras 100 entidades que correspondem aos critérios de consulta. O chamador pode especificar um valor de parâmetro de cadeia de caracteres de consulta para top retornar um número máximo diferente de resultados. Se existirem mais resultados além do que é retornado, um token de continuação também será retornado no cabeçalho da resposta. O nome do cabeçalho é x-ms-continuation-token.

Se você definir o valor do token de continuação no cabeçalho da próxima solicitação, poderá obter a próxima página de resultados. Este nome do cabeçalho da solicitação também x-ms-continuation-tokené .

Exemplo - listar todas as entidades

O exemplo de solicitação HTTP a seguir lista todas as entidades no hub de tarefas:

GET /runtime/webhooks/durabletask/entities

O JSON de resposta pode ter a seguinte aparência (formatado para legibilidade):

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

Exemplo - filtrando a lista de entidades

O exemplo de solicitação HTTP a seguir lista apenas as duas primeiras entidades do tipo counter e também busca seu estado:

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

O JSON de resposta pode ter a seguinte aparência (formatado para legibilidade):

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

Próximos passos