gRPC API сервиса отложенной обработки операций


Исходная схема: apis_ru/tinkoff/cloud/longrunning/v1/longrunning.proto

Services

Operations

Имя методаТип запросаТип ответаОписание
GetOperationGetOperationRequestOperationВозвращает информацию о состоянии операции по её идентификатору.
Может вернуть gRPC ошибку со статусом NotFound, если запрошенная операция не существует.
WaitOperationWaitOperationRequestOperationДожидается первого изменения состояния операции с момента отправки запроса и возвращает её новое состояние.
ListOperationsListOperationsRequestListOperationsResponseВозвращает список операций и их текущее состояние по заданным условиям.
WatchOperationsWatchOperationsRequestWatchOperationsResponse streamОтслеживает состояние операций;
позволяет получить актуальный список состояний операций, а также получать события с изменениями их состояний в рамках одного стрима.
DeleteOperationDeleteOperationRequestgoogle.protobuf.EmptyУдаляет и асинхронно отменяет обработку операций, подпадающих под фильтр.
После успешного вызова данного метода методы работы с указанными операциями будут считать,что операции не существуют.
Это означает, что отследить факт реальной остановки операции будет невозможно.
CancelOperationCancelOperationRequestgoogle.protobuf.EmptyАсинхронно отменяет операцию.
Отменённая операция переходит в состояние
FAILED
.
Если операция находится в обработке, то она перейдёт в состояние
FAILED
только после реальной остановки обработки.
С завершившимися операциями ничего не происходит.

Enumerations

OperationState

Состояние операции

ИмяЗначениеОписание
ENQUEUED0Операция находится в очереди и её обработка ещё не начата.
PROCESSING1Операция в данный момент обрабатывается.
DONE2Операция завершена успешно.
FAILED3Операция была завершена с ошибкой, либо была отменена.

Messages

CancelOperationRequest

Запрос на отмену операций для метода CancelOperation.
На данный момент поддерживается только вариант с явным указанием ID операции в поле

filter
.

ПолеТипОписание
filterOperationFilterФильтр операций.

DeleteOperationRequest

Запрос на удаление операций для метода DeleteOperation.
На данный момент поддерживается только вариант с явным указанием ID операции в поле

filter
.

ПолеТипОписание
filterOperationFilterФильтр операций.

GetOperationRequest

Запрос информации об операции для метода GetOperation.

ПолеТипОписание
idstringИдентификатор операции

ListOperationsRequest

Запрос на получение информации о состоянии множества операций для метода ListOperations.

ПолеТипОписание
filterOperationFilterФильтр операций.
page_sizeint32Максимальное количество операций, возвращаемое за один вызов.
Если операции, подпадающие под фильтр, не умещаются в одну страницу, то в ответе будет возвращён токен для получения следующей страницы операций.
page_tokenstringТокен страницы для постраничной выборки списка операций.
Сюда нужно передавать значение поля
next_page_token
из ListOperationsResponse
Если значение непустое, остальные поля сообщения игнорируются.

ListOperationsResponse

Список операций, возвращаемых методом ListOperations.

ПолеТипОписание
operationsOperationСписок операций.
next_page_tokenstringТокен для получения следующей страницы операций.
Заполняется для всех страниц кроме последней.

Operation

Операция.
Статус операций можно отслеживать через сервис Operations.

ПолеТипОписание
idstringИдентификатор операции.
Назначается сервисом при создании операции.
Идентификаторы операций уникальны для одного API_KEY.
groupstringГруппа, которая была назначена операции при создании.
metadatagoogle.protobuf.AnyНе используется на данный момент.
stateOperationStateСостояние, в котором находится операция.
errorgoogle.rpc.StatusОшибка, произошедшая при обработке операции.
Заполняется при статусе
FAILED
.
responsegoogle.protobuf.AnyРезультат выполнения операции.
Заполняется при статусе
DONE
.
Для сервиса распознавания аудио результатом является
RecognizeResponse
.

OperationFilter

Фильтр операций.
Описывает множество операций, которое должно быть обработано в рамках различных вызовов.
Для корректного запроса должно быть соблюдено хотя бы одно из правил:

  • Поле
    id
    задано как
    exact_id
  • Поле
    group
    задано как
    exact_group
  • Все 3 поля
    service_id
    ,
    id
    и
    group
    заданы
ПолеТипОписание
exact_service_idstringИдентификатор сервиса, чьи операции должно подпадать под фильтр.
Для сервиса распознавания аудио название сервиса -
stt
.
any_service_idgoogle.protobuf.EmptyРазрешить операции любого сервиса.
exact_idstringИдентификатор операции.
any_idgoogle.protobuf.EmptyРазрешить любой идентификатор операции
exact_groupstringНазвание группы, операции которой должны подпадать под фильтр.
any_groupgoogle.protobuf.EmptyРазрешить любую группу.
stateOperationStateНе используется на данный момент.

OperationsInitialState

Исходное состояние операций.

ПолеТипОписание
operationsOperationСписок операций.

OperationsUpdate

Изменение состояния одной или нескольких операций.

ПолеТипОписание
operationsOperationСписок операций.

WaitOperationRequest

Запрос на ожидание изменения состояния операции информации об операции для метода WaitOperation.

ПолеТипОписание
idstringИдентификатор операции.
timeoutgoogle.protobuf.DurationМаксимальное время ожидания изменения состояния операции.
Если не заполнено, то время не ожидания будет ограничено таймаутом вызова, допускаемым HTTP/gRPC протоколами.

WatchOperationsRequest

Запрос на мониторинг статуса операций для метода WatchOperations.

ПолеТипОписание
filterOperationFilterФильтр операций.
listen_for_updatesboolВключает режим подписки на все новые события с операциями, заданными фильтром.

WatchOperationsResponse

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

initial_state
.
Затем присылается одно сообщение с заполненным полем
init_finished
, означающее, что информация об исходном состоянии передана в полном объёме.
После этого, если была выставлена настройка
listen_for_updates
в запросе, сервер переходит в режим ожидания изменений в операциях, подпадающих под фильтр. Все такие изменения присылаются в виде сообщений с заполненным полем
update
.

ПолеТипОписание
initial_stateOperationsInitialStateОписание исходного состояния операций.
init_finishedgoogle.protobuf.EmptyПризнак того, что вся информация об исходном состоянии была передана.
updateOperationsUpdateОписание нового состояни изменившихся операций.