====== Форматы обмена сообщениями и запросов к грид-сервисам: общее описание, JSON Schema и примеры ====== Сервис выполнения многошаговых заданий реализован в виде RESTful грид-сервиса, поэтому взаимодействие с другими компонентами грид-сети происходит в режиме "запрос-ответ". Далее следует описание запросов к серверу pilot-httpd. Все запросы, отправляемые на сервер, имеющие не пустое тело, должны содержать заголовок Content-MD5. Все ответы сервера, имеющие не пустое тело, всегда содержат заголовок Content-MD5. Все URL запросов из описания ниже используют префикс pilot/ для обозначения адреса реального сервера pilot-httpd. Формальное описание дается на языке [[http://json-schema.org/|JSON Schema]]. ===== Создание нового задания ===== Для создания новых заданий используется запрос POST к pilot/jobs/, запрос является объектом, имеющим следующие атрибуты: * definition, объект - описание задания, и, возможно, задач, согласно спецификации описания заданий, задач и ресурсных требований. Ответ на запрос соответствует ответу на запрос списка заданий. Возможные коды HTTP ответа: 201, 400, 401, 412. ==== Формальное описание (JSON Schema) ==== { "description": "Запрос на создание задания", "type": "object", "properties": { "definition": { "type": "string", "description": "описание задания на языке описания заданий", "format": "application/octet-stream" } }, "additionalProperties": false } Пример запроса: { "definition": "# Example job\n#\nJOB A A.jt\nJOB B B.jt\nJOB C C.jt\nPARENT A CHILD B\nPARENT B CHILD C\n" } ===== Получение информации о задании ===== Для получения информации о состоянии задания используется запрос GET к pilot/jobs//, где — идентификатор задания. Ответ на запрос является объектом, имеющим следующие атрибуты: * created, modified, строка - дата/время создания задания и дата/время последнего изменения задания или его состояния. * expires, строка - дата/время автоматического удаления задания с сервера. * server_time, строка - дата/время на сервере на момент генерации данного ответа сервера. * server_policy_url, строка - URL документа, описывающего политику сервера, применяемую к данному заданию. Политика сервера описывает используемые сервером умолчания, и ограничения. * owner, строка - DN владельца задания * state, список объектов - история изменений состояния задания. Каждый объект имеет атрибуты: * s, строка - состояние задания; возможные значения: * new: только что созданное задание; * pending: задание ожидает начала выполнения; * running: задание выполняется; * paused: выполнение задания приостановлено; * finished: выполнение задания завершено; * aborted: выполнение задания отменено. * ts, строка - дата/время, когда наступило соответствующее состояние. Объект состояния может так же иметь другие атрибуты, не определенные в данном списке. Текущее состояние задания соответствует элементу с наиболее свежей датой/временем. Порядок, в котором объекты присутствуют в списке, может быть произвольным. * operation, список объектов - текущие операции и история выполнения операций над заданием; каждый объект имеет атрибуты: * op, строка -операция; возможные значения: * start: запуск задания на выполнение; * pause: приостановка выполнения задания; * abort: отмена выполнения задания. * id, строка - уникальный в рамках одного задания идентификатор операции. * created, строка - дата и время помещения данной операции в очередь. * completed, строка - дата и время завершения данной операции. * success, boolean - было ли завершение операции успешным. * result, объект - расширенный результат завершения операции, произвольный объект. Объект операция может так же иметь другие атрибуты, не определенные в данном списке. Операции обрабатываются системой в хронологическом порядке. Порядок, в котором объекты присутствуют в списке, может быть произвольным. * definition, объект - описание задания, без описания задач, согласно спецификации описания заданий, задач и ресурсных требований. * tasks, объект - URI задач задания; атрибуты объекта соответствуют идентификаторам задач из описания задания, значения этих атрибутов — URI соответствующих задач (возможно, относительные). Возможные коды HTTP ответа: 201, 400, 401, 412. Формальное описание (JSON Schema): { "description": "Задание", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time", "optional": true }, "expires": { "type": "string", "format": "date-time", "description": "Дата, когда данная задача будет удалена с сервера." }, "server_time": { "type": "string", "format": "date-time", "description": "Текущие дата и время на сервере" }, "server_policy_uri": { "type": "string", "format": "uri", "description": "URI ресурса с описанием политики работы сервера" }, "owner": { "type": "string", "description": "DN пользователя, создавшего задание", "maxLength": 256 }, "state": { "type": "array", "description": "Состояние задания, со всей историей его изменений", "items": { "type": "object", "description": "Запись о состоянии задания.", "properties": { "s": { "type": "string", "description": "состояние", "enum": [ "new", "pending", "running", "paused", "finished", "aborted"] }, "ts": { "type": "string", "format": "date-time", "description": "время, когда наступило данное состояние" } }, "additionalProperties": true } }, "operation": { "type": "array", "description": "операции, которые должны быть выполнены с данным заданием", "items": { "type": "object", "description": "Операция с заданием", "properties": { "op": { "type": "string", "description": "операция", "enum": [ "start", "pause", "abort" ] }, "id": { "type": "string", "description": "id операции", "maxLength": 36 }, "created": { "type": "string", "format": "date-time", "description": "время, когда была запрошена данная операция" }, "completed": { "type": "string", "format": "date-time", "description": "время, когда была вполнена данная операция", "optional": true, "requires": "success" }, "success": { "type": "boolean", "description": "было ли выполнение операции успешным", "optional": true, "requires": "completed" }, "result": { "type": "object", "description": "результат завершения операции", "optional": true, "requires": "completed" } }, "additionalProperties": true } }, "definition": { "type": "string", "description": "описание задания на языке описания заданий", "format": "application/octet-stream" }, "tasks": { "type": "array", "description": "список URI задач задания", "items": { "type": "string", "format": "uri" } } }, "additionalProperties": false Пример ответа с информацией о задании: { "created": "2009-07-03T10:27:00Z", "modified": "2009-07-03T10:27:14Z", "expires": "2009-07-04T10:28:30Z", "server_time": "2009-07-03T10:28:30Z", "server_policy_uri": "https://pilot.grid-net.ru/policy/job/", "definition": { "version": 2, "description": "тестовое задание", "default_storage_base": "gsiftp://tb01.grid-net.ru/home/shamardin/jt/", "tasks": [ { "id": "a", "description": "задача #1", "definition": { "version": 2, "executable": "/usr/bin/whoami", "stdout": "test.txt" } } ] } "state": [ { "s": "new", "ts": "2009-07-03T10:27:00Z" }, { "s": "pending", "ts": "2009-07-03T10:27:14Z" }, { "s": "running", "ts": "2009-07-03T10:27:22Z" } ], "owner": "/C=RU/O=NanoGrid/OU=users/OU=sinp.msu.ru/CN=Lev Shamardin", "operation": [ { "op": "start", "id": "c9deca6c-3208-4146-848b-2b65b0943127", "created": "2009-07-03T10:27:03Z", "completed": "2009-07-03T10:27:14Z", "success": true } ], "tasks": { "a": "https://pilot.grid-net.ru/jobs/912832/a/" } } ===== Изменение задания и выполнение операций над заданием ===== Для изменения задания, а так же для выполнения операций над заданием (например, запуск задания), используются запросы методом PUT по URI задания, который обычно имеет вид pilot/jobs//. Запрос является объектом, имеющим следующие атрибуты: * definition, объект, опциональный параметр - новое описание задания и, возможно, задач, согласно спецификации описания заданий, задач и ресурсных требований. При наличии данного атрибута в запросе произойдет изменение описания задания и, возможно, задач задания. Изменение возможно только для заданий, находящихся в состоянии new. Попытка изменения описания задания, находящегося в другом состоянии вызовет ошибку 403. Все задачи, отсутствующие в новом описании задания, будут сразу же удалены с сервера. Задачи, описания которых отсутствуют в новом описании задания, изменены не будут. * operation, объект, опциональный параметр - при наличии этого параметра будет создана новая операция над заданием, если ее не существовало ранее; объект имеет следующие атрибуты: * op, строка - выполняемая операция. Возможные значения: * start: запустить задание на выполнение; * pause: приостановить выполнение задания; * abort: отменить выполнение задания. * id, строка - уникальный в рамках одного задания идентификатор операции. Генерация уникального id является ответственностью клиента, в качестве id рекомендуется использовать, например, uuid4. Возможные коды HTTP ответа: 204, 401, 404. Формальное описание JSON Schema: { "description": "Запрос на модификацию параметров задания", "type": "object", "properties": { "operation": { "type": "object", "description": "Операция с заданием", "properties": { "op": { "type": "string", "description": "операция", "enum": [ "start", "pause", "abort" ] }, "id": { "type": "string", "description": "id операции", "maxLength": 36 } }, "additionalProperties": true, "optional": true }, "definition": { "type": "string", "description": "описание задания на языке описания заданий", "format": "application/octet-stream", "optional": true } } } Пример запроса на запуск задания: { "operation": { "op": "start", "id": "c9deca6c-3208-4146-848b-2b65b0943127" } } ===== Получение списка заданий ===== Для получения списка заданий пользователя (в любом состоянии) используется запрос методом GET к pilot/jobs/. Ответом сервера является список объектов, каждый из которых имеет следующие атрибуты: * uri, строка - URI задания. Возможные коды HTTP ответа: 200, 401. Формальное описание JSON Schema: { "description": "Список заданий, к которым есть доступ у пользователя", "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", "description": "URI задания", "format": "uri" } }, "additionalProperties": false } } Пример ответа на запрос получения списка заданий: [ { "uri": "https://pilot.grid-net.ru/jobs/199231/" }, { "uri": "https://pilot.grid-net.ru/jobs/912832/" } ]