Referência de API HTTP

Artigo
06/01/2023

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, entidadese hubs de tarefas. Essas APIs HTTP são webhooks de extensibilidade autorizadas pelo host do Azure Functions, mas manipuladas 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ções. Ao desenvolver localmente usando as Azure Functions Core Tools, a URL base normalmente é http://localhost:7071. No serviço hospedado do Azure Functions, a URL base normalmente é https://{appName}.azurewebsites.net. Também há suporte para nomes de host personalizados se configurados em seu aplicativo do Serviço de Aplicativo.

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

Parâmetro	Tipo de parâmetro	Descrição
`taskHub`	Cadeia de consulta	O nome do hub de tarefas. Se não for especificado, o nome do hub de tarefas do aplicativo de funções será presumido.
`connection`	Cadeia de consulta	O nome da configuração do aplicativo de conexão para o provedor de armazenamento de back-end. Se não for especificada, a configuração de conexão padrão do aplicativo de funções será presumida.
`systemKey`	Cadeia 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. Ela concede acesso especificamente às APIs da extensão de Tarefas Duráveis e pode ser gerenciada da mesma maneira que as outras chaves de acesso do Azure Functions. Você pode gerar URLs que contenham os valores de cadeia de caracteres de consulta corretos taskHub, connection e systemKey usando APIs de associação do cliente de orquestração, como as APIs CreateCheckStatusResponse e CreateHttpManagementPayload no .NET, as APIs createCheckStatusResponse e createHttpManagementPayload no JavaScript etc.

As próximas seções tratam das APIs HTTP específicas com suporte da 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 de orquestrador especificada.

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`functionName`	URL	O nome da função de orquestrador a ser iniciada.
`instanceId`	URL	Parâmetro opcional. A ID da instância de orquestração. Se não especificado, a função de orquestrador será iniciada com uma ID de instância aleatória.
`{content}`	Conteúdo da solicitação	Opcional. A entrada da função de orquestrador formatada em JSON.

Resposta

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

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

Veja a seguir um exemplo de solicitação que inicia uma função de orquestrador RestartVMs e inclui a carga do 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"
}

O conteúdo da resposta para os casos de HTTP 202 é um objeto JSON com os campos a seguir:

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 "acionar evento" da instância de orquestração.
`terminatePostUri`	A URL "encerrar" da instância de orquestração.
`purgeHistoryDeleteUri`	A URL "limpar histórico" da instância de orquestração.
`rewindPostUri`	(visualização) A URL "retroceder" da instância de orquestração.
`suspendPostUri`	A URL "suspender" da instância de orquestração.
`resumePostUri`	A URL "retomar" da instância de orquestração.

O tipo de dados de todos os campos é string.

Este é um exemplo de conteúdo de resposta para uma instância de orquestração com abc123 como ID (formatada para facilitar a leitura):

{
    "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 deve ser compatível com o Padrão de Consumidor de Sondagem. Ela também inclui estes cabeçalhos de resposta notáveis:

Location: a URL do ponto de extremidade do status. Essa URL contém o mesmo valor do statusQueryGetUri campo.
Retry-After: o número de segundos de espera entre as operações de sondagem. O valor padrão é 10.

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

Obter status da instância

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

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com 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]

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`instanceId`	URL	A ID da instância de orquestração.
`showInput`	Cadeia de consulta	Parâmetro opcional. Se definido como `false`, a entrada da função não será incluída no conteúdo da resposta.
`showHistory`	Cadeia de consulta	Parâmetro opcional. Se definido como `true`, o histórico de execução da orquestração será incluído na carga da resposta.
`showHistoryOutput`	Cadeia 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`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas criadas no ou após o carimbo de data e hora ISO8601 especificado.
`createdTimeTo`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas criadas no ou antes do carimbo de data e hora ISO8601 especificado.
`runtimeStatus`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas com base em seu status de runtime. Para ver a lista de possíveis valores de status de tempo de execução, consulte o artigo Consulta de instâncias.
`returnInternalServerErrorOnFailure`	Cadeia de consulta	Parâmetro opcional. Se definido como `true`, essa API retornará uma resposta HTTP 500 em vez de 200, se a instância estiver em estado de falha. Esse parâmetro destina-se a cenários de sondagem de status automatizados.

Resposta

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

HTTP 200 (OK) : a instância especificada está em estado concluído ou de 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 de Servidor Interno) : retornado somente quando returnInternalServerErrorOnFailure é definido como true e a instância especificada falhou com exceção sem tratamento.

A carga de resposta para os casos de HTTP 200 e HTTP 202 é um objeto JSON com os campos a seguir:

Campo	Tipo de dados	Descrição
`runtimeStatus`	string	O status de runtime da instância. Os valores incluem Em execução, Pendente, Com Falha, Cancelado, Encerrado, Concluído, Suspenso.
`input`	JSON	Os dados JSON usados para inicializar a instância. Este campo é `null` se o `showInput` parâmetro da cadeia de caracteres de consulta for definido para `false`.
`customStatus`	JSON	Os dados JSON usados para status de orquestração personalizado. Este campo é `null` se não for definido.
`output`	JSON	A saída JSON da instância. Este campo será `null` se a instância não estiver no estado concluído.
`createdTime`	string	A hora em que a instância foi criada. Usa a notação estendida ISO 8601.
`lastUpdatedTime`	string	A hora em que a instância foi persistida 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. Esse campo é `null`, exceto se o parâmetro da cadeia de caracteres de consulta `showHistory` estiver definido como `true`.

Aqui está um exemplo de carga de resposta, incluindo o histórico de execução de orquestração e saídas de atividades (formatado 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 Local que faz referência à mesma URL que o campo statusQueryGetUri mencionado anteriormente.

Obter status de todas as instâncias

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

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com 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}

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`showInput`	Cadeia de consulta	Parâmetro opcional. Se definido como `false`, a entrada da função não será incluída no conteúdo da resposta.
`showHistoryOutput`	Cadeia 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`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas criadas no ou após o carimbo de data e hora ISO8601 especificado.
`createdTimeTo`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas criadas no ou antes do carimbo de data e hora ISO8601 especificado.
`runtimeStatus`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas com base em seu status de runtime. Para ver a lista de possíveis valores de status de tempo de execução, consulte o artigo Consulta de instâncias.
`instanceIdPrefix`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias retornadas para incluir apenas instâncias cuja ID da 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`	Cadeia de consulta	Parâmetro opcional. Quando especificado, limita o número de instâncias retornadas pela consulta.

Resposta

Aqui está um exemplo de cargas 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"
    }
]

Observação

Essa operação pode ser muito cara em termos de E/S do armazenamento do Azure se você estiver usando o provedor padrão de Armazenamento do Azure e se houver muitas linhas na tabela de Instâncias. Mais detalhes sobre a tabela de Instância podem ser encontrados na documentação do provedor de Armazenamento do Microsoft Azure.

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

Cuidado

O resultado da consulta pode retornar menos itens do que o limite especificado por top. Ao receber resultados, você deve sempre verificar se há um token de continuação.

Se você definir o valor do token de continuação no cabeçalho da próxima solicitação, terá a próxima página de resultados. O 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 para uma instância de orquestração especificada.

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

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

Resposta

Podem ser retornados os valores de código de status HTTP a seguir.

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 de resposta para o caso de HTTP 200 é um objeto JSON com o campo a seguir:

Campo	Tipo de dados	Descrição
`instancesDeleted`	Número inteiro	O número de instâncias excluídas. No caso de instância única, esse valor deve ser sempre `1`.

Veja um exemplo de carga de resposta (formatada para facilitar a leitura):

{
    "instancesDeleted": 1
}

Limpar históricos de várias instâncias

Você também pode excluir o histórico e artefatos relacionados para várias instâncias em um hub de tarefas removendo a {instanceId} da solicitação 'Limpar o 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'.

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`createdTimeFrom`	Cadeia de consulta	Filtra a lista de instâncias limpas criadas no ou após o carimbo de data e hora ISO8601 especificado.
`createdTimeTo`	Cadeia de consulta	Parâmetro opcional. Quando especificado, filtra a lista de instâncias limpas criadas no ou antes do carimbo de data e hora ISO8601 especificado.
`runtimeStatus`	Cadeia 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 Consulta de instâncias.

Observação

Essa operação pode ser muito cara em termos de E/S do armazenamento do Azure se você estiver usando o provedor padrão de Armazenamento do Azure e se houver muitas linhas nas tabelas de Instâncias e/ou Histórico. Veja mais detalhes sobre essas tabelas na documentação Desempenho e escala no Durable Functions (Azure Functions).

Resposta

Podem ser retornados os valores de código de status HTTP a seguir.

HTTP 200 (OK) : o histórico da instância foi limpo com êxito.
HTTP 404 (Não Encontrado) : nenhuma instância encontrada corresponde à expressão do filtro.

A carga de resposta para o caso de HTTP 200 é um objeto JSON com o campo a seguir:

Campo	Tipo de dados	Descrição
`instancesDeleted`	Número inteiro	O número de instâncias excluídas.

Veja um exemplo de carga de resposta (formatada para facilitar a leitura):

{
    "instancesDeleted": 250
}

Acionar evento

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

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`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á esperando.
`{content}`	Conteúdo da solicitação	A carga do evento em formato JSON.

Resposta

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 um JSON válido.
HTTP 404 (Não encontrado): a instância especificada não foi encontrada.
HTTP 410 (Não existe mais): a instância especificada foi concluída ou falhou e não pode processar os eventos gerados.

Veja um exemplo de solicitação que envia a cadeia de caracteres JSON "incr" para uma instância que aguarda um evento nomeado operation:

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 têm nenhum conteúdo.

Encerrar instância

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

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

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

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

Resposta

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 (Não existe mais): a instância especificada foi concluída ou falhou.

Veja um exemplo de solicitação que encerra uma instância em execução e especifica o motivo buggy:

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

As respostas para esta API não têm nenhum conteúdo.

Suspender instância

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

Solicitação

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

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

Campo	Tipo de parâmetro	Descrição
`instanceId`	URL	A ID da instância de orquestração.
`reason`	Cadeia de consulta	Opcional. O motivo para suspender a instância de orquestração.

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

HTTP 202 (Aceita): 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 (Não existe mais): a instância especificada foi concluída, falhou ou foi encerrada.

As respostas para esta API não têm nenhum conteúdo.

Retomar instância

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

Solicitação

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

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

Campo	Tipo de parâmetro	Descrição
`instanceId`	URL	A ID da instância de orquestração.
`reason`	Cadeia de consulta	Opcional. O motivo para retomar a instância de orquestração.

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

HTTP 202 (Aceita): a solicitação de retomada foi aceita para processamento.
HTTP 404 (Não encontrado): a instância especificada não foi encontrada.
HTTP 410 (Não existe mais): a instância especificada foi concluída, falhou ou foi encerrada.

As respostas para esta API não têm nenhum conteúdo.

Instância Gerenciada (versão prévia)

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

Solicitação

Para a versão 1.x do tempo de execução do Functions, a solicitação é formatada desta forma (são mostradas várias linhas para maior 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 da URL tem todos os mesmos parâmetros, mas com prefixo ligeiramente diferente:

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

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

Campo	Tipo de parâmetro	Descrição
`instanceId`	URL	A ID da instância de orquestração.
`reason`	Cadeia de consulta	Opcional. O motivo para retroceder a instância de orquestração.

Resposta

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

HTTP 202 (Aceito): a solicitação de retroceder foi aceita para processamento.
HTTP 404 (Não encontrado): a instância especificada não foi encontrada.
HTTP 410 (Não existe mais): a instância especificada foi concluída ou falhou.

Veja um exemplo de solicitação que retrocede uma instância com falha e especifica o motivo corrigido:

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

As respostas para esta API não têm nenhum conteúdo.

Entidade de sinal

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

Observação

As entidades duráveis estão disponíveis a partir do Durable Functions 2.0.

Solicitação

A solicitação HTTP é formatada como a seguir (são mostradas várias linhas para maior clareza):

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

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

Campo	Tipo de parâmetro	Descrição
`entityName`	URL	O nome (tipo) da entidade.
`entityKey`	URL	A chave (ID exclusiva) da entidade.
`op`	Cadeia de consulta	Opcional. O nome da operação definida pelo usuário a ser invocada.
`{content}`	Conteúdo da solicitação	A carga do evento em formato JSON.

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

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

5

Observação

Por padrão, com entidades baseadas em classe no .NET, a especificação do valor op de delete excluirá o estado de uma entidade. No entanto, se a entidade definir uma operação chamada delete, essa operação definida pelo usuário será invocada.

Resposta

Essa 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 inválida) : o conteúdo da solicitação não era do tipo application/json, não era um JSON válido ou tinha um valor entityKey inválido.
HTTP 404 (Não Encontrado) : a instância entityName especificada não foi encontrada.

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

Obter entidade

Obtém o estado da entidade especificada.

Solicitação

A solicitação HTTP é formatada como a seguir (são mostradas várias linhas para maior clareza):

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

Resposta

Essa 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 tem o estado serializado em JSON da entidade como conteúdo.

Exemplo

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

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

Se a entidade Counter contiver apenas uma série de etapas salvas em um campo currentValue, o conteúdo da resposta poderá ser semelhante a este (formatado para facilitar a leitura):

{
    "currentValue": 5
}

Listar entidades

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

Solicitação

A solicitação HTTP é formatada como a seguir (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}

Parâmetros de solicitação para essa API incluem o conjunto padrão mencionado anteriormente, bem como o parâmetro exclusivo a seguir:

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

Resposta

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

Por padrão, a operação retorna as primeiras 100 entidades correspondente aos critérios de consulta. O chamador pode especificar um valor de parâmetro de cadeia de consulta para que top retorne outro número máximo de resultados. Se houver mais resultados do que os retornados, também será retornado um token de continuação no cabeçalho de resposta. O nome do cabeçalho 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

A resposta JSON pode ser parecida com a esta (formatada para facilitar a leitura):

[
    {
        "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 – filtragem da 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

A resposta JSON pode ser parecida com a esta (formatada para facilitar a leitura):

[
    {
        "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óximas etapas

Saiba como usar o Application Insights para monitorar suas funções duráveis

Compartilhar via

Referência de API HTTP

Iniciar orquestração

Solicitação

Resposta

Obter status da instância

Solicitação

Resposta

Obter status de todas as instâncias

Solicitação

Resposta

Limpar histórico de instância única

Solicitação

Resposta

Limpar históricos de várias instâncias

Solicitação

Resposta

Acionar evento

Solicitação

Resposta

Encerrar instância

Solicitação

Resposta

Suspender instância

Solicitação

Retomar instância

Solicitação

Instância Gerenciada (versão prévia)

Solicitação

Resposta

Entidade de sinal

Solicitação

Resposta

Obter entidade

Solicitação

Resposta

Exemplo

Listar entidades

Solicitação

Resposta

Exemplo – listar todas as entidades

Exemplo – filtragem da lista de entidades

Próximas etapas

Comentários

Recursos adicionais