Referência de API HTTP

  • Artigo

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.

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.

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