View source for Help:Public API/management/containers

= Управление контейнерами (проектами, ветками, группами проектов) =

В данном разделе содержится описание REST API управления контейнерами и их содержимым.

Для выполнения операций получения списка контейнеров, их создания, изменения и удаления существует http-ресурс

<pre style="white-space: pre;">
POST /api/public/admin/server/containers
</pre>

Для операций управления составом групп проектов существует http-ресурс 

<pre style="white-space: pre;">
POST /api/public/admin/server/project-groups
</pre>

Для операции переименования снимков существует http-ресурс

<pre>
PUT /api/public/snapshots/{snapshot_id}/update
</pre>

{{Note|type=warn|text=Для использования ресурсов необходимо использовать http-запросы с токеном пользователя имеющего соответствующие права}}

== <code>POST /api/public/admin/server/containers</code> - управление набором проектов, веток, групп проектов ==

Формат запроса:

<pre style="white-space: pre;">
{
  "action": "string",
  "id": "string",
  "type": "string",
  "name": "string",
  "parent": "string",
  "review_with_comment": true
}
</pre>

Формат ответа:

<pre style="white-space: pre;">
{
  "Containers": [
    {
      "action": "string",
      "id": "string",
      "name": "string",
      "parent": "string",
      "review_with_comment": true,
      "type": "string"
    }
  ]
}
</pre>

Назначение полей запроса и установка значений полей ответа зависит от типа операции и определяется значением поля запроса <code>action</code>.

{| class="wikitable"
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code>
|-
!Значение
!Тип операции
|-
|<code>list</code>
|Получение списка контейнеров
|-
|<code>add</code>
|Создание контейнера
|-
|<code>update</code>
|Изменение контейнера
|-
|<code>remove</code>
|Удаление контейнера
|}

=== Получение списка контейнеров: "action": "list" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>list</code>
|-
|<code>id</code>
|Если не пустое: идентификатор контейнера, для которого будут загружены "связанные" контейнеры:
:- если передан id группы проектов - вернётся список проектов входящих в данную группу
:- если передан id проекта - вернётся список групп проектов, в который входит проект + список его веток
:- если передан id ветки - вернётся список снимков данной ветки
|-
|<code>type</code>
|Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code>

Если не пустое: отфильтровывает список контейнеров по типу

Если пустое:
:- если поле <code>id</code> пустое - возвращается объединённый список проектов и групп проектов
|-
|<code>name</code>
|Если не пустое:
:- если поле <code>id</code> пустое - отфильтровывает список контейнеров по названию
:- если поле <code>id</code> НЕ пустое - фильтр по названию НЕ применяется
|-
|<code>parent</code>
|Не используется
|-
|<code>review_with_comment</code>
|Не используется
|}

==== Примеры запросов с <code>"action": "list"</code> ====
<pre>
$ curl --data '{"action": "list"}' -X POST http://localhost:8080/api/public/admin/server/containers
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"},{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"},{"id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","name":"iptables","type":"project"},{"id":"d53b0b92-d0fb-429a-8f86-c8fe6ee50c0c","name":"proftpd","type":"project"}]}
</pre>
<pre>
$ curl --data '{"action": "list", "type": "project-group"}' -X POST http://localhost:8080/api/public/admin/server/containers
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"20706313-6986-4c9d-9a4e-5e4908a11499","name":"projectGroupB","type":"project-group"}]}
</pre>
<pre>
$ curl --data '{"action": "list", "name": "bas"}' -X POST http://localhost:8080/api/public/admin/server/containers
{"Containers":[{"id":"a7e22042-96e5-4659-b21a-0615d434bed7","name":"bash","type":"project"}]}
</pre>
<pre>
$ curl --data '{"action": "list", "id":"a7e22042-96e5-4659-b21a-0615d434bed7"}' -X POST http://localhost:8080/api/public/admin/server/containers
{"Containers":[{"id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","name":"projectGroupA","type":"project-group"},{"id":"ef9210db-180b-4351-8a2f-7e8ceaa42ec6","name":"master","type":"branch","parent":"a7e22042-96e5-4659-b21a-0615d434bed7"}]}
</pre>

=== Создание контейнера: "action": "add" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>add</code>
|-
|<code>id</code>
|Не используется
|-
|<code>type</code>
|Тип нового контейнера. Обязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code>
|-
|<code>name</code>
|Название нового контейнера. Обязательное
|-
|<code>parent</code>
|Название или идентификатор проекта, в котором будет создана новая ветка
Если тип нового контейнера НЕ <code>branch</code>: не используется
|-
|<code>review_with_comment</code>
|Значение настройки проекта "Обязательный комментарий при разметке"
Если тип нового контейнера НЕ <code>project</code>: не используется
|}

=== Изменение контейнера: "action": "update" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>update</code>
|-
|<code>id</code>
|Идентификатор изменяемого контейнера. Обязательное
|-
|<code>type</code>
|Тип изменяемого контейнера. Используется для поиска контейнера вместе с id. Изменить тип контейнера нельзя. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code>
|-
|<code>name</code>
|Новое название контейнера. Обязательное
|-
|<code>parent</code>
|Не используется. Изменить проект в котором создана ветка нельзя
|-
|<code>review_with_comment</code>
|Новое значение настройки проекта "Обязательный комментарий при разметке"
|}

=== Удаление контейнера: "action": "remove" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>remove</code>
|-
|<code>id</code>
|Идентификатор удаляемого контейнера. Обязательное
|-
|<code>type</code>
|Тип удаляемого контейнера. Используется для поиска контейнера вместе с id. Необязательное. Допустимые значения: <code>project</code>, <code>branch</code>, <code>project-group</code>
|-
|<code>name</code>
|Не используется
|-
|<code>parent</code>
|Не используется
|-
|<code>review_with_comment</code>
|Не используется
|}

== <code>POST /api/public/admin/server/project-groups</code> - управление составом групп проектов ==

Формат запроса:

<pre style="white-space: pre;">
{
  "action": "string",
  "project_group_name_or_id": "string",
  "project_name_or_id": "string"
}
</pre>

Формат ответа:

<pre style="white-space: pre;">
{
  "action": "string",
  "project_group_id": "string",
  "project_group_name": "string",
  "project_id": "string",
  "project_name": "string"
}
</pre>

Назначение полей запроса и ответа зависит от типа операции и определяется значением поля <code>action</code>.

{| class="wikitable"
|+ style=white-space:nowrap | Поддерживаемыe значения поля <code>action</code>
|-
!Значение
!Тип операции
|-
|<code>get</code>
|Получение экземпляра группы проектов
|-
|<code>add-project-to-group</code>
|Добавление проекта в группу проектов
|-
|<code>remove-project-from-group</code>
|Исключение проекта из группы проектов
|}

=== Получение экземпляра группы проектов: "action": "get" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>get</code>
|-
|<code>project_group_name_or_id</code>
|Название или идентификатор запрашиваемой группы проектов. {{Note|text= Поддержка названия добавлена ПОСЛЕ версии 9.0.2}}
|-
|<code>project_name_or_id</code>
|Не используется
|}

=== Добавление проекта в группу проектов: "action": "add-project-to-group" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>add-project-to-group</code>
|-
|<code>project_group_name_or_id</code>
|Название или идентификатор изменяемой группы проектов
|-
|<code>project_name_or_id</code>
|Название или идентификатор добавляемого проекта
|}

=== Исключение проекта из группы проектов: "action": "remove-project-from-group" ===

{| class="wikitable"
|+ style=white-space:nowrap | Назначение полей запроса
|-
!Поле
!Описание
|-
|<code>action</code>
|<code>remove-project-from-group</code>
|-
|<code>project_group_name_or_id</code>
|Название или идентификатор изменяемой группы проектов
|-
|<code>project_name_or_id</code>
|Название или идентификатор исключаемого проекта
|}

==== Примеры запросов управления составом групп ====
<pre>
$ curl --data '{"action": "get", "project_group_name_or_id": "0f7da122-9c86-4384-b7bc-356bfb3b7f28"}' -X POST http://localhost:8080/api/public/admin/server/project-groups
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}

$ curl --data '{"action": "get", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups
{"action":"get","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA"}
</pre>
<pre>
$ curl --data '{"action": "add-project-to-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups
{"action":"add-project-to-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}
</pre>
<pre>
$ curl --data '{"action": "remove-project-from-group", "project_name_or_id": "iptables", "project_group_name_or_id": "projectGroupA"}' -X POST http://localhost:8080/api/public/admin/server/project-groups
{"action":"remove-project-from-group","project_group_id":"0f7da122-9c86-4384-b7bc-356bfb3b7f28","project_group_name":"projectGroupA","project_id":"a8e0352c-0408-417c-8fd0-4fbe03f38980","project_name":"iptables"}
</pre>