Справочник по API HTTPHTTP API reference

Расширение Durable Functions предоставляет набор встроенных APИ HTTP, которые могут быть использованы entitiesдля выполнения задач управления на оркестровке, сущностяхи концентратах задач.The Durable Functions extension exposes a set of built-in HTTP APIs that can be used to perform management tasks on orchestrations, entities, and task hubs. Эти HTTP-AIS — это веб-крючки расширения, которые авторизованы хостом Azure Functions, но обрабатываются непосредственно расширением durable Functions.These HTTP APIs are extensibility webhooks that are authorized by the Azure Functions host but handled directly by the Durable Functions extension.

Все HTTP-aIS, реализованные расширением, требуют следующих параметров.All HTTP APIs implemented by the extension require the following parameters. Тип данных всех параметров — string.The data type of all parameters is string.

ПараметрParameter Тип параметраParameter Type ОписаниеDescription
taskHub Строка запросаQuery string Имя центра задач.The name of the task hub. Если не указано, предполагается имя центра задач текущего приложения-функции.If not specified, the current function app's task hub name is assumed.
connection Строка запросаQuery string Имя строки подключения для учетной записи хранения.The name of the connection string for the storage account. Если не указано, предполагается строка подключения по умолчанию для приложения-функции.If not specified, the default connection string for the function app is assumed.
systemKey Строка запросаQuery string Ключ авторизации, необходимый для вызова API.The authorization key required to invoke the API.

systemKey— ключ авторизации, авторизуемый хостом Azure Functions.systemKey is an authorization key autogenerated by the Azure Functions host. В частности, он предоставляет доступ к API расширения устойчивых задач и им можно управлять так же, как и другими ключами авторизации.It specifically grants access to the Durable Task extension APIs and can be managed the same way as other authorization keys. Можно создавать URL-адреса, taskHubсодержащие connectionправильные значения строки, и systemKey зажимать CreateCheckStatusResponse значения CreateHttpManagementPayload строки, используя apIs createHttpManagementPayload связывания клиента, такие как AI и AI в .NET, или AI createCheckStatusResponse и AI в JavaScript.You can generate URLs that contain the correct taskHub, connection, and systemKey query string values using orchestration client binding APIs, such as the CreateCheckStatusResponse and CreateHttpManagementPayload APIs in .NET, or the createCheckStatusResponse and createHttpManagementPayload APIs in JavaScript.

В следующих нескольких разделах рассматриваются определенные API HTTP, поддерживаемые расширением, и приведены примеры их использования.The next few sections cover the specific HTTP APIs supported by the extension and provide examples of how they can be used.

Начало оркестровкиStart orchestration

Начинает выполнять новый экземпляр указанной функции оркестратора.Starts executing a new instance of the specified orchestrator function.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
functionName URL-адресURL Название функции оркестратора для начала.The name of the orchestrator function to start.
instanceId URL-адресURL Необязательный параметр.Optional parameter. Идентификатор экземпляра оркестрации.The ID of the orchestration instance. Если не указано, функция оркестратора начнется со случайного идентификатора экземпляра.If not specified, the orchestrator function will start with a random instance ID.
{content} Содержимое запросаRequest content Необязательный параметр.Optional. Ввод функции оркестранта JSON.The JSON-formatted orchestrator function input.

ОтветResponse

Может быть возвращено несколько кодов состояния.Several possible status code values can be returned.

  • HTTP 202 (Принято): Указанная функция оркестратора была запланирована для запуска.HTTP 202 (Accepted): The specified orchestrator function was scheduled to start running. Заголовок Location ответа содержит URL для опроса статуса оркестровки.The Location response header contains a URL for polling the orchestration status.
  • HTTP 400 (Плохой запрос): Указанная функция оркестратора не существует, указанный идентификатор экземпляра не действителен, или содержимое запроса не было действительным JSON.HTTP 400 (Bad request): The specified orchestrator function doesn't exist, the specified instance ID was not valid, or request content was not valid JSON.

Ниже приводится пример запроса, который запускает функцию оркестратора и включает полезную RestartVMs нагрузку объекта JSON:The following is an example request that starts a RestartVMs orchestrator function and includes JSON object payload:

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 со следующими полями:The response payload for the HTTP 202 cases is a JSON object with the following fields:

ПолеField ОписаниеDescription
id Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
statusQueryGetUri URL-адрес состояния экземпляра оркестрации.The status URL of the orchestration instance.
sendEventPostUri URL-адрес вызова события экземпляра оркестрации.The "raise event" URL of the orchestration instance.
terminatePostUri URL-адрес завершения экземпляра оркестрации.The "terminate" URL of the orchestration instance.
purgeHistoryDeleteUri URL-адрес "История очистки" экземпляра оркестровки.The "purge history" URL of the orchestration instance.
rewindPostUri (предварительный просмотр) URL-адрес "перемотка назад" экземпляра оркестровки.(preview) The "rewind" URL of the orchestration instance.

Тип данных всех полей — string.The data type of all fields is string.

Вот пример полезной нагрузки ответа для abc123 экземпляра оркестровки с идентификатором (отформатированным для читаемости):Here is an example response payload for an orchestration instance with abc123 as its ID (formatted for readability):

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

Ответ HTTP предназначен для совместимости с шаблоном опроса потребителей.The HTTP response is intended to be compatible with the Polling Consumer Pattern. Он также включает в себя следующие заметные заголовки ответов:It also includes the following notable response headers:

  • Расположение: URL конечной точки статуса.Location: The URL of the status endpoint. Этот URL-адрес содержит statusQueryGetUri то же значение, что и поле.This URL contains the same value as the statusQueryGetUri field.
  • Повторная попытка-После: количество секунд, чтобы ждать между операциями опроса.Retry-After: The number of seconds to wait between polling operations. Значение по умолчанию — 10.The default value is 10.

Для получения дополнительной информации об асинхронном шаблоне опроса HTTP см. HTTP async operation trackingFor more information on the asynchronous HTTP polling pattern, see the HTTP async operation tracking documentation.

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

Возвращает состояние определенного экземпляра оркестрации.Gets the status of a specified orchestration instance.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
showInput Строка запросаQuery string Необязательный параметр.Optional parameter. При установке falseна, ввод функции не будет включен в полезную нагрузку ответа.If set to false, the function input will not be included in the response payload.
showHistory Строка запросаQuery string Необязательный параметр.Optional parameter. Если задано значение true, журнал выполнения оркестрации будет включен в полезные данные ответа.If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput Строка запросаQuery string Необязательный параметр.Optional parameter. При установке trueна , выходы функции будут включены в историю выполнения оркестровки.If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных экземпляров, созданных на или после данной метки времени ISO8601.When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных экземпляров, которые были созданы на или до данной метки времени ISO8601.When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Строка запросаQuery string Необязательный параметр.Optional parameter. При указании он фильтрует список возвращаемого значения экземпляров на основе их состояния среды выполнения.When specified, filters the list of returned instances based on their runtime status. Чтобы увидеть список возможных значений состояния Querying instances времени выполнения, см.To see the list of possible runtime status values, see the Querying instances article.

ОтветResponse

Может быть возвращено несколько кодов состояния.Several possible status code values can be returned.

  • HTTP 200 (ОК) (HTTP 200 (ОК)). Указанный экземпляр находится в завершенном состоянии.HTTP 200 (OK): The specified instance is in a completed state.
  • HTTP 202 (Accepted) (HTTP 202 (принято)). Указанный экземпляр выполняется.HTTP 202 (Accepted): The specified instance is in progress.
  • HTTP 400 (Bad Request) (HTTP 400 (неверный запрос)). На определенном экземпляре произошел сбой, или его работа была прервана.HTTP 400 (Bad Request): The specified instance failed or was terminated.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не существует или не был запущен.HTTP 404 (Not Found): The specified instance doesn't exist or has not started running.
  • HTTP 500 (внутренняя ошибка сервера): сбой указанного экземпляра с необработанным исключением.HTTP 500 (Internal Server Error): The specified instance failed with an unhandled exception.

Полезные данные ответа для случаев HTTP 200 и HTTP 202 являются объектами JSON со следующими полями:The response payload for the HTTP 200 and HTTP 202 cases is a JSON object with the following fields:

ПолеField Тип данныхData type ОписаниеDescription
runtimeStatus строкаstring Состояние среды выполнения экземпляра.The runtime status of the instance. Возможные значения: Running, Pending, Failed, Canceled, Terminated, Completed.Values include Running, Pending, Failed, Canceled, Terminated, Completed.
input JSONJSON Данные JSON, используемые для инициализации экземпляра.The JSON data used to initialize the instance. Это поле имеет значение null, если для параметра строки запроса showInput задано значение false.This field is null if the showInput query string parameter is set to false.
customStatus JSONJSON Данные JSON, используемые для состояния пользовательской оркестрации.The JSON data used for custom orchestration status. Если поле не заполнено, для него устанавливается значение null.This field is null if not set.
output JSONJSON Выходные данные JSON экземпляра.The JSON output of the instance. Это поле имеет значение null, если экземпляр не находится в завершенном состоянии.This field is null if the instance is not in a completed state.
createdTime строкаstring Время, когда был создан экземпляр.The time at which the instance was created. Использует расширенную нотацию ISO 8601.Uses ISO 8601 extended notation.
lastUpdatedTime строкаstring Время, когда экземпляр был в последний раз сохранен.The time at which the instance last persisted. Использует расширенную нотацию ISO 8601.Uses ISO 8601 extended notation.
historyEvents JSONJSON Массив JSON, содержащий журнал выполнения оркестрации.A JSON array containing the orchestration execution history. Это поле имеет значение null, если для параметра строки запроса showHistory не задано значение true.This field is null unless the showHistory query string parameter is set to true.

Ниже приведен пример полезных данных ответа, включающий журнал выполнения оркестрации и выходные данные действия (в удобном для чтения формате).Here is an example response payload including the orchestration execution history and activity outputs (formatted for readability):

{
  "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, упомянутое ранее.The HTTP 202 response also includes a Location response header that references the same URL as the statusQueryGetUri field mentioned previously.

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

Вы также можете запросить статус всех экземпляров, удалив instanceId запрос «Получить статус экземпляра».You can also query the status of all instances by removing the instanceId from the 'Get instance status' request. В этом случае основные параметры совпадают со статусом «Получить экземпляр».In this case, the basic parameters are the same as the 'Get instance status'. Параметры строки запроса для фильтрации также поддерживаются.Query string parameters for filtering are also supported.

Следует помнить, что connection и code являются дополнительными.One thing to remember is that connection and code are optional. Если у вас есть анонимный code auth на функцию, то не требуется.If you have anonymous auth on the function, then code isn't required. Если вы не хотите использовать другую строку подключения к хранилищу, кроме определенной в настройках приложения AzureWebWebJobsStorage, то можно безопасно игнорировать параметр строки запроса подключения.If you don't want to use a different storage connection string other than defined in the AzureWebJobsStorage app setting, then you can safely ignore the connection query string parameter.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
showInput Строка запросаQuery string Необязательный параметр.Optional parameter. При установке falseна, ввод функции не будет включен в полезную нагрузку ответа.If set to false, the function input will not be included in the response payload.
showHistory Строка запросаQuery string Необязательный параметр.Optional parameter. Если задано значение true, журнал выполнения оркестрации будет включен в полезные данные ответа.If set to true, the orchestration execution history will be included in the response payload.
showHistoryOutput Строка запросаQuery string Необязательный параметр.Optional parameter. При установке trueна , выходы функции будут включены в историю выполнения оркестровки.If set to true, the function outputs will be included in the orchestration execution history.
createdTimeFrom Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных экземпляров, созданных на или после данной метки времени ISO8601.When specified, filters the list of returned instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных экземпляров, которые были созданы на или до данной метки времени ISO8601.When specified, filters the list of returned instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Строка запросаQuery string Необязательный параметр.Optional parameter. При указании он фильтрует список возвращаемого значения экземпляров на основе их состояния среды выполнения.When specified, filters the list of returned instances based on their runtime status. Чтобы увидеть список возможных значений состояния Querying instances времени выполнения, см.To see the list of possible runtime status values, see the Querying instances article.
top Строка запросаQuery string Необязательный параметр.Optional parameter. При указании ограничивает количество экземпляров, возвращенных запросом.When specified, limits the number of instances returned by the query.

ОтветResponse

Вот пример полезных данных ответа, включая состояние оркестрации (в удобном для чтения формате):Here is an example of response payloads including the orchestration status (formatted for readability):

[
    {
        "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, если в таблице экземпляров много строк.This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances table. Дополнительные сведения о таблице экземпляров см. в документации по производительности и масштабируемости в устойчивых функциях (Функциях Azure).More details on Instance table can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

При наличии дополнительных результатов в заголовке ответа возвращается маркер продолжения.If more results exist, a continuation token is returned in the response header. Имя заголовка — x-ms-continuation-token.The name of the header is x-ms-continuation-token.

Если в следующем заголовке запроса значение маркера продолжения будет установлено, можно получить следующую страницу результатов.If you set continuation token value in the next request header, you can get the next page of results. Это имя заголовка запроса x-ms-continuation-tokenтакже.This name of the request header is also x-ms-continuation-token.

Очистка истории одного экземпляраPurge single instance history

Удаляет историю и связанные с ней артефакты для указанного экземпляра оркестровки.Deletes the history and related artifacts for a specified orchestration instance.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.

ОтветResponse

Следующие значения кода статуса HTTP могут быть возвращены.The following HTTP status code values can be returned.

  • HTTP 200 (OK): История экземпляра была успешно очищена.HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (не найдено): Указанный экземпляр не существует.HTTP 404 (Not Found): The specified instance doesn't exist.

Полезная нагрузка отклика для случая HTTP 200 — объект JSON со следующим полем:The response payload for the HTTP 200 case is a JSON object with the following field:

ПолеField Тип данныхData type ОписаниеDescription
instancesDeleted Целое числоinteger Количество исключенных экземпляров.The number of instances deleted. Для единственного экземпляра это значение 1всегда должно быть .For the single instance case, this value should always be 1.

Ниже приведен пример полезных данных ответа (в формате, удобном для чтения):Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 1
}

Очистка нескольких историй экземпляровPurge multiple instance histories

Можно также удалить историю и связанные с ней артефакты {instanceId} для нескольких экземпляров в концентраторе задач, удалив запрос «Очистка отдельной истории экземпляра».You can also delete the history and related artifacts for multiple instances within a task hub by removing the {instanceId} from the 'Purge single instance history' request. Для выборочной очистки истории экземпляров используйте те же фильтры, описанные в запросе «Получить все статусы экземпляров».To selectively purge instance history, use the same filters described in the 'Get all instances status' request.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
createdTimeFrom Строка запросаQuery string Фильтрует список удаленных экземпляров, созданных на или после данной метки времени ISO8601.Filters the list of purged instances that were created at or after the given ISO8601 timestamp.
createdTimeTo Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список удаленных экземпляров, созданных на или до данной метки времени ISO8601.When specified, filters the list of purged instances that were created at or before the given ISO8601 timestamp.
runtimeStatus Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список удаленных экземпляров в зависимости от состояния времени выполнения.When specified, filters the list of purged instances based on their runtime status. Чтобы увидеть список возможных значений состояния Querying instances времени выполнения, см.To see the list of possible runtime status values, see the Querying instances article.

Примечание

Эта операция может быть очень дорогостоящей с точки зрения ввоза/вывода Azure Storage I/O, если в таблицах Instances and/or History много строк.This operation can be very expensive in terms of Azure Storage I/O if there are a lot of rows in the Instances and/or History tables. Более подробную информацию об этих таблицах можно найти в документации «Производительность и масштабирование» в документации «Прочная функции» (Azure Functions).More details on these tables can be found in the Performance and scale in Durable Functions (Azure Functions) documentation.

ОтветResponse

Следующие значения кода статуса HTTP могут быть возвращены.The following HTTP status code values can be returned.

  • HTTP 200 (OK): История экземпляра была успешно очищена.HTTP 200 (OK): The instance history has been purged successfully.
  • HTTP 404 (не найдено): Не было найдено экземпляров, которые соответствовали бы выражению фильтра.HTTP 404 (Not Found): No instances were found that match the filter expression.

Полезная нагрузка отклика для случая HTTP 200 — объект JSON со следующим полем:The response payload for the HTTP 200 case is a JSON object with the following field:

ПолеField Тип данныхData type ОписаниеDescription
instancesDeleted Целое числоinteger Количество исключенных экземпляров.The number of instances deleted.

Ниже приведен пример полезных данных ответа (в формате, удобном для чтения):Here is an example response payload (formatted for readability):

{
    "instancesDeleted": 250
}

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

Отправляет сообщение уведомления о событии в выполняющийся экземпляр оркестрации.Sends an event notification message to a running orchestration instance.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
eventName URL-адресURL Имя события, которое ожидает целевой экземпляр оркестрации.The name of the event that the target orchestration instance is waiting on.
{content} Содержимое запросаRequest content Полезные данные события в формате JSON.The JSON-formatted event payload.

ОтветResponse

Может быть возвращено несколько кодов состояния.Several possible status code values can be returned.

  • HTTP 202 (Accepted) (HTTP 202 (принято)). Вызванное событие принято в обработку.HTTP 202 (Accepted): The raised event was accepted for processing.
  • HTTP 400 (Bad request) (HTTP 400 (неверный запрос)). Содержимое запроса не принадлежит к допустимому типу application/json или не является допустимым файлом JSON.HTTP 400 (Bad request): The request content was not of type application/json or was not valid JSON.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone) (HTTP 410 (потеряно)). Указанный экземпляр выполнен или завершился с ошибкой и не может обрабатывать возникающие события.HTTP 410 (Gone): The specified instance has completed or failed and cannot process any raised events.

Ниже приведен пример запроса, отправляющий строку JSON "incr" в экземпляр, который ожидает событие с именем operation:Here is an example request that sends the JSON string "incr" to an instance waiting for an event named operation:

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

"incr"

Ответы этого API не содержат какого-либо содержимого.The responses for this API do not contain any content.

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

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

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующий уникальный параметр.Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

ПолеField Тип параметраParameter Type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
reason Строка запросаQuery string Необязательный параметр.Optional. Причина завершения работы экземпляра оркестрации.The reason for terminating the orchestration instance.

ОтветResponse

Может быть возвращено несколько кодов состояния.Several possible status code values can be returned.

  • HTTP 202 (Accepted) (HTTP 202 (принято)). Запрос на завершение принят для обработки.HTTP 202 (Accepted): The terminate request was accepted for processing.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (Gone) (HTTP 410 (потеряно)). Определенный экземпляр выполнен успешно или завершился со сбоем.HTTP 410 (Gone): The specified instance has completed or failed.

Ниже приведен пример запроса, который завершает выполнение экземпляра и указывает причину ошибки:Here is an example request that terminates a running instance and specifies a reason of buggy:

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

Ответы этого API не содержат какого-либо содержимого.The responses for this API do not contain any content.

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

Восстанавливает сбойный экземпляр оркестрации в рабочем состоянии путем воспроизведения последних неудачных операций.Restores a failed orchestration instance into a running state by replaying the most recent failed operations.

ЗапросRequest

Для версии 1.x времени выполнения функций запрос отформатирован следующим образом (для ясности отображаются несколько строк):For version 1.x of the Functions runtime, the request is formatted as follows (multiple lines are shown for clarity):

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

В версии 2.x времени выполнения функций формат URL имеет все те же параметры, но с несколько иной приставкой:In version 2.x of the Functions runtime, the URL format has all the same parameters but with a slightly different prefix:

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующий уникальный параметр.Request parameters for this API include the default set mentioned previously as well as the following unique parameter.

ПолеField Тип параметраParameter Type ОписаниеDescription
instanceId URL-адресURL Идентификатор экземпляра оркестрации.The ID of the orchestration instance.
reason Строка запросаQuery string Необязательный параметр.Optional. Причина перемотки экземпляра оркестрации.The reason for rewinding the orchestration instance.

ОтветResponse

Может быть возвращено несколько кодов состояния.Several possible status code values can be returned.

  • HTTP 202 (принято). Запрос на перемотку принят для обработки.HTTP 202 (Accepted): The rewind request was accepted for processing.
  • HTTP 404 (Not Found) (HTTP 404 (не найдено)). Указанный экземпляр не найден.HTTP 404 (Not Found): The specified instance was not found.
  • HTTP 410 (потеряно). Определенный экземпляр выполнен успешно или был прерван.HTTP 410 (Gone): The specified instance has completed or was terminated.

Ниже приведен пример запроса, который перематывает сбойный экземпляр и указывает причину исправления:Here is an example request that rewinds a failed instance and specifies a reason of fixed:

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

Ответы этого API не содержат какого-либо содержимого.The responses for this API do not contain any content.

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

Отправляет сообщение операции в одну сторону в долговременное сообщение entity.Sends a one-way operation message to a Durable Entity. Если сущность не существует, она будет создана автоматически.If the entity doesn't exist, it will be created automatically.

Примечание

Долгосрочные сущности доступны начиная с функций durable 2.0.Durable entities are available starting in Durable Functions 2.0.

ЗапросRequest

Запрос HTTP отформатирован следующим образом (для ясности отображаются несколько строк):The HTTP request is formatted as follows (multiple lines are shown for clarity):

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
entityName URL-адресURL Имя (тип) сущности.The name (type) of the entity.
entityKey URL-адресURL Ключ (уникальный идентификатор) сущности.The key (unique ID) of the entity.
op Строка запросаQuery string Необязательный параметр.Optional. Имя операции, определяемой пользователем, чтобы вызвать.The name of the user-defined operation to invoke.
{content} Содержимое запросаRequest content Полезные данные события в формате JSON.The JSON-formatted event payload.

Вот пример запроса, который отправляет определенное пользователем Counter сообщение steps"Добавить" объекту с именем.Here is an example request that sends a user-defined "Add" message to a Counter entity named steps. Содержание сообщения является значением 5.The content of the message is the value 5. Если сущность еще не существует, она будет создана по этому запросу:If the entity does not already exist, it will be created by this request:

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

5

Примечание

По умолчанию с объектами, основанными на классах в .NET,указание op значения delete будет удалено состояние объекта.By default with class-based entities in .NET, specifying the op value of delete will delete the state of an entity. Однако если сущность deleteопределяет имя операции, то вместо этого будет вызвана операция с определенным пользователем.If the entity defines an operation named delete, however, that user-defined operation will be invoked instead.

ОтветResponse

Эта операция имеет несколько возможных ответов:This operation has several possible responses:

  • HTTP 202 (Принято): Операция сигнала была принята для асинхронной обработки.HTTP 202 (Accepted): The signal operation was accepted for asynchronous processing.
  • HTTP 400 (Плохой запрос): Содержимое запроса не было типа, application/json entityKey не было действительным JSON, или имело недействительное значение.HTTP 400 (Bad request): The request content was not of type application/json, was not valid JSON, or had an invalid entityKey value.
  • HTTP 404 (не найдено): Указанный entityName не найден.HTTP 404 (Not Found): The specified entityName was not found.

Успешный запрос HTTP не содержит содержимого в ответе.A successful HTTP request does not contain any content in the response. Неудавшийся запрос HTTP может содержать информацию об ошибках, отстекаемых JSON, в содержимом ответа.A failed HTTP request may contain JSON-formatted error information in the response content.

Получить сущностьGet entity

Получает состояние указанного объекта.Gets the state of the specified entity.

ЗапросRequest

Запрос HTTP отформатирован следующим образом (для ясности отображаются несколько строк):The HTTP request is formatted as follows (multiple lines are shown for clarity):

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

ОтветResponse

Эта операция имеет два возможных ответа:This operation has two possible responses:

  • HTTP 200 (OK): Указанная сущность существует.HTTP 200 (OK): The specified entity exists.
  • HTTP 404 (не найдено): Указанная сущность не найдена.HTTP 404 (Not Found): The specified entity was not found.

Успешный ответ содержит JSON-серийное состояние сущности в качестве его содержимого.A successful response contains the JSON-serialized state of the entity as its content.

ПримерExample

В следующем примере запрос HTTP Counter получает stepsсостояние существующей сущности под названием:The following example HTTP request gets the state of an existing Counter entity named steps:

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

Если Counter объект просто содержал ряд шагов, currentValue сохраненных в поле, содержимое ответа может выглядеть следующим (отформатировано для читаемости):If the Counter entity simply contained a number of steps saved in a currentValue field, the response content might look like the following (formatted for readability):

{
    "currentValue": 5
}

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

Вы можете запросить несколько сущностей по имени сущности или к последней дате операции.You can query for multiple entities by the entity name or by the last operation date.

ЗапросRequest

Запрос HTTP отформатирован следующим образом (для ясности отображаются несколько строк):The HTTP request is formatted as follows (multiple lines are shown for clarity):

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

Параметры запроса для этого API включают набор по умолчанию, упомянутый ранее, а также следующие уникальные параметры:Request parameters for this API include the default set mentioned previously as well as the following unique parameters:

ПолеField Тип параметраParameter type ОписаниеDescription
entityName URL-адресURL Необязательный параметр.Optional. При указании фильтрует список возвращенных сущностей по имени сущности (нечувствительным к делу).When specified, filters the list of returned entities by their entity name (case-insensitive).
fetchState Строка запросаQuery string Необязательный параметр.Optional parameter. При установке trueна, состояние сущности будет включено в полезную нагрузку ответа.If set to true, the entity state will be included in the response payload.
lastOperationTimeFrom Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных сущностей, обрабатывающих операции после данной метки времени ISO8601.When specified, filters the list of returned entities that processed operations after the given ISO8601 timestamp.
lastOperationTimeTo Строка запросаQuery string Необязательный параметр.Optional parameter. При указании фильтрует список возвращенных сущностей, которые обрабатывали операции до данной метки времени ISO8601.When specified, filters the list of returned entities that processed operations before the given ISO8601 timestamp.
top Строка запросаQuery string Необязательный параметр.Optional parameter. При указании ограничено количество объектов, возвращенных запросом.When specified, limits the number of entities returned by the query.

ОтветResponse

Успешный ответ HTTP 200 содержит jSON-серийный массив сущностей и, по желанию, состояние каждой сущности.A successful HTTP 200 response contains a JSON-serialized array of entities and optionally the state of each entity.

По умолчанию операция возвращает первые 100 сущностей, которые соответствуют критериям запроса.By default the operation returns the first 100 entities that match the query criteria. Вызывающее может указать значение top параметра строки запроса для возврата другого максимального количества результатов.The caller can specify a query string parameter value for top to return a different maximum number of results. Если больше результатов существует за пределами того, что возвращается, токен продолжения также возвращается в заголовке ответа.If more results exist beyond what is returned, a continuation token is also returned in the response header. Имя заголовка — x-ms-continuation-token.The name of the header is x-ms-continuation-token.

Если в следующем заголовке запроса значение маркера продолжения будет установлено, можно получить следующую страницу результатов.If you set continuation token value in the next request header, you can get the next page of results. Это имя заголовка запроса x-ms-continuation-tokenтакже.This name of the request header is also x-ms-continuation-token.

Пример - перечислите все сущностиExample - list all entities

В следующем примере запрос HTTP перечисляет все объекты в концентраторе задач:The following example HTTP request lists all entities in the task hub:

GET /runtime/webhooks/durabletask/entities

Ответ JSON может выглядеть следующим (отформатированным для читаемости):The response JSON may look like the following (formatted for readability):

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

Пример - фильтрация списка объектовExample - filtering the list of entities

В следующем примере запрос HTTP перечисляет counter только первые два сущности типа, а также получает их состояние:The following example HTTP request lists just the first two entities of type counter and also fetches their state:

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

Ответ JSON может выглядеть следующим (отформатированным для читаемости):The response JSON may look like the following (formatted for readability):

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

Дальнейшие действияNext steps