Справочник по API HTTP

  • Статья

Расширение "Устойчивые функции" обеспечивает доступ к набору встроенных API HTTP, которые можно использовать для выполнения задач управления оркестрациями, сущностями и центрами задач. Эти API HTTP являются веб-перехватчиками расширяемости, которые разрешены узлом функций Azure, но обрабатываются непосредственно расширением "Устойчивые функции".

Базовый URL-адрес API, упомянутых в этой статье, совпадает с базовым URL-адресом приложения-функции. При локальной разработке с помощью Azure Functions Core Tools базовым URL-адресом обычно является http://localhost:7071. В размещенной службе Функций Azure базовым URL-адресом обычно является https://{appName}.azurewebsites.net. Пользовательские имена узлов также поддерживаются, если они настроены в приложении Службы приложений.

Всем API HTTP, реализованным с помощью расширения, требуются следующие параметры. Тип данных всех параметров — string.

Параметр Тип параметра Description
taskHub Строка запроса Имя центра задач. Если не указано, предполагается имя центра задач текущего приложения-функции.
connection Строка запроса Имя параметра подключения приложения для поставщика серверного хранилища. Если оно не указано, для приложения-функции предполагается конфигурация подключения по умолчанию.
systemKey Строка запроса Ключ авторизации, необходимый для вызова API.

systemKey — это ключ авторизации, автоматически генерируемый узлом Функций Azure. В частности, он предоставляет доступ к API расширения "Устойчивые задачи", и им можно управлять точно так же, как и другими ключами доступа Функций Azure. Вы можете создавать URL-адреса, содержащие правильные значения строк запросов taskHub, connection и systemKey, используя API привязки клиента оркестрации , такие как API CreateCheckStatusResponse и CreateHttpManagementPayload в .NET, API createCheckStatusResponse и createHttpManagementPayload в JavaScript и т. д.

В следующих нескольких разделах рассматриваются определенные API HTTP, поддерживаемые расширением, и приведены примеры их использования.

Запуск оркестрации

Начинает выполнять новый экземпляр указанной функции оркестратора.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
functionName URL Имя запускаемой функции оркестратора.
instanceId URL Необязательный параметр. Идентификатор экземпляра оркестрации. Если он не указан, функция оркестратора будет запущена со случайным идентификатором экземпляра.
{content} Содержимое запроса Необязательно. Входные данные функции оркестратора в формате JSON.

Response

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (Accepted) (HTTP 202 (принято)): запланирован запуск указанной функции оркестратора. Заголовок ответа Location содержит URL-адрес для опроса состояния оркестрации.
  • HTTP 400 (Bad request) HTTP 400 (недопустимый запрос): указанная функция оркестратора не существует, указан недопустимый идентификатор экземпляра, либо содержимое запроса не соответствовало допустимому формату JSON.

Далее приведен пример запроса, который запускает функцию оркестратора RestartVMs и включает полезные данные объекта JSON:

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

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

В качестве полезных данных ответа в случае ответов HTTP 202 выступает объект JSON со следующими полями.

Поле Description
id Идентификатор экземпляра оркестрации.
statusQueryGetUri URL-адрес состояния экземпляра оркестрации.
sendEventPostUri URL-адрес вызова события экземпляра оркестрации.
terminatePostUri URL-адрес завершения экземпляра оркестрации.
purgeHistoryDeleteUri URL-адрес "очистки журнала" экземпляра оркестрации.
rewindPostUri URL-адрес "перемотки назад" экземпляра оркестрации (предварительная версия).
suspendPostUri URL-адрес приостановки экземпляра оркестрации.
resumePostUri URL-адрес возобновления экземпляра оркестрации.

Тип данных всех полей — string.

Ниже приведен пример полезных данных ответа для экземпляра оркестрации с идентификатором abc123 (в удобном для чтения формате).

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

Ответ HTTP должен быть совместим с шаблоном объекта-получателя опроса. Он также включает следующие важные заголовки ответа.

  • Location: URL-адрес конечной точки состояния. Этот URL-адрес содержит то же значение, что и поле statusQueryGetUri.
  • Retry-After: количество секунд между операциями опроса. Значение по умолчанию — 10.

Дополнительные сведения о шаблоне асинхронного опроса HTTP см. в документации по отслеживанию асинхронных операций HTTP.

Получение состояния экземпляра

Возвращает состояние определенного экземпляра оркестрации.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
showInput Строка запроса Необязательный параметр. Если задано значение false, входные данные функции не будут включаться в полезные данные ответа.
showHistory Строка запроса Необязательный параметр. Если задано значение true, журнал выполнения оркестрации будет включен в полезные данные ответа.
showHistoryOutput Строка запроса Необязательный параметр. Если задано значение true, выходные данные функции будут включаться в журнал выполнения оркестрации.
createdTimeFrom Строка запроса Необязательный параметр. При указании фильтрует список возвращаемых экземпляров, которые были созданы в момент с указанной меткой времени ISO8601 или после него.
createdTimeTo Строка запроса Необязательный параметр. При указании фильтрует список возвращаемых экземпляров, которые были созданы в момент с указанной меткой времени ISO8601 или перед ним.
runtimeStatus Строка запроса Необязательный параметр. При указании он фильтрует список возвращаемого значения экземпляров на основе их состояния среды выполнения. Чтобы ознакомиться со списком возможных значений состояния среды выполнения, см. статью Запросы к экземплярам.
returnInternalServerErrorOnFailure Строка запроса Необязательный параметр. Если задано значение true, этот API будет возвращать ответ HTTP 500 вместо HTTP 200, если экземпляр находится в состоянии сбоя. Данный параметр предназначен для сценариев автоматического опроса состояния.

Response

Может быть возвращено несколько кодов состояния.

  • HTTP 200 (ОК) (HTTP 200 (все в порядке)): указанный экземпляр находится в завершенном состоянии или состоянии сбоя.
  • HTTP 202 (Accepted) (HTTP 202 (принято)). Указанный экземпляр выполняется.
  • HTTP 400 (Bad Request) (HTTP 400 (неверный запрос)). На определенном экземпляре произошел сбой, или его работа была прервана.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не существует или не был запущен.
  • HTTP 500 (Internal Server Error) (HTTP 500 (внутренняя ошибка сервера)): возвращается, только если returnInternalServerErrorOnFailure присвоено значение true, а указанный экземпляр допустил сбой с необработанным исключением.

Полезные данные ответа для случаев HTTP 200 и HTTP 202 являются объектами JSON со следующими полями:

Поле Тип данных Description
runtimeStatus строка Состояние среды выполнения экземпляра. Возможные значения: Выполняется, В ожидании, Сбой, Отменено, Завершено, Выполнено, Приостановлено.
input JSON Данные JSON, используемые для инициализации экземпляра. Это поле имеет значение null, если для параметра строки запроса showInput задано значение false.
customStatus JSON Данные JSON, используемые для состояния пользовательской оркестрации. Если поле не заполнено, для него устанавливается значение null.
output JSON Выходные данные JSON экземпляра. Это поле имеет значение null, если экземпляр не находится в завершенном состоянии.
createdTime строка Время, когда был создан экземпляр. Использует расширенную нотацию ISO 8601.
lastUpdatedTime строка Время, когда экземпляр был в последний раз сохранен. Использует расширенную нотацию ISO 8601.
historyEvents JSON Массив JSON, содержащий журнал выполнения оркестрации. Это поле имеет значение null, если для параметра строки запроса showHistory не задано значение true.

Ниже приведен пример полезных данных ответа, включающий журнал выполнения оркестрации и выходные данные действия (в удобном для чтения формате).

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

Ответ HTTP 202 также включает заголовок ответа Location, который ссылается на тот же URL-адрес, что и поле statusQueryGetUri, упомянутое ранее.

Получение состояния всех экземпляров

Можно также запросить состояние всех экземпляров, удалив instanceId из запроса "Get instance status". В этом случае основные параметры аналогичны параметру "Get instance status". Также поддерживаются параметры строки запроса для фильтрации.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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}

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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}

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
showInput Строка запроса Необязательный параметр. Если задано значение false, входные данные функции не будут включаться в полезные данные ответа.
showHistoryOutput Строка запроса Необязательный параметр. Если задано значение true, выходные данные функции будут включаться в журнал выполнения оркестрации.
createdTimeFrom Строка запроса Необязательный параметр. При указании фильтрует список возвращаемых экземпляров, которые были созданы в момент с указанной меткой времени ISO8601 или после него.
createdTimeTo Строка запроса Необязательный параметр. При указании фильтрует список возвращаемых экземпляров, которые были созданы в момент с указанной меткой времени ISO8601 или перед ним.
runtimeStatus Строка запроса Необязательный параметр. При указании он фильтрует список возвращаемого значения экземпляров на основе их состояния среды выполнения. Чтобы ознакомиться со списком возможных значений состояния среды выполнения, см. статью Запросы к экземплярам.
instanceIdPrefix Строка запроса Необязательный параметр. Если он указан, выполняется фильтрация списка возвращаемых экземпляров, чтобы в нем присутствовали только экземпляры, у которых идентификатор начинается с указанной строки префикса. Доступно, начиная с версии расширения 2.7.2.
top Строка запроса Необязательный параметр. При указании ограничивает количество экземпляров, возвращаемых запросом.

Response

Вот пример полезных данных ответа, включая состояние оркестрации (в удобном для чтения формате):

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

Примечание.

Эта операция может требовать выполнения очень большого количества операций ввода-вывода службы хранилища Azure, если используется поставщик хранилища Azure по умолчанию, а в таблице "Экземпляры" много строк. Подробнее о таблице экземпляров см. в документации поставщика службы хранилища Azure.

Если имеются другие результаты, в заголовок возвращаемого ответа включается маркер продолжения. Имя заголовка — x-ms-continuation-token.

Внимание

В результате запроса может возвращаться меньше элементов, чем задано ограничением top. Поэтому при получении результатов следует всегда проверять наличие маркера продолжения.

Если в следующем заголовке запроса задать значение маркера продолжения, будет получена очередная страница с результатами. Это имя заголовка запроса также выступает в роли маркера x-ms-continuation-token.

Очистка журнала для одного экземпляра

Удаляет журнал и сопутствующие артефакты для указанного экземпляра оркестрации.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.

Response

Могут возвращаться следующие значения кода состояния HTTP.

  • HTTP 200 (ОК) (HTTP 200 (все в порядке)): журнал экземпляров успешно очищен.
  • HTTP 404 (Not Found) (HTTP 404 (не найден)): указанный экземпляр не существует.

В качестве полезных данных в случае ответа HTTP 200 выступает объект JSON со следующим полем.

Поле Тип данных Description
instancesDeleted integer Количество удаленных экземпляров. В случае с одним экземпляром это значение всегда должно быть равно 1.

Ниже приведен пример полезных данных ответа (в формате, удобном для чтения):

{
    "instancesDeleted": 1
}

Очистка журналов для нескольких экземпляров

Кроме того, можно удалить журналы и сопутствующие артефакты для нескольких экземпляров в центре задач, удалив {instanceId} из запроса "Purge single instance history". Чтобы выборочно очистить журнал экземпляров, используйте фильтры, которые описаны в разделе, посвященном запросу "Get all instances status".

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
createdTimeFrom Строка запроса Фильтрует список удаленных экземпляров, созданных в момент с указанной меткой времени ISO8601 или после него.
createdTimeTo Строка запроса Необязательный параметр. При указании фильтрует список удаленных экземпляров, созданных в момент с указанной меткой времени ISO8601 или перед ним.
runtimeStatus Строка запроса Необязательный параметр. При указании фильтрует список удаленных экземпляров исходя из их состояния среды выполнения. Чтобы ознакомиться со списком возможных значений состояния среды выполнения, см. статью Запросы к экземплярам.

Примечание.

Эта операция может требовать выполнения очень большого количества операций ввода-вывода службы хранилища Azure, если используется поставщик хранилища Azure по умолчанию, а в таблицах "Экземпляры" и/или "Журнал" много строк. Дополнительные сведения об этих таблицах см. в документации по производительности и масштабировании в Устойчивых функциях (Функциях Azure).

Response

Могут возвращаться следующие значения кода состояния HTTP.

  • HTTP 200 (ОК) (HTTP 200 (все в порядке)): журнал экземпляров успешно очищен.
  • HTTP 404 (Not Found) (HTTP 404 (не найдены)): не найдены экземпляры, соответствующие выражению фильтра.

В качестве полезных данных в случае ответа HTTP 200 выступает объект JSON со следующим полем.

Поле Тип данных Description
instancesDeleted integer Количество удаленных экземпляров.

Ниже приведен пример полезных данных ответа (в формате, удобном для чтения):

{
    "instancesDeleted": 250
}

Вызов события

Отправляет сообщение уведомления о событии в выполняющийся экземпляр оркестрации.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
eventName URL Имя события, которое ожидает целевой экземпляр оркестрации.
{content} Содержимое запроса Полезные данные события в формате JSON.

Response

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (Accepted) (HTTP 202 (принято)). Вызванное событие принято в обработку.
  • HTTP 400 (Bad request) (HTTP 400 (неверный запрос)). Содержимое запроса не принадлежит к допустимому типу application/json или не является допустимым файлом JSON.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.
  • HTTP 410 (Gone) (HTTP 410 (потеряно)). Указанный экземпляр выполнен или завершился с ошибкой и не может обрабатывать возникающие события.

Ниже приведен пример запроса, отправляющий строку JSON "incr" в экземпляр, который ожидает событие с именем operation:

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

"incr"

Ответы этого API не содержат какого-либо содержимого.

Завершение экземпляра

Завершите выполнение экземпляра оркестрации.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующий уникальный параметр.

Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
reason Строка запроса Необязательно. Причина завершения работы экземпляра оркестрации.

Response

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (Accepted) (HTTP 202 (принято)). Запрос на завершение принят для обработки.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.
  • HTTP 410 (Gone) (HTTP 410 (потеряно)). Определенный экземпляр выполнен успешно или завершился со сбоем.

Ниже приведен пример запроса, который завершает выполнение экземпляра и указывает причину ошибки:

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

Ответы этого API не содержат какого-либо содержимого.

Приостановка экземпляра

Приостанавливает выполнение экземпляра оркестрации.

Запросить

В версии 2.x среды выполнения Функций формат запроса выглядит следующим образом (для ясности отображается несколько строк):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
reason Строка запроса Необязательно. Причина приостановки экземпляра оркестрации.

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (принято). Запрос на приостановку принят для обработки.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.
  • HTTP 410 (потеряно). Указанный экземпляр выполнен успешно, столкнулся со сбоем или был прерван.

Ответы этого API не содержат какого-либо содержимого.

Возобновление экземпляра

Возобновляет приостановленный экземпляр оркестрации.

Запросить

В версии 2.x среды выполнения Функций формат запроса выглядит следующим образом (для ясности отображается несколько строк):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
reason Строка запроса Необязательно. Причина возобновления экземпляра оркестрации.

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (принято). Запрос на возобновление принят для обработки.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.
  • HTTP 410 (потеряно). Указанный экземпляр выполнен успешно, столкнулся со сбоем или был прерван.

Ответы этого API не содержат какого-либо содержимого.

Экземпляр перемотки (предварительная версия)

Восстанавливает сбойный экземпляр оркестрации в рабочем состоянии путем воспроизведения последних неудачных операций.

Запросить

В версии 1.x среды выполнения Функций Azure формат запроса выглядит следующим образом (для ясности отображается несколько строк).

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

В версии 2.x среды выполнения Функций Azure формат URL-адреса имеет те же параметры, но с немного другим префиксом.

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующий уникальный параметр.

Поле Тип параметра Description
instanceId URL Идентификатор экземпляра оркестрации.
reason Строка запроса Необязательно. Причина перемотки экземпляра оркестрации.

Response

Может быть возвращено несколько кодов состояния.

  • HTTP 202 (принято). Запрос на перемотку принят для обработки.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.
  • HTTP 410 (потеряно). Определенный экземпляр выполнен успешно или был прерван.

Ниже приведен пример запроса, который перематывает сбойный экземпляр и указывает причину исправления:

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

Ответы этого API не содержат какого-либо содержимого.

Сущность сигнала

Отправляет одностороннее сообщение операции для устойчивой сущности. Если сущность не существует, она будет создана автоматически.

Примечание.

Устойчивые сущности доступны начиная с версии 2.0. расширения "Устойчивые функции".

Запросить

Формат HTTP-запроса выглядит следующим образом (для ясности показаны несколько строк).

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
entityName URL Имя (тип) сущности.
entityKey URL Ключ (уникальный идентификатор) сущности.
op Строка запроса Необязательно. Имя вызываемой операции, определяемой пользователем.
{content} Содержимое запроса Полезные данные события в формате JSON.

Далее приведен пример запроса, который отправляет определяемое пользователем сообщение "Add" для сущности Counter с именем steps. Содержимое сообщения — это значение 5. Если сущность еще не существует, она будет создана при помощи следующего запроса.

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

5

Примечание.

По умолчанию в случае сущностей на основе классов в .NET указание значения op для delete приведет к удалению состояния сущности. Если сущность определяет операцию с именем delete, вместо нее будет вызываться определяемая пользователем операция.

Response

На эту операцию есть ряд возможных ответов.

  • HTTP 202 (Accepted) (HTTP 202 (принято)): операция сигнала была принята для асинхронной обработки.
  • HTTP 400 (Bad request) (HTTP 400 (неверный запрос)): содержимое запроса не относится к типу application/json, не соответствует допустимому формату JSON или имеет недопустимое значение entityKey.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)): указанное имя entityName не найдено.

В ответе на успешный HTTP-запрос нет никакого содержимого. В содержимом ответа на неудачный HTTP-запрос могут содержаться сведения об ошибке в формате JSON.

Get entity

Возвращает состояние указанной сущности.

Запросить

Формат HTTP-запроса выглядит следующим образом (для ясности показаны несколько строк).

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

Response

На эту операцию имеется два возможных ответа.

  • HTTP 200 (ОК) (HTTP 200 (все в порядке)): указанная сущность существует.
  • HTTP 404 (Not Found) (HTTP 404 (не найдена)): указанная сущность не найдена.

В качестве содержимого успешного ответа выступает сериализованное в формате JSON состояние сущности.

Пример

В следующем примере HTTP-запрос получает состояние существующей сущности Counter с именем steps.

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

Если бы сущность Counter просто содержала несколько шагов, сохраненных в поле currentValue, содержимое ответа может выглядеть следующим образом (формат выбран в целях удобочитаемости).

{
    "currentValue": 5
}

Отображение сущностей

Можно запросить несколько сущностей, указав имя сущности или дату последней операции.

Запросить

Формат HTTP-запроса выглядит следующим образом (для ясности показаны несколько строк).

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:

Поле Тип параметра Description
entityName URL Необязательно. При указании фильтрует список возвращенных сущностей по имени сущности (без учета регистра).
fetchState Строка запроса Необязательный параметр. Если задано значение true, состояние сущности будет включено в полезные данные ответа.
lastOperationTimeFrom Строка запроса Необязательный параметр. При указании фильтрует список возвращенных сущностей, которые обрабатывали операции после наступления момента с заданной меткой времени ISO8601.
lastOperationTimeTo Строка запроса Необязательный параметр. При указании фильтрует список возвращенных сущностей, которые обрабатывали операции перед наступлением момента с заданной меткой времени ISO8601.
top Строка запроса Необязательный параметр. При указании ограничивает количество сущностей, возвращаемых запросом.

Response

Успешный ответ HTTP 200 содержит массив сущностей, сериализованный в формате JSON, а также при необходимости сведения о состоянии каждой сущности.

По умолчанию операция возвращает первые 100 сущностей, соответствующих критериям запроса. Вызывающий объект может указать значение параметра строки запроса для top, чтобы вернуть другое максимальное число результатов. Если число результатов больше числа возвращенных результатов, маркер продолжения также возвращается в заголовке ответа. Имя заголовка — x-ms-continuation-token.

Если в следующем заголовке запроса задать значение маркера продолжения, будет получена очередная страница с результатами. Это имя заголовка запроса также выступает в роли маркера x-ms-continuation-token.

Пример перечисления всех сущностей

В следующем примере HTTP-запрос служит для перечисления всех сущностей в центре задач.

GET /runtime/webhooks/durabletask/entities

Ответ в формате JSON может выглядеть следующим образом (формат выбран в целях удобочитаемости).

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

Пример фильтрации списка сущностей

В следующем примере HTTP-запрос служит для перечисления только первых двух сущностей с типом counter, а также получения сведений об их состоянии.

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

Ответ в формате JSON может выглядеть следующим образом (формат выбран в целях удобочитаемости).

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

Следующие шаги

Узнайте, как использовать Application Insights для мониторинга Устойчивых функций