Редактировать задачу
Запрос позволяет внести изменения в задачу.
PATCH
https://api.tracker.yandex.net/v3/issues/<id_задачи>
Статус задачи может быть изменен только с помощью запроса «Выполнить переход в статус».
Формат запроса
Перед выполнением запроса получите доступ к API.
Чтобы отредактировать задачу, используйте HTTP-запрос с методом PATCH
. В теле запроса укажите параметры в формате JSON.
PATCH /v3/issues/<id_задачи>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
Тело запроса в формате JSON
}
Заголовки
-
Host
: адрес узла, предоставляющего API. -
Authorization
: токен для авторизации в одном из форматов:-
OAuth <OAuth-токен>
при авторизации по протоколу OAuth 2.0. Читать подробнее -
Bearer <IAM-токен>
при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Cloud Organization. Читать подробнее
-
-
X-Org-ID
илиX-Cloud-Org-ID
: идентификатор организации.-
Используйте заголовок
X-Org-ID
, если к Трекеру привязана организация Яндекс 360 для бизнеса. -
Используйте заголовок
X-Cloud-Org-ID
, если к Трекеру привязана организация Yandex Cloud Organization.
Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.
-
Ресурс
Параметр | Описание | Тип данных |
---|---|---|
<id_задачи> | Идентификатор или ключ текущей задачи. | Строка |
Параметры запроса
Дополнительные параметры
Параметр | Описание | Тип данных |
---|---|---|
version | Версия задачи. Изменения вносятся только в текущую версию задачи. | Число |
Параметры тела запроса
В теле запроса передается JSON-объект с идентификаторами изменяемых полей задачи и их значениями. Для редактирования полей задачи можно использовать операторы set
, add
, remove
и другие.
Подробнее читайте в разделе Формат тела запроса.
Дополнительные параметры
В таблице перечислены часто используемые параметры задачи. Полный список поддерживаемых параметров можно найти на странице https://tracker.yandex.ru/admin/fields.
Параметр | Описание | Тип данных |
---|---|---|
summary | Название задачи. | Строка |
parent | Родительская задача. | Объект или строка |
description | Описание задачи. | Строка |
markupType | Тип отображаемой в тексте разметки. Если вы используете в тексте описания задачи разметку YFM, укажите значение md . |
Строка |
sprint | Блок с информацией о спринтах. | Массив объектов или строк |
type | Тип задачи. | Объект, строка (если передается ключ типа задачи) или число (если передается идентификатор типа задачи). |
priority | Приоритет задачи. | Объект, строка (если передается ключ приоритета) или число (если передается идентификатор приоритета). |
followers | Идентификаторы или логины наблюдателей задачи. | Массив объектов или строк |
project | Блок с информацией о проектах задачи | Объект |
attachmentIds | Идентификаторы временных файлов, которые будут добавлены как вложения. | Массив строк |
descriptionAttachmentIds | Идентификаторы временных файлов, которые будут добавлены в описание задачи. | Массив строк |
tags | Блок с информацией о тегах. | Массив строк |
Поля объекта parent
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор родительской задачи. | Строка |
key | Ключ родительской задачи. | Строка |
Поля объекта sprint
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор спринта. Информацию о спринте можно получить при помощи запроса. | Число |
Поля объекта type
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор типа задачи. | Строка |
key | Ключ типа задачи. | Строка |
Поля объекта priority
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор приоритета. | Строка |
key | Ключ приоритета. | Строка |
Поля объекта followers
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор сотрудника. | Строка |
Поля объекта project
Параметр | Описание | Тип данных |
---|---|---|
primary | Идентификатор основного проекта задачи (поле проекта shortId ) |
Число |
secondary | Идентификаторы дополнительных проектов задачи (поле проекта shortId ) |
Массив чисел |
Если в адресе запроса указана версия API v2
, параметр project
может содержать только идентификатор основного проекта.
Например: "project": 1234
Пример 1: Изменить название, описание, тип и приоритет задачи.
- Используется HTTP-метод PATCH.
- Редактируется задача TEST-1.
- Новый тип задачи: «Ошибка».
- Новый приоритет задачи: «Низкий».
PATCH /v3/issues/TEST-1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации> { "summary": "<новое_название_задачи>", "description": "<новое_описание_задачи>", "type": { "id": "1", "key": "bug" }, "priority": { "id": "2", "key": "minor" } }
Пример 2: Изменить родительскую задачу, добавить в спринты, добавить наблюдателей.
- Используется HTTP-метод PATCH.
- Редактируется задача TEST-1.
- Новая родительская задача: TEST-2.
- Задача добавляется в спринты с идентификаторами 3 и 2. Спринты должны быть на разных досках.
- Добавлены наблюдатели с логинами
userlogin-1
иuserlogin-2
.
PATCH /v3/issues/TEST-1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации> { "parent": { "key": "TEST-2"}, "sprint": [{"id": "3"}, {"id": "2"}], "followers": { "add": ["userlogin-1", "userlogin-2"] } }
Пример 3: Добавить к задаче один тег и удалить другой.
- Используется HTTP-метод PATCH.
- Редактируется задача TEST-1.
- Добавляется тег:
тег1
.- Удаляется тег:
тег2
.
PATCH /v3/issues/TEST-1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации> { "tags": { "add": ["тег1"], "remove": ["тег2"] } }
Пример 4: Изменить у задачи основной проект и добавить дополнительный
- Используется HTTP-метод PATCH.
- В качестве основного проекта указывается проект с идентификатором
1234
.- В список дополнительных проектов добавляется проект с идентификатором
5678
.
PATCH /v3/issues/TEST-1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации> { "project": { "primary": 1234, "secondary": { "add": [5678] } } }
Формат ответа
В случае успешного выполнения запроса API возвращает ответ с кодом 200 OK
.
Тело ответа содержит информацию об отредактированной задаче в формате JSON.
[
{
"self": "https://api.tracker.yandex.net/v3/issues/TREK-9844",
"id": "593cd211ef7e8a33********",
"key": "TREK-9844",
"version": 7,
"lastCommentUpdatedAt": "2017-07-18T13:33:44.291+0000",
"summary": "subtask",
"parent": {
"self": "https://api.tracker.yandex.net/v3/issues/JUNE-2",
"id": "593cd0acef7e8a33********",
"key": "JUNE-2",
"display": "Task"
},
"aliases": [
"JUNE-3"
],
"updatedBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
},
"description": "<#<html><head></head><body><div>test</div><div> </div><div> </div> </body></html>#>",
"sprint": [
{
"self": "https://api.tracker.yandex.net/v3/sprints/53**",
"id": "53**",
"display": "Sprint 1"
}
],
"type": {
"self": "https://api.tracker.yandex.net/v3/issuetypes/2",
"id": "2",
"key": "task",
"display": "Задача"
},
"priority": {
"self": "https://api.tracker.yandex.net/v3/priorities/2",
"id": "2",
"key": "normal",
"display": "Средний"
},
"createdAt": "2017-06-11T05:16:01.339+0000",
"followers": [
{
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
}
],
"createdBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
},
"votes": 0,
"assignee": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
},
"project": {
"primary": {
"self": "https://api.tracker.yandex.net/v3/projects/1",
"id": "1",
"display": "New project"
},
"secondary": []
},
"queue": {
"self": "https://api.tracker.yandex.net/v3/queues/TREK",
"id": "111",
"key": "TREK",
"display": "My queue"
},
"updatedAt": "2017-07-18T13:33:44.291+0000",
"status": {
"self": "https://api.tracker.yandex.net/v3/statuses/1",
"id": "1",
"key": "open",
"display": "Открыт"
},
"previousStatus": {
"self": "https://api.tracker.yandex.net/v3/statuses/2",
"id": "2",
"key": "resolved",
"display": "Решен"
},
"favorite": false
},
{...}
]
Параметры ответа
В таблице перечислены часто используемые параметры задачи. Полный список поддерживаемых параметров можно найти на странице https://tracker.yandex.ru/admin/fields.
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о задаче | Строка |
id | Идентификатор задачи | Строка |
key | Ключ задачи | Строка |
version | Версия задачи. Каждое изменение параметров задачи увеличивает номер версии. Редактирование задачи будет заблокировано, если версия достигнет предельного значения: для роботов 10100 , для пользователей 11100 |
Число |
lastCommentUpdatedAt | Дата и время последнего добавленного комментария | Строка |
summary | Название задачи | Строка |
parent | Объект с информацией о родительской задаче | Объект |
aliases | Массив с информацией об альтернативных ключах задачи | Массив строк |
updatedBy | Объект с информацией о последнем сотруднике, изменявшим задачу | Объект |
description | Описание задачи | Строка |
sprint | Массив объектов с информацией о спринте | Массив объектов |
type | Объект с информацией о типе задачи | Объект |
priority | Объект с информацией о приоритете | Объект |
createdAt | Дата и время создания задачи | Строка |
followers | Массив объектов с информацией о наблюдателях задачи | Массив объектов |
createdBy | Объект с информацией о создателе задачи | Объект |
votes | Количество голосов за задачу | Число |
assignee | Объект с информацией об исполнителе задачи | Объект |
project | Объект с информацией о проектах задачи | Объект |
queue | Объект с информацией об очереди задачи | Объект |
updatedAt | Дата и время последнего обновления задачи | Строка |
status | Объект с информацией о статусе задачи | Объект |
previousStatus | Объект с информацией о предыдущем статусе задачи | Объект |
favorite | Признак избранной задачи:
|
Логический |
tags | Теги задачи | Массив строк |
Поля объекта parent
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о задаче. | Строка |
id | Идентификатор задачи. | Строка |
key | Ключ задачи. | Строка |
display | Отображаемое название задачи. | Строка |
Поля объекта updatedBy
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число |
cloudUid | Уникальный идентификатор пользователя в Yandex Cloud Organization. | Строка |
Поля объектов массива sprint
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о спринте. | Строка |
id | Идентификатор спринта. | Строка |
display | Отображаемое название спринта. | Строка |
Поля объекта type
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о типе задаче. | Строка |
id | Идентификатор типа задачи. | Строка |
key | Ключ типа задачи. | Строка |
display | Отображаемое название типа задачи. | Строка |
Поля объекта priority
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о приоритете. | Строка |
id | Идентификатор приоритета. | Строка |
key | Ключ приоритета. | Строка |
display | Отображаемое название приоритета. | Строка |
Поля объектов массива followers
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число |
cloudUid | Уникальный идентификатор пользователя в Yandex Cloud Organization. | Строка |
Поля объекта createdBy
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число |
cloudUid | Уникальный идентификатор пользователя в Yandex Cloud Organization. | Строка |
Поля объекта assignee
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число |
cloudUid | Уникальный идентификатор пользователя в Yandex Cloud Organization. | Строка |
Поля объекта project
Параметр | Описание | Тип данных |
---|---|---|
primary | Основной проект задачи | Объект |
secondary | Список дополнительных проектов задачи | Массив объектов |
Если в адресе запроса указана версия API v2
, объект project
содержит информацию только об основном проекте.
Поля объекта, содержащего данные проекта
Параметры primary
и secondary
содержат объекты со следующими полями:
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о проекте. | Строка |
id | Идентификатор проекта. | Строка |
display | Отображаемое название проекта. | Строка |
Поля объекта queue
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию об очереди. | Строка |
id | Идентификатор очереди. | Строка |
key | Ключ очереди. | Строка |
display | Отображаемое название очереди. | Строка |
Поля объекта status
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о статусе. | Строка |
id | Идентификатор статуса. | Строка |
key | Ключ статуса. | Строка |
display | Отображаемое название статуса. | Строка |
Поля объекта previousStatus
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о статусе. | Строка |
id | Идентификатор статуса. | Строка |
key | Ключ статуса. | Строка |
display | Отображаемое название статуса. | Строка |
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
- 401
- Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.
- 403
- У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
- 404
- Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
- 409
- При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
- 423
- Редактирование объекта заблокировано. Возможно, превышено допустимое значение параметра
version
— количество обновлений объекта. Максимальное значение версии составляет10100
для роботов и11100
для пользователей.