Активность проекта

Получите и отслеживайте ленты активности проектов с помощью Blue API.

Получение активности проекта

Запрос activityList предоставляет доступ к комплексной ленте активности для проектов и компаний. Деятельность автоматически генерируется, когда пользователи выполняют действия, такие как создание задач, комментариев или внесение изменений в проект.

Простой пример

query ProjectActivity {
  activityList(
    projectId: "your-project-id"
    first: 20
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Расширенный пример с фильтрацией

query FilteredActivity {
  activityList(
    companyId: "your-company-id"
    categories: [CREATE_TODO, MARK_TODO_AS_COMPLETE, CREATE_COMMENT]
    userIds: ["user1-id", "user2-id"]
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-12-31T23:59:59Z"
    first: 50
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      uid
      category
      html
      createdAt
      updatedAt
      createdBy {
        id
        name
        email
      }
      affectedBy {
        id
        name
      }
      todo {
        id
        title
      }
      comment {
        id
        text
      }
      project {
        id
        name
        slug
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Входные параметры

Запрос activityList

Параметр	Тип	Обязательный	Описание
`companyId`	String	Нет	Фильтровать активности по ID компании или слагу
`projectId`	String	Нет	Фильтровать активности по ID проекта или слагу
`userId`	String	Нет	Фильтровать активности по конкретному пользователю
`userIds`	[String!]	Нет	Фильтровать активности по нескольким пользователям
`tagIds`	[String!]	Нет	Фильтровать активности по тегам задач
`categories`	[ActivityCategory!]	Нет	Фильтровать по конкретным типам активности
`startDate`	DateTime	Нет	Фильтровать активности с этой даты
`endDate`	DateTime	Нет	Фильтровать активности до этой даты
`skip`	Int	Нет	Пропустить это количество записей (пагинация смещения)
`first`	Int	Нет	Вернуть первые N записей (пагинация курсора)
`last`	Int	Нет	Вернуть последние N записей (пагинация курсора)
`after`	String	Нет	Вернуть записи после этого курсора
`before`	String	Нет	Вернуть записи до этого курсора
`orderBy`	ActivityOrderByInput	Нет	Порядок сортировки для результатов

Значения ActivityCategory

Система автоматически отслеживает различные типы активности:

Категория	Описание
`CREATE_TODO`	Создана новая задача/дело
`MARK_TODO_AS_COMPLETE`	Задача помечена как завершенная
`CREATE_COMMENT`	Добавлен комментарий
`CREATE_DISCUSSION`	Начата дискуссия
`CREATE_STATUS_UPDATE`	Опубликовано обновление статуса
`CREATE_TODO_LIST`	Создан новый список задач
`MOVE_TODO`	Задача перемещена между списками
`COPY_TODO`	Задача скопирована
`ADD_USER_TO_PROJECT`	Пользователь добавлен в проект
`REMOVE_USER_FROM_PROJECT`	Пользователь удален из проекта
`ARCHIVE_PROJECT`	Проект был архивирован
`UNARCHIVE_PROJECT`	Проект был разархивирован
`CREATE_INVITATION`	Пользователь был приглашен
`ACCEPT_INVITATION`	Приглашение было принято
`CREATE_CUSTOM_FIELD`	Создано пользовательское поле
`RECEIVE_FORM`	Получена форма отправки

Значения ActivityOrderByInput

Значение	Описание
`createdAt_DESC`	Сначала самые последние (по умолчанию)
`createdAt_ASC`	Сначала самые старые
`updatedAt_DESC`	Сначала самые недавно обновленные
`updatedAt_ASC`	Сначала самые редко обновленные
`category_ASC`	Алфавитный порядок по категории
`category_DESC`	Обратный алфавитный порядок по категории

Поля ответа

Тип активности

Поле	Тип	Описание
`id`	ID!	Уникальный идентификатор для активности
`uid`	String!	Альтернативный уникальный идентификатор
`category`	ActivityCategory!	Тип активности, которая произошла
`html`	String!	Полное HTML-описание активности
`createdAt`	DateTime!	Когда произошла активность
`updatedAt`	DateTime!	Когда активность была в последний раз обновлена
`createdBy`	User!	Пользователь, который выполнил действие
`affectedBy`	User	Пользователь, на которого повлияло действие
`company`	Company	Связанная компания
`project`	Project	Связанный проект
`todo`	Todo	Связанная задача (если применимо)
`todoList`	TodoList	Связанный список задач (если применимо)
`comment`	Comment	Связанный комментарий (если применимо)
`discussion`	Discussion	Связанная дискуссия (если применимо)
`statusUpdate`	StatusUpdate	Связанное обновление статуса (если применимо)
`metadata`	String	Дополнительные метаданные активности

Ответ ActivityList

Поле	Тип	Описание
`activities`	[Activity!]!	Массив записей активности
`pageInfo`	PageInfo!	Информация о пагинации
`totalCount`	Int!	Общее количество активностей, соответствующих фильтрам

Обновления активности в реальном времени

Подпишитесь на изменения активности, используя подписку subscribeToActivity:

subscription ActivityUpdates($companyId: String!, $projectId: String) {
  subscribeToActivity(companyId: $companyId, projectId: $projectId) {
    mutation
    node {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
  }
}

Параметры подписки

Параметр	Тип	Обязательный	Описание
`companyId`	String	Нет	Подписаться на активность по всей компании
`projectId`	String	Нет	Подписаться на активность конкретного проекта

Подписка уведомит вас о:

ACTIVITY_CREATED - Новые активности
ACTIVITY_UPDATED - Измененные активности
ACTIVITY_DELETED - Удаленные активности

Фильтрация и конфиденциальность

Автоматическая фильтрация

Лента активности автоматически фильтрует результаты на основе:

Настройки проекта: Показывает только активности из проектов с включенным отслеживанием активности
Разрешения пользователей: Разные роли пользователей видят разные типы активности
Членство в проекте: Пользователи видят только активности из проектов, к которым у них есть доступ
Членство в компании: Активности ограничены компаниями пользователя

Соображения конфиденциальности

Пользователи с ролью CLIENT имеют ограниченную видимость определенных административных действий
Активности соответствуют настройкам конфиденциальности на уровне проекта
Чувствительные операции могут не генерировать публичные активности

Ответы на ошибки

Неверный проект/компания

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Доступ запрещен

{
  "errors": [{
    "message": "You do not have permission to view activities for this project",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Неверный диапазон дат

{
  "errors": [{
    "message": "Start date must be before end date",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Лучшие практики

Используйте пагинацию: Ленты активности могут быть большими, всегда используйте параметр first
Фильтруйте по проекту: Ленты активности по всей компании могут быть перегружены
Обновления в реальном времени: Используйте подписки для живых лент активности
Фильтрация по дате: Используйте диапазоны дат для анализа исторической активности
Фильтрация по категории: Фильтруйте по конкретным типам активности для целевых лент
Фильтрация по пользователям: Отслеживайте активности конкретных членов команды с помощью userIds

Важные заметки

Активности автоматически генерируются и не могут быть созданы вручную через API
Текст активности использует HTML-форматирование для богатого отображения
Поле text устарело в пользу html
Активности навсегда хранятся и предоставляют полный аудит
Подписки в реальном времени требуют аутентификации соединения WebSocket