Перейти к содержимому
Документация

Надёжные функции

Durable Functions (надёжные функции) дают развёрнутой функции постоянный идентификатор, по которому её можно перезапустить: вы запускаете её как именованный инстанс, а платформа записывает этот инстанс в Postgres, поэтому его статус, результат и историю можно смотреть по id, а повторные запуски не создают дублей. Это механизм надёжности вокруг одного запуска функции, а не язык описания процессов. Для многошаговых сценариев с ветвлениями, fan-out, расписаниями и подтверждениями человека используйте графовые пайплайны (см. страницу «Пайплайны»).

Надёжный инстанс выполняет одну обычную развёрнутую функцию до завершения. Её возвращаемое значение становится результатом инстанса, а сам инстанс завершается со статусом COMPLETED (или FAILED, если обработчик выбросил ошибку). Поскольку запуск записывается в Postgres до выполнения функции, инстанс переживает перезапуск платформы — она запускает его заново из надёжной очереди, а не теряет работу.

Запуск надёжного инстанса#

Из функции на Node.js встроенный клиент global.durable запускает другую развёрнутую функцию как надёжный инстанс через startNew(functionName, instanceId?, input?). Цель — обычный обработчик, не генератор. Передайте instanceId, чтобы сделать запуск идемпотентным: второй startNew с тем же id вернёт существующий инстанс, а не создаст дубль. То, что вы передаёте в input, становится event этой функции.

durable.jsjs
// process-order.js — an ORDINARY deployed function (Node.js). Its return value
// becomes the durable instance output. Deploy it like any other function.
exports.handler = async (event, context) => {
  const order = event; // the input you passed to startNew()
  const charged = await chargeCard(order);
  await reserveStock(order);
  return { ok: true, orderId: order.id, chargeId: charged.id };
};

// starter.js — a second Node.js function launches "process-order" as a durable,
// idempotent, restartable instance and follows it by id. global.durable is
// injected into the Node runtime only.
exports.handler = async (event, context) => {
  // startNew(functionName, instanceId?, input?). Passing an instanceId makes the
  // start idempotent — a duplicate start with the same id returns the same instance.
  const { instanceId } = await global.durable.startNew(
    'process-order',
    `order-${event.orderId}`,
    { id: event.orderId, amount: event.amount },
  );

  // Optional: block up to N ms for the instance to finish (resolves on COMPLETED,
  // throws on FAILED/TERMINATED/timeout). Otherwise poll global.durable.getStatus(id).
  const status = await global.durable.waitForCompletion(instanceId, 30000);
  return { instanceId, state: status.status, output: status.output };
};

Клиент управления (только Node.js)#

global.durable встроен в среду выполнения Node.js — функции на Python и Go его не получают. Он предоставляет:

  • startNew(name, instanceId?, input?) — запустить именованную функцию как инстанс; резолвится в { instanceId, … }.
  • getStatus(instanceId) — прочитать инстанс: status, output, createdAt, lastUpdatedAt и историю событий history (или null, если инстанса нет).
  • waitForCompletion(instanceId, timeoutMs?) — опрашивать до статуса COMPLETED и вернуть статус; бросает ошибку при FAILED, TERMINATED или таймауте.
  • terminate(instanceId, reason?) — остановить инстанс и пометить его TERMINATED.

HTTP API#

Те же операции доступны по HTTP для вызова не из Node-функции. POST /durable/orchestrations/{name}/start возвращает 202 с { instanceId, statusQueryGetUri, terminatePostUri, … }, а GET /durable/orchestrations/{instanceId}/status возвращает инстанс. Эти маршруты авторизуются через вашу сессию или Bearer-PAT (области jobs:read / jobs:write); global.durable обращается к ним за вас со служебным токеном.

Надёжные инстансы, задачи или пайплайны#

Выбирайте надёжный инстанс, когда нужен один фоновый запуск с постоянным id — идемпотентный старт, статус для опроса и устойчивость к перезапускам. Выбирайте фоновую задачу (см. «Фоновые задачи»), когда нужна работа по принципу fire-and-forget с автоматическими повторными попытками, нарастающей задержкой и очередью недоставленных (DLQ). Выбирайте графовый пайплайн, когда несколько функций образуют процесс с ветвлениями, fan-out, запусками по расписанию или шагом подтверждения человеком (узел Human gate). Все три используют одни и те же функции на одной очереди в Postgres.