API RESTful грид-сервисов приводится на примере сервиса выполнения многошаговых заданий. Этот сервис, который мы назовем pilot, работает с заданиями, которые представляют собой объекты сложной структуры, состоящие из элементарных задач. Каждая элементарная задача является запуском какой-либо программы на выполнение на грид–ресурсе по протоколу Globus WS-GRAM. Интерфейс прикладного программирования этого сервиса должен предоставлять возможность создания ресурсов заданий и задач, изменения их свойств, выполнения операций над заданиями (запуск, отмена), получение информации о состоянии заданий и задач, а так же получения учетной информации о выполнении заданий и задач. Таким образом, основными ресурсами сервиса являются задания, задачи, и учетная информация.
Систему предлагается реализовать в виде двух компонентов: системы управления выполнением заданий и системы регистрации и контроля выполнения задач. Основное назначение системы — выполнение заданий.
Задание — это направленный ацикличный граф, узлами в котором являются задачи, а ребра задают порядок их выполнения. Задачи, из которых состоит задание, выполняются в порядке обхода графа. При этом в местах ветвления, если это возможно, разные ветки графа выполняются одновременно. Задачи для выполнения передаются в систему регистрации задач.
На данном этапе ребра графа задают только порядок выполнения задач. Однако в будущем, возможно, ребра будут определять так же передачу выходных данных одних задач на вход другим.
Задача является базовым элементом, который может быть выполнен системой регистрации задач. Запуском задач на выполнение, а так же слежением за их выполнением занимается система регистрации и контроля выполнения задач . Систему распределения заданий предлагается реализовать как веб-сервис, следующий концепции REST, с представлением документов в виде JSON-документов.
Далее будем считать, что элементу pilot/ соответствует корневой URI всех сервисов, например, https://pilot.grid-net.ru/. Все данные передаются в формате JSON. Формальные описания форматов приводятся в виде JSON Schema
Ресурсы сервиса pilot:
При отправке всех запросов для установления https-соединения необходимо использовать прокси-сертификат пользователя, со всеми необходимыми расширениями.
Все запросы, отправляемые на сервер, имеющие не пустое тело, должны содержать заголовок Content-MD5. Все ответы сервера, имеющие не пустое тело, всегда содержат заголовок Content-MD5.
Для создания новых заданий используется запрос POST к pilot/jobs/, запрос является объектом, имеющим следующие атрибуты:
Ответ на запрос соответствует ответу на запрос списка заданий. Возможные коды HTTP ответа: 201, 400, 401, 412.
Для получения информации о состоянии задания используется запрос GET к pilot/jobs/<jobid>/, где <jobid> — идентификатор задания. Ответ на запрос является объектом, имеющим следующие атрибуты:
Объект состояния может так же иметь другие атрибуты, не определенные в данном списке.
Текущее состояние задания соответствует элементу с наиболее свежей датой/временем. Порядок, в котором объекты присутствуют в списке, может быть произвольным.
Объект операция может так же иметь другие атрибуты, не определенные в данном списке.
Операции обрабатываются системой в хронологическом порядке. Порядок, в котором объекты присутствуют в списке, может быть произвольным.
Возможные коды HTTP ответа: 201, 400, 401, 412.
{ "created": "2010-07-03T10:27:00Z",
"modified": "2010-07-03T10:27:14Z",
"expires": "2010-07-04T10:28:30Z",
"server_time": "2010-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": "2010-07-03T10:27:00Z" },
{ "s": "pending",
"ts": "2010-07-03T10:27:14Z" },
{ "s": "running",
"ts": "2010-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": "2010-07-03T10:27:03Z",
"completed": "2010-07-03T10:27:14Z",
"success": true
} ],
"tasks": {
"a": "https://pilot.grid-net.ru/jobs/912832/a/"
},
"deleted": false
}
Для получения информации о состоянии задания используется запрос GET к pilot/jobs/<jobid>/?parts=a;b;c…, где <jobid> — идентификатор задания, а значение параметра parts содержит перечисление частей информации о задании, которую необходимо получить. Части информации, которые можно получить:
Для изменения задания, а так же для выполнения операций над заданием (например, запуск задания), используются запросы методом PUT по URI задания, который обычно имеет вид pilot/jobs/<jobid>/.
Запрос является объектом, имеющим следующие атрибуты
Новое описание задания и, возможно, задач, согласно спецификации описания заданий, задач и ресурсных требований. При наличии данного атрибута в запросе произойдет изменение описания задания и, возможно, задач задания. Изменение возможно только для заданий, находящихся в состоянии new. Попытка изменения описания задания, находящегося в другом состоянии вызовет ошибку 403. Все задачи, отсутствующие в новом описании задания, будут сразу же удалены с сервера. Задачи, описания которых отсутствуют в новом описании задания, изменены не будут.
Уникальный в рамках одного задания идентификатор операции. Генерация уникального id является ответственностью клиента, в качестве id рекомендуется использовать, например, uuid4.
Возможные коды HTTP ответа: 204, 401, 404.
{ "operation": { "op": "start",
"id": "c9deca6c-3208-4146-848b-2b65b0943127" } }
Для получения списка заданий пользователя (в любом состоянии) используется запрос методом GET к pilot/jobs/. Ответом сервера является список объектов, каждый из которых имеет следующие атрибуты:
Возможные коды HTTP ответа: 200, 401. Пример ответа на запрос получения списка заданий
[ { "uri": "https://pilot.grid-net.ru/jobs/199231/" },
{ "uri": "https://pilot.grid-net.ru/jobs/912832/" } ]
Для получения списка заданий любых пользователей (в любом состоянии) используется запрос методом GET к pilot/jobs/?owner=X с дополнительным параметром owner в QUERY_STRING.
Значения параметра owner интерпретируется как shell-like glob pattern, т.е. все символы кроме * и ? соответствуют самим себе, символ ? соответствует значению «один любой символ», символ * соответствует значению «ноль или более любых символов». Ответом сервера является список объектов, каждый из которых имеет следующие атрибуты:
Ответ сервера содержит только те задания, доступ к которым разрешен согласно политике доступа к заданиям данного сервера. Например, администратор виртуальной организации может получать доступ ко всем заданиям пользователей данной виртуальной организации и т.п.
Для удаления задания используется запрос методом DELETE по URI задания. После удаления задания вся информация о нем и его задачах становится недоступной. При удалении задания, которые выполняется в момент удаления, производится принудительная остановка задания.
Возможные коды HTTP ответа: 204, 401, 404.
Для получения информации о задаче, включающей состояние задачи, используется запрос методом GET по URI задачи, который обычно имеет вид pilot/jobs/<jobid>/<taskid>/.
Ответом сервера является объект, имеющий следующие атрибуты:
Возможные коды HTTP ответа: 200, 401, 404.
Пример ответа с состоянием задачи
{ "created": "2010-07-03T10:27:00Z",
"modified": "2010-07-03T10:27:02Z",
"job": "https://pilot.grid-net.ru/jobs/912832/",
"definition": { "version": 2,
"executable": "/usr/bin/whoami",
"stdout": "test.txt"
},
"deleted": false,
"state": [ { "s": "new",
"ts": "2010-07-03T10:27:00Z" },
{ "s": "pending",
"ts": "2010-07-03T10:27:14Z" },
{ "s": "running",
"ts": "2010-07-03T10:27:22Z" },
{ "s": "finished",
"ts": "2010-07-03T10:27:23Z" } ],
"exit_code": 0
}
Для изменения описания задачи задачи используются запросы методом PUT по URI задачи, который обычно имеет вид pilot/jobs/<jobid>/<taskid>. Запрос является объектом, имеющим следующие атрибуты:
Пример запроса на изменение задачи
{
"definition": { "version": 2,
"executable": "/usr/bin/whoami",
"stdout": "test.txt"
}
}
Для получения информации о доступности ресурсов для выполнения задания, включая всего его задачи с учетом требований, используется запрос методом GET по URI вида pilot/v2/jobs/<jobid>/resources. Ответом является объект, имеющий следующие атрибуты:
Поскольку выполнение matchmaking может занимать определенное время, ответ на такой запрос к серверу может занять существенное время.
Для получения аккаунтинговой информации необходимо использовать запросы методом GET по в иерархии pilot/v2/accounting/. Поскольку аккаунтиговая информация может иметь значительные объемы дублирующейся информации, клиентам рекомендуется поддерживать Content-Encoding типа gzip, и сообщать об этом серверу в заголовках запроса через заголовок Accept-Encoding. Сервер по умолчанию возвращает ответы в формате JSON. Возможно возвращение ответов в формате CSV, для этого клиент должен добавить в запрос заголовок:
Accept: text/csv
Обращения за аккаунтинговой информацией могут производиться как с авторизацией сертификатом или прокси-сертификатом пользователя, так и с авторизацией сертификатом хоста. Вопрос об объеме доступа к аккаунтинговой информации по тому или иному сертификату решается со стороны сервера.
Запрос производится по URI вида pilot/v2/accounting/period/<ts1>-<ts2>/, где <ts1> и <ts2> могут иметь одно из следующих значений:
Невыполнение следующих требований приведет к ответу с кодом 400:
Примеры URI запросов:
Запрос производится по URI вида pilot/v2/accounting/last/N/, где N — количество возвращаемых записей. Возвращаются последние N записей аккаунтинга.
Ответы сервера на запросы аккаунтинга в формате JSON представляют собой списки объектов, имеющих следующие атрибуты:
task_finished: задача завершилась успешно. Для событий этого типа обязательно присутствуют поля job_id, user_dn, task_id. Может присутствовать поле detail, содержащее код завершения задачи.
Ответы сервера на запросы аккаунтинга в формате CSV соответствуют спецификации RFC 4180 с заголовками. Ответ содержит колонки ts, user_dn, job_id, task_id, event, detail, полностью соответствующие соответствующим полям ответа в формате JSON.
Последовательность действий, которые выполняет клиент для того, чтобы запустить задание, следить за его состоянием и получить результаты:
Через некоторое время после этого начнется выполнение задания. За состоянием можно следить при помощи обращений методом GET по URI задания и/или отдельных задач.
200 OK
Запрос обработан без ошибок, тело ответа содержит ответ на запрос в указанном выше формате.
201 Created
Запрос обработан без ошибок, ответ имеет пустое тело и заголовок Location, содержащий URI созданного ресурса.
204 No Content
Запрос обработан без ошибок, ответ имеет пустое тело, содержательного ответа на запрос не предполагается по спецификации протокола. Такой ответ обычно является подтверждением удаления какого-либо ресурса.
400 Bad Request
Ошибка обработки запроса. Запрос содержал данные в неправильном формате, либо пытался изменить параметры, которые нельзя изменить.
401 Unauthorized
Ошибка обработки запроса. Доступ к запрашиваемому объекту запрещен.
403 Forbidden
Попытка выполнения операции, которая запрещена. Например, попытка изменить описание задания в состоянии, отличного от new.
404 Not Found
Ошибка обработки запроса. Запрашиваемый ресурс не существует.
412 Precondition Failed
Ошибка обработки запроса. Контрольная сумма тела запроса не соответствует заголовку Content-MD5 запроса. Тело ответа пустое.