Referência da API HTTP

A extensão Durable Functions expõe um conjunto de APIs HTTP incorporadas que podem executar tarefas de gestão em orquestrações, entities e tarefas. Estas APIs HTTP são webhooks de extensibilidade que o host do Azure Functions autoriza, mas a extensão Durable Functions trata diretamente.

Antes de usar estas APIs HTTP, certifique-se de que tem:

• Uma compreensão básica dos conceitos de modelos de programação de Tarefas Duradouras (orquestradores, atividades, entidades)
• Um projeto Durable Functions inicializado com ligações configuradas
• Acesso ao URL base da sua aplicação de função, nome do hub de tarefas, definições de ligação e chave de autorização

URL base e parâmetros comuns

Todas as APIs HTTP partilham a mesma URL base que a tua aplicação funcional. Quando desenvolves localmente usando as Ferramentas Centrais Azure Functions, a URL base é tipicamente http://localhost:7071. No serviço Azure Functions hospedado, a URL base é tipicamente https://{appName}.azurewebsites.net. A extensão também suporta nomes de host personalizados se configurados na sua aplicação de Serviços de Aplicações.

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

Como obter valores de parâmetros

Uso de ligações de cliente de orquestração (recomendado): Gerar URLs completas automaticamente usando APIs de ligação de clientes de orquestração :

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

Construção manual de URLs:

• taskHub: Retirado do host.json ficheiro:

  • v2.x: extensions.durableTask.hubName
  • v1.x: durableTask.hubName
  • Também pode ser configurado através das definições da aplicação usando %AppSettingName% a sintaxe

• connection: Nome da definição da aplicação que contém a ligação de armazenamento. Retirado de host.json:

  • v2.x: extensions.durableTask.storageProvider.connectionStringName (por defeito se AzureWebJobsStorage não for especificado)
  • v1.x: durableTask.azureStorageConnectionStringName (por defeito se AzureWebJobsStorage não especificado)
  • Pode usar cadeias de ligação ou ligações baseadas em identidade (autenticação Microsoft Entra)

• systemKey: Chave de autorização específica de extensão para APIs de Tarefas Duradouras. Retirado do portal Azure:

  1. Abra a sua Aplicação de Funções
  2. Selecione as teclas Funções → Aplicação no menu esquerdo
  3. Na secção de chaves do Sistema , localize a chave (normalmente gerada automaticamente para a extensão)
  4. Copiar o valor-chave

  ️ Nota de segurança: A chave do sistema concede acesso a todas as APIs HTTP Durable Functions. Não partilhes publicamente nem o incluas no código do lado do cliente.

Cada API HTTP suporta um conjunto consistente de padrões de pedido/resposta. As secções seguintes fornecem informações para cada operação.

Fluxo de trabalho comum de API

Um ciclo típico de vida de orquestração segue esta sequência:

1. Iniciar orquestração → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → Devolve o ID da instância e o URL de estado
2. Verificar o estado → GET /runtime/webhooks/durabletask/instances/{instanceId} → Monitorizar o progresso
3. Enviar evento (opcional) → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} → Enviar sinais externos
4. Limpeza (opcional) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} → Histórico de Purga

Para detalhes das operações e exemplos de pedido/resposta, consulte a referência abaixo.

Iniciar orquestração

Começa a executar uma nova instância da função de orquestrador especificada.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): A função do orquestrador especificada estava programada para começar a executar. O Location cabeçalho de resposta contém uma URL para consultar o estado da orquestração.
• HTTP 400 (Pedido mau): A função do orquestrador especificada não existe, o ID da instância especificado não é válido, ou o conteúdo do pedido não é JSON válido.

Segue-se um pedido de exemplo que inicia uma RestartVMs função de orquestrador e inclui uma carga útil de 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:

O tipo de dados de todos os campos é string.

Aqui está um exemplo de payload de resposta para uma instância de orquestração com abc123 como 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 de Consumidor de Polling. Inclui também os seguintes cabeçalhos de resposta notáveis:

• Localização: A URL do endpoint de estado, que contém o mesmo valor do statusQueryGetUri campo.
• Retry-After: O número de segundos a esperar entre as operações de sondagem. O valor predefinido é 10.

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

Obtenha o estado da instância

Obtém o estado de uma instância de orquestração especificada. Use isto para monitorizar o progresso da orquestração e obter resultados.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 200 (OK): A instância especificada encontra-se num estado concluído ou falhado.
• HTTP 202 (Aceite): A instância especificada está em curso.
• HTTP 400 (Pedido Mau): A instância especificada falhou ou foi terminada.
• HTTP 404 (Não Encontrado): A instância especificada não existe ou ainda não começou a correr.
• HTTP 500 (Erro do Servidor Interno): Retornado apenas quando o returnInternalServerErrorOnFailure é 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:

Aqui está um exemplo de carga útil de resposta, incluindo o histórico de execução da orquestração e os resultados das atividades (formatados 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 inclui também um cabeçalho de resposta Localização que faz referência ao mesmo URL do statusQueryGetUri campo mencionado anteriormente.

Obter o status de todas as instâncias

Consulta o estado de múltiplas instâncias de orquestração ao mesmo tempo. Pode filtrar os resultados por estado, tempo de criação e prefixo de ID de instância. Use esta operação para monitorizar todas as orquestrações ativas ou encontrar instâncias específicas.

Solicitação

Runtime de funções 2.x (recomendado):

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}

Runtime de funções 1.x (legado):

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}

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

Aqui está um exemplo de carga útil de resposta incluindo o estado da orquestração (formatado para melhor 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 é devolvido no cabeçalho da resposta. O nome do cabeçalho é x-ms-continuation-token.

Se definir o valor do token de continuação no próximo cabeçalho do pedido, pode obter a página seguinte de resultados. O nome do cabeçalho do pedido também x-ms-continuation-tokené .

Purgar histórico de instância única

Apaga o histórico e artefatos relacionados de uma instância de orquestração especificada. Esta operação liberta recursos de armazenamento e não pode ser desfeita.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

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

• HTTP 200 (OK): O histórico das instâncias foi eliminado com sucesso.
• 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:

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

{
    "instancesDeleted": 1
}

Purgar múltiplos históricos de instâncias

Apaga o histórico e os artefactos de várias instâncias ao mesmo tempo, filtrados por estado, hora de criação ou prefixo do ID da instância. Use isto para limpar instâncias antigas em massa e gerir custos de armazenamento.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

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

• HTTP 200 (OK): O histórico das instâncias foi eliminado com sucesso.
• HTTP 404 (Não Encontrado): Não foram encontradas instâncias que correspondam à expressão do filtro.

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

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

{
    "instancesDeleted": 250
}

Acionar evento

Envia uma mensagem de notificação de evento para uma instância de orquestração em execução. A orquestração deve estar à espera deste evento pelo nome usando WaitForExternalEvent ou wait_for_external_event.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): O evento levantado foi aceite para processamento.
• HTTP 400 (pedido mau): O conteúdo do pedido 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 (Desaparecido): A instância especificada foi concluída ou falhou e não consegue processar quaisquer eventos levantados.

Aqui está um pedido de exemplo que envia a string "incr" JSON para uma instância à espera de uma operação chamada evento:

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.

Terminar instância

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

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e o seguinte parâmetro único.

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): O pedido de terminação foi aceite para processamento.
• HTTP 404 (Não Encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Desaparecido): A instância especificada foi concluída ou falhou.

Aqui está um pedido de exemplo que termina uma instância em execução e especifica uma razão de buggy:

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.

Suspensão de instância

Pausa uma instância de orquestração em execução sem a terminar. A instância pode ser retomada mais tarde usando a resume operação.

Solicitação

Na versão 2.x do runtime Functions, o pedido está formatado da seguinte forma (várias linhas são mostradas para maior clareza):

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

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): O pedido de suspensão foi aceite para processamento. Não é respondido.
• HTTP 404 (Não Encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Desaparecido): A instância especificada foi concluída, falhou ou terminou e não pode ser suspensa.

Verificação: Após receber HTTP 202, consulte o estado da instância usando GET /runtime/webhooks/durabletask/instances/{instanceId} para verificar se runtimeStatus mudou para "Suspended".

Retomar instância

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

Solicitação

Na versão 2.x do runtime Functions, o pedido está formatado da seguinte forma (várias linhas são mostradas para maior clareza):

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

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): O pedido de currículo foi aceite para processamento. Não é respondido.
• HTTP 404 (Não Encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Desaparecido): A instância especificada foi concluída, falhou ou terminou e não pode ser retomada.

Verificação: Após receber HTTP 202, consulte o estado da instância usando GET /runtime/webhooks/durabletask/instances/{instanceId} para verificar se runtimeStatus mudou para "Running".

Instância Rewind (pré-visualização)

Restaura uma instância de orquestração falhada para um estado operacional reexecutando as operações falhadas mais recentes. Esta funcionalidade permite a recuperação de falhas transitórias sem intervenção manual.

Solicitação

Runtime de funções 2.x (recomendado):

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

Runtime de funções 1.x (legado):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e o seguinte parâmetro único.

Resposta

Vários valores possíveis de código de estado podem ser devolvidos.

• HTTP 202 (Aceite): O pedido de rebobinamento foi aceite para processamento.
• HTTP 404 (Não Encontrado): A instância especificada não foi encontrada.
• HTTP 410 (Desaparecido): A instância especificada foi concluída ou terminada.

Aqui está um pedido de exemplo que rebobina uma instância com falha e especifica um motivo de fixed:

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 do sinal

Envia uma mensagem de operação unidirecional para uma Entidade Durável. Se a entidade não existir, é criada automaticamente. As operações da entidade são processadas sequencialmente e persistem de forma duradoura.

Solicitação

O pedido HTTP está formatado da seguinte forma (são mostradas várias linhas para maior clareza):

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

Os parâmetros de pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Aqui está um pedido de exemplo que envia uma mensagem "Adicionar" definida pelo utilizador para uma Counter entidade chamada steps. O conteúdo da mensagem é o valor 5. Se a entidade ainda não existir, este pedido cria-a:

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

5

Resposta

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

• HTTP 202 (Aceite): A operação do sinal foi aceite para processamento assíncrono.
• HTTP 400 (pedido mau): O conteúdo do pedido 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.

Um pedido HTTP bem-sucedido não contém qualquer conteúdo na resposta. Um pedido HTTP falhado pode conter informação de erro no formato JSON no conteúdo da resposta.

Obter entidade

Obtém o estado da entidade especificada.

Solicitação

O pedido HTTP está formatado da seguinte forma (são mostradas várias linhas para maior clareza):

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

Resposta

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

• 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 em JSON da entidade como seu conteúdo.

Example

Para obter o estado de uma entidade existente Counter nomeado steps:

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

Se a entidade Counter simplesmente contivesse um número de passos guardados num currentValue campo, o conteúdo da resposta poderia ser o seguinte (formatado para legibilidade):

{
    "currentValue": 5
}

Listar entidades

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

Solicitação

O pedido HTTP está formatado da seguinte forma (são mostradas várias linhas para maior 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 pedido para esta API incluem o conjunto padrão mencionado anteriormente e os seguintes parâmetros únicos:

Resposta

Uma resposta HTTP 200 bem-sucedida contém um array serializado em JSON de entidades e, opcionalmente, o estado de cada entidade.

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

Se definir o valor do token de continuação no próximo cabeçalho do pedido, pode obter a página seguinte de resultados. O nome do cabeçalho do pedido também x-ms-continuation-tokené .

Exemplo - listar todas as entidades

Para listar todas as entidades no hub de tarefas:

GET /runtime/webhooks/durabletask/entities

O JSON da resposta pode ser o seguinte (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 - filtrar a lista de entidades

Para listar as duas counter primeiras entidades e obter o seu estado:

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

O JSON da resposta pode ser o seguinte (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 }
    }
]

Exemplo de fluxo de trabalho completo

Este exemplo demonstra um ciclo completo de vida de orquestração usando curl comandos. Também podes usar o Postman, Thunder Client ou qualquer cliente HTTP.

1. Iniciar uma orquestração

Iniciar uma nova ProcessOrder orquestração com dados de entrada:

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

Resposta (HTTP 202):

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

Guardar o ID da instância: abc123def456

2. Sondagem para o estado

Verifique o progresso da orquestração:

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

Resposta durante a execução (HTTP 202):

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

Resposta quando concluída (HTTP 200):

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

3. Enviar um evento externo (opcional)

Se a orquestração estiver à espera de aprovação, envie um evento de aprovação:

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

Resposta: HTTP 202 (Aceite)

4. Histórico de limpeza (opcional)

Depois de a orquestração terminar, purgar a sua história:

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

Resposta (HTTP 200):

{
  "instancesDeleted": 1
}

Próximos passos