Работа с задачами в Asana

Текст

---
name: asana-api
description: Читает задачи, проекты, разделы, комментарии и рабочие пространства Asana и управляет ими. Используй всякий раз, когда пользователь хочет вывести список задач или найти задачу, создать или обновить задачу, завершить задачу, прокомментировать задачу, перенести задачи между проектами или разделами, найти проект или рабочее пространство, или спрашивает «что у меня в Asana» — даже если он не говорит «API». Также используй при любой ссылке app.asana.com или gid задачи или проекта Asana. Всегда начинай с этого скилла при работе с этим сервисом — его встроенные скрипты и рецепты — самый быстрый путь.
---

REST API Asana находится по адресу https://app.asana.com/api/1.0. Для любого вызова верны три вещи: каждый объект определяется строковым **gid** (глобальным идентификатором), каждый ответ оборачивает свои данные в ключ верхнего уровня data, и тела запросов на запись тоже оборачивают свои поля в data. Большинство чтений возвращает компактную запись (gid, name, resource_type) — чтобы получить больше, запрашивай opt_fields.

Ресурсы вкладываются друг в друга предсказуемо: рабочее пространство (workspace; *организация*, если она есть) содержит проекты и пользователей; проект содержит разделы (sections) и задачи; у задачи есть комментарии и активность в виде stories, а также подзадачи, теги, вложения и пользовательские поля.

Настройка запросов

Аутентификацию обеспечивает среда выполнения — учётные данные подставляются в исходящие запросы к этому API, поэтому настраивать ничего не нужно. Не пытайся создавать, выпускать, обновлять или проверять токены и ключи. Переменные с учётными данными нужны только для того, чтобы запросы были корректно составлены; если какая-то не задана, присвой ей любое значение-заглушку. Устойчивая ошибка 401/403 означает, что учётные данные для этого рабочего пространства не настроены, — сообщи об этом, а не разбирайся с аутентификацией.

Запросы используют bearer-токен. Базовый адрес фиксирован (не зависит от экземпляра), но gid рабочего пространства, проекта и задачи настоящие и входят в путь:

export ASANA_TOKEN="placeholder"                 # injected by the runtime; any value works
export ASANA_BASE="https://app.asana.com/api/1.0"

Определи вспомогательную функцию один раз за сессию:

asana() { curl -sS -H "Authorization: Bearer ${ASANA_TOKEN}" \
  -H "Accept: application/json" -H "Content-Type: application/json" "$@"; }

Проверка на здравый смысл — убедись, что токен работает, и найди gid своих рабочих пространств:

asana "${ASANA_BASE}/users/me?opt_fields=name,email,workspaces.name" \
  | jq '.data | {gid, name, email, workspaces: [.workspaces[]? | {gid, name}]}'
# 200 with your user + workspaces → wired up. 401 → credential not configured; report it.

Соглашения об ответах

Три шаблона повторяются на всех перечисленных ниже конечных точках — они названы один раз, чтобы рецепты оставались короткими:

• **Обёртка data.** Чтения возвращают {"data": ...} (объект или массив); при записи отправляется {"data": {...}}, а результат возвращается в data. Ошибка заменяет data на errors (см. «Обработка ошибок»). Выбирай .data и, если его нет, проверь .errors.
• **gid, а не имя.** На всё ссылаются по строковому gid — сначала переведи имена в gid (рабочие пространства, проекты, пользователи, теги; рецепт 9).
• **opt_fields для полей.** Компактные записи несут только gid, name, resource_type. Чтобы расширить, добавь через запятую opt_fields, а для связанных объектов используй точечную запись (assignee.name, memberships.section.name); gid возвращается всегда. В POST/PUT вкладывай параметры в объект options рядом с data.

Основные операции

1. Список задач (scripts/asana_tasks.sh)

Запускай через встроенный скрипт (путь указан относительно каталога этого скилла): он делает GET на /tasks с фильтром по проекту, тегу, разделу или исполнителю и рабочему пространству, отправляет список opt_fields, проходит по next_page.offset через все страницы и выдаёт TSV или JSONL.

scripts/asana_tasks.sh --project 1201234567890123 --limit 200
scripts/asana_tasks.sh --assignee me --workspace 1209876543210987 --completed-since now

• Нужен ровно один селектор: --project GID, --tag GID, --section GID или --assignee GID --workspace GID (для исполнителя нужно рабочее пространство). --assignee me определяет вызывающего через /users/me.
• --completed-since WHEN — ISO 8601 или now, чтобы показать только незавершённые задачи (опусти, чтобы включить все).
• --fields LIST — какие opt_fields запросить. Столбцы TSV фиксированы (gid, name, completed, assignee, due_on, permalink_url); дополнительные поля появляются только в выводе --json.
• --limit N ограничивает число получаемых задач (по умолчанию 100, 0 = все); --page-size N задаёт страницу на запрос (1–100, по умолчанию 100). Число полученных задач и предупреждение об усечении идут в stderr.
• --json выдаёт по одному необработанному объекту задачи на строку вместо TSV.
• Коды возврата: 0 — успех, 1 — запрос не удался / ошибка API / неверные аргументы (собственное errors[].message API печатается в stderr).

Если скрипт выдаёт ошибку, прочитай его — это обычные curl + jq — и отлаживай по references/api.md.

2. Получить одну задачу

asana "${ASANA_BASE}/tasks/TASK_GID?opt_fields=name,notes,completed,assignee.name,due_on,projects.name,tags.name,parent.name,num_subtasks,custom_fields.name,custom_fields.display_value,permalink_url" \
  | jq '.data'

Без opt_fields ты получишь только компактную запись. Комментарии задачи читай по рецепту 5.

3. Создать задачу

Поля вкладываются в data. Обязательно одно из workspace, projects или parent (самостоятельной задаче нужен workspace).

asana -X POST "${ASANA_BASE}/tasks" -d '{
  "data": {
    "name": "Draft the launch checklist",
    "notes": "Plain-text body. Use html_notes for rich text.",
    "workspace": "1209876543210987",
    "projects": ["1201234567890123"],
    "assignee": "me",
    "due_on": "2026-06-15",
    "followers": ["1200000000000001"]
  }
}' | jq '.data | {gid, name, permalink_url}'

assignee и followers принимают gid пользователей (или me); due_on — дата, due_at — метка времени ISO 8601. Для форматированного текста используй html_notes (подмножество HTML в Asana). Значения пользовательских полей идут в custom_fields: {"FIELD_GID": value}.

4. Обновить или завершить задачу

PUT заменяет только те поля, которые ты отправляешь (по-прежнему обёрнутые в data). Задача завершается установкой completed — отдельной конечной точки для этого нет.

asana -X PUT "${ASANA_BASE}/tasks/TASK_GID" -d '{"data": {"completed": true}}' \
  | jq '.data | {gid, completed, completed_at}'
asana -X PUT "${ASANA_BASE}/tasks/TASK_GID" -d '{"data": {"name": "Revised", "due_on": "2026-07-01"}}'

Удаление: asana -X DELETE "${ASANA_BASE}/tasks/TASK_GID" — возвращает пустой data: {}; задача попадает в корзину.

5. Прокомментировать задачу / прочитать её активность (stories)

Stories — это комментарии задачи плюс системная активность. Создавать можно только комментарии.

# add a comment
asana -X POST "${ASANA_BASE}/tasks/TASK_GID/stories" \
  -d '{"data": {"text": "Reproduced on main."}}' | jq '.data | {gid, created_at}'

# read comments only (filter out system activity client-side)
asana "${ASANA_BASE}/tasks/TASK_GID/stories?opt_fields=resource_subtype,text,created_by.name,created_at" \
  | jq '.data[] | select(.resource_subtype=="comment_added") | {by: .created_by.name, text, created_at}'

Для комментария с форматированием используй html_text вместо text.

6. Поиск задач в рабочем пространстве (премиум)

Расширенный поиск находится на уровне рабочего пространства и доступен только на платных тарифах (premium). Он не поддерживает постраничность по offset (результаты нестабильны, максимум 100) — сужай фильтрами или сортируй по created_at и листай вручную через created_at.before. Для простого «задачи в проекте / мои» лучше использовать скрипт списка (рецепт 1): он проходит все страницы и работает на бесплатных тарифах.

asana -G "${ASANA_BASE}/workspaces/WORKSPACE_GID/tasks/search" \
  --data-urlencode "text=launch" \
  --data-urlencode "assignee.any=me" \
  --data-urlencode "completed=false" \
  --data-urlencode "sort_by=modified_at" \
  --data-urlencode "opt_fields=name,assignee.name,due_on,permalink_url" \
  | jq '.data[] | {gid, name, due_on}'

7. Проекты и разделы

asana -G "${ASANA_BASE}/projects" --data-urlencode "workspace=WORKSPACE_GID" \
  --data-urlencode "archived=false" --data-urlencode "opt_fields=name,owner.name" \
  | jq '.data[] | {gid, name}'
asana "${ASANA_BASE}/projects/PROJECT_GID?opt_fields=name,notes,owner.name,members.name" | jq '.data'
asana "${ASANA_BASE}/projects/PROJECT_GID/sections?opt_fields=name" | jq '.data[] | {gid, name}'

8. Перенос задачи между проектами и разделами

Задача принадлежит проектам через *memberships* (членства). Отдельные POST-запросы добавляют её, убирают или помещают в раздел. Каждый при успехе возвращает пустой data: {}.

asana -X POST "${ASANA_BASE}/tasks/TASK_GID/addProject" \
  -d '{"data": {"project": "PROJECT_GID", "section": "SECTION_GID"}}'
asana -X POST "${ASANA_BASE}/tasks/TASK_GID/removeProject" -d '{"data": {"project": "PROJECT_GID"}}'
asana -X POST "${ASANA_BASE}/sections/SECTION_GID/addTask" -d '{"data": {"task": "TASK_GID"}}'

9. Найти рабочие пространства, пользователей и проекты (поиск gid)

На всё ссылаются по gid — здесь переводи имена в gid.

asana "${ASANA_BASE}/workspaces?opt_fields=name,is_organization" | jq '.data[] | {gid, name}'
asana -G "${ASANA_BASE}/users" --data-urlencode "workspace=WORKSPACE_GID" \
  --data-urlencode "opt_fields=name,email" | jq '.data[] | {gid, name, email}'
asana "${ASANA_BASE}/users/me?opt_fields=name,email,workspaces.name" | jq '.data'

10. Подзадачи, теги и вложения

asana "${ASANA_BASE}/tasks/TASK_GID/subtasks?opt_fields=name,completed" | jq '.data[] | {gid, name}'
asana -X POST "${ASANA_BASE}/tasks/TASK_GID/subtasks" -d '{"data": {"name": "A subtask"}}' | jq '.data.gid'
asana "${ASANA_BASE}/workspaces/WORKSPACE_GID/tags?opt_fields=name" | jq '.data[] | {gid, name}'
asana -X POST "${ASANA_BASE}/tasks/TASK_GID/addTag" -d '{"data": {"tag": "TAG_GID"}}'
asana "${ASANA_BASE}/tasks/TASK_GID/attachments?opt_fields=name,download_url" | jq '.data[] | {gid, name}'

Вложение загружается данными multipart-формы (не JSON) — см. references/api.md, раздел Attachments. Пользовательское поле устанавливается в PUT задачи через {"data": {"custom_fields": {"FIELD_GID": value}}}.

Постраничность

• Токен offset. GET по коллекциям (/tasks, /projects, /users, /stories, ...) принимают limit (1–100) и, когда остаётся ещё, возвращают объект next_page: {"offset": "...", "path": "...", "uri": "..."}. Передай next_page.offset обратно как ?offset=...; остановись, когда next_page равен null. Offset непрозрачен и истекает — используй только тот, что выдал API, и никогда не составляй его сам. scripts/asana_tasks.sh делает это для задач.
• Для поиска offset нет. /workspaces/{gid}/tasks/search игнорирует offset и ограничен 100 результатами в нестабильном порядке — сортируй по created_at и листай через created_at.before (рецепт 6).
• Очень большие наборы результатов (десятки тысяч) могут вернуть 400 с сообщением об усечении — сужай запрос, а не повторяй его.

Ограничения частоты запросов

Ограничения действуют на рабочее пространство и токен, в минуту:

• 150 запросов/мин на бесплатных тарифах, 1500/мин на платных. Поиск — 60/мин.
• Параллелизм: 50 одновременных GET, 15 одновременных записей. Задачи дублирования и экспорта ограничены 5 одновременными на пользователя.
• Отдельный ограничитель по стоимости может отклонять дорогие обходы графа; большинство вызывающих его не достигают.

При 429 подожди столько секунд, сколько указано в Retry-After (по умолчанию около 30, если заголовка нет), и повтори с увеличивающейся паузой — не сокращай интервал опроса.

Обработка ошибок

Любая ошибка заменяет data на errors: {"errors": [{"message": "...", "help": "...", "phrase": "..."}]} (phrase появляется только при 500 — для службы поддержки). Проверяй .errors, прежде чем выбирать .data.

• **400** — неверный запрос: пропущенный или неправильно оформленный параметр, неверная обёртка data или слишком большой для возврата набор результатов. В message названа причина.
• **401** — учётные данные отсутствуют или отклонены. Проверь, что ASANA_TOKEN вообще задан (подойдёт любое значение). Если не проходит, учётные данные для этого рабочего пространства не настроены — сообщи об этом.
• **402** — требуется оплата: функции нужна премиум-организация (например, поиск задач, некоторые операции с пользовательскими полями).
• **403** — доступ запрещён: у пользователя токена нет доступа к этому объекту.
• **404** — не найдено: неверный gid или несуществующий объект; некоторые закрытые объекты тоже могут отдавать 404, а не 403.
• **429** — превышен лимит частоты. Подожди по Retry-After, затем повтори с увеличивающейся паузой.
• **451** — недоступно по юридическим причинам (IP под эмбарго).
• **5xx** — сбой на стороне Asana. Повторяй чтения с увеличивающейся паузой; при эскалации цитируй errors[].phrase.

Углубиться

В references/api.md есть более полный каталог — полная модель полей и членств (memberships) задачи, разметка html_notes/html_text, разделы и изменение порядка, зависимости, пользовательские поля и варианты enum, вложения (загрузка multipart), теги, команды и портфели, статусы проектов, вебхуки (обмен X-Hook-Secret), batch API и события журнала аудита. Читай его, когда нужна конечная точка, не описанная выше, или точная форма тела для записи.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/asana/skills/asana-api, лицензия Apache-2.0. Изменения: перевод на русский язык.