Table of Contents
Форматы обмена сообщениями и запросов к грид-сервисам: общее описание, JSON Schema и примеры
Сервис выполнения многошаговых заданий реализован в виде RESTful грид-сервиса, поэтому взаимодействие с другими компонентами грид-сети происходит в режиме ?запрос-ответ?. Далее следует описание запросов к серверу pilot-httpd. Все запросы, отправляемые на сервер, имеющие не пустое тело, должны содержать заголовок Content-MD5. Все ответы сервера, имеющие не пустое тело, всегда содержат заголовок Content-MD5. Все URL запросов из описания ниже используют префикс pilot/ для обозначения адреса реального сервера pilot-httpd. Формальное описание дается на языке 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/<jobid>/, где <jobid> ? идентификатор задания.
Ответ на запрос является объектом, имеющим следующие атрибуты:
- 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/<jobid>/.
Запрос является объектом, имеющим следующие атрибуты:
- 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/" } ]