Referência da 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, entidades e hubs de tarefas. Essas APIs HTTP são webhooks de extensibilidade que são autorizados pelo host do Azure Functions, mas manipulados diretamente pela extensão Durable Functions.

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

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

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

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

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

Iniciar orquestração

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

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

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

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

O tipo de dados de todos os campos é string.

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

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/suspend?reason={text}&code=XXX",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/resume?reason={text}&code=XXX"
}

A resposta HTTP destina-se a ser compatível com o Padrão do Consumidor de Sondagem. Ele também inclui os seguintes cabeçalhos de resposta notáveis:

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

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

Obter o status da instância

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

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

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

A resposta HTTP 202 também inclui um cabeçalho de resposta de localização que faz referência à mesma URL que o statusQueryGetUri campo mencionado anteriormente.

Obter o status de todas as instâncias

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

Pedir

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

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

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

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

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

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

Response

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

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Nota

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

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

Atenção

O resultado da consulta pode retornar menos itens do que o limite especificado pelo top. Ao receber os resultados, você deve, portanto , 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, poderá obter a próxima página de resultados. Este nome do cabeçalho da solicitação também x-ms-continuation-tokené .

Limpar histórico de instância única

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

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

{
    "instancesDeleted": 1
}

Limpar vários históricos de instâncias

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

Pedir

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

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

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

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

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

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

Nota

Essa operação pode ser muito cara em termos de E/S do Armazenamento do Azure se você estiver usando o provedor de Armazenamento do Azure padrão e se houver muitas linhas nas tabelas Instâncias e/ou Histórico. Mais detalhes sobre essas tabelas podem ser encontrados na documentação Desempenho e escala em Funções duráveis (Azure Functions ).

Response

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

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

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

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

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

{
    "instancesDeleted": 250
}

Evento de aumento

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

"incr"

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

Encerrar instância

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

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

Suspender instância

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

Pedir

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo de parâmetro Description
instanceId URL A ID da instância de orquestração.
reason Cadeias de consulta Opcional. O motivo da suspensão da instância de orquestração.

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

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

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

Retomar instância

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

Pedir

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Campo Tipo de parâmetro Description
instanceId URL A ID da instância de orquestração.
reason Cadeias de consulta Opcional. A razão para retomar a instância de orquestração.

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

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

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

Instância de retrocesso (visualização)

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

Pedir

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

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

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

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

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

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

Response

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

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

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

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

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

Entidade de sinal

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

Nota

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

Pedir

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

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

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

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

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

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

5

Nota

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

Response

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

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

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

Obter entidade

Obtém o estado da entidade especificada.

Pedir

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

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

Response

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

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

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

Exemplo

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

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

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

{
    "currentValue": 5
}

Listar entidades

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

Pedir

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

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

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

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

Response

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

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

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

Exemplo - listar todas as entidades

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

GET /runtime/webhooks/durabletask/entities

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

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

Exemplo - filtrando a lista de entidades

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

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

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

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

Próximos passos

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