Форматы обмена сообщениями и запросов к грид-сервисам: общее описание, JSON Schema и примеры

Сервис выполнения многошаговых заданий реализован в виде RESTful грид-сервиса, поэтому взаимодействие с другими компонентами грид-сети происходит в режиме “запрос-ответ”. Далее следует описание запросов к серверу pilot-httpd. Все запросы, отправляемые на сервер, имеющие не пустое тело, должны содержать заголовок Content-MD5. Все ответы сервера, имеющие не пустое тело, всегда содержат заголовок Content-MD5. Все URL запросов из описания ниже используют префикс pilot/ для обозначения адреса реального сервера pilot-httpd. Формальное описание дается на языке JSON Schema.

Для создания новых заданий используется запрос POST к pilot/jobs/, запрос является объектом, имеющим следующие атрибуты:

• definition, объект - описание задания, и, возможно, задач, согласно спецификации описания заданий, задач и ресурсных требований.

Ответ на запрос соответствует ответу на запрос списка заданий. Возможные коды HTTP ответа: 201, 400, 401, 412.

{ "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/" } ]