Перейти к содержанию

Пользователи

Раздел «Пользователи» (users) отвечает за учётные записи в организации: их список, поиск по email или группе, данные конкретного пользователя по логину или uid, а также данные пользователя, от имени которого выполняются запросы к API. yatracker предоставляет методы для получения этой информации; создание, изменение и удаление учётных записей API Трекера не поддерживает.

Обратите внимание

Как и все методы YaTracker, методы работы с пользователями являются асинхронными. В примерах ниже вызовы показаны так, как будто мы уже находимся внутри корутины.

Официальная документация: https://yandex.ru/support/tracker/ru/api/users/get-users

Список пользователей

get_users

async def get_users(
    self,
    per_page: int | None = None,
    page: int | None = None,
    *,
    id_: str | int | None = None,
    email: str | None = None,
    group: str | int | None = None,
    expand: str | None = None,
) -> list[FullUser]: ...

Возвращает список пользователей организации.

users = await tracker.get_users(expand="groups")

for user in users:
    print(user.uid, user.display)
  1. per_page — количество пользователей на странице, от 1 до 100.
  2. page — номер страницы (по умолчанию 1).
  3. id_ — uid пользователя, начиная с которого нужно искать (query-параметр id).
  4. email — вернуть только пользователя с таким email.
  5. group — вернуть только пользователей указанной группы.
  6. expand — дополнительные поля в ответе: "groups" — группы, в которые входят пользователи.

Ограничение в 10 000 пользователей

Этот запрос отдаёт не больше 10 000 пользователей. Для больших организаций используйте get_users_relative или iter_users — они не ограничены сверху.

Источник: https://yandex.ru/support/tracker/ru/api/users/get-users

get_users_relative

async def get_users_relative(
    self,
    per_page: int | None = None,
    id_: str | int | None = None,
    expand: str | None = None,
) -> UsersPage: ...

Возвращает одну страницу пользователей с относительной пагинацией — в отличие от get_users, этот запрос не ограничен 10 000 записей.

page = await tracker.get_users_relative(per_page=50)

if page.has_next:
    next_page = await tracker.get_users_relative(
        per_page=50,
        id_=page.users[-1].uid,
    )
  1. per_page — количество пользователей на странице, от 1 до 100.
  2. id_ — uid пользователя, начиная с которого нужно искать (query-параметр id). Не передавайте его, чтобы получить первую страницу.
  3. expand — дополнительные поля в ответе: "groups" — группы, в которые входят пользователи.

Пользователи в ответе отсортированы по возрастанию uid. Чтобы получить следующую страницу, передайте в id_ значение uid последнего пользователя предыдущей страницы; UsersPage.has_next говорит, остались ли ещё страницы.

Источник: https://yandex.ru/support/tracker/ru/api/users/get-users-relative

iter_users

Чтобы не управлять пагинацией вручную, используйте iter_users — асинхронный генератор поверх get_users_relative:

async def iter_users(
    self,
    per_page: int | None = None,
    expand: str | None = None,
) -> AsyncIterator[FullUser]: ...

async for user in tracker.iter_users(per_page=50, expand="groups"):
    print(user.uid, user.display)
  1. per_page — количество пользователей, запрашиваемых за один вызов get_users_relative.
  2. expand — дополнительные поля в ответе: "groups" — группы, в которые входят пользователи.

Каждая следующая страница запрашивается с uid последнего пользователя предыдущей. Документация описывает id как пользователя, с которого начинается следующая страница, поэтому пользователь-курсор может вернуться ещё раз в начале следующей страницы — если uid пользователя совпадает с курсором (id_), iter_users не отдаёт его повторно. Итерация останавливается, когда очередная страница пуста, когда has_next равен False, а также — на случай зацикливания — когда страница не продвигается дальше курсора (последний uid страницы равен курсору), даже если API продолжает сообщать has_next=true.

per_page=1 отправляется как perPage=2

Курсор id включающий: пользователь-курсор возвращается ещё раз в начале следующей страницы. Поэтому страница из одного пользователя могла бы содержать только сам курсор, и итерация остановилась бы после первого пользователя. Чтобы этого не происходило, per_page=1 отправляется в API как perPage=2.

Источник: https://yandex.ru/support/tracker/ru/api/users/get-users-relative

Один пользователь

get_user

async def get_user(
    self,
    user_id: str | int,
    expand: str | None = None,
) -> FullUser: ...

Возвращает одного пользователя организации по uid или логину.

user = await tracker.get_user("username")
user = await tracker.get_user(1120000000012345, expand="groups")

# логин, состоящий только из цифр, нужно указывать с префиксом "login:"
user = await tracker.get_user("login:12345")
  1. user_id — uid или логин пользователя. Логин, состоящий только из цифр, нужно передавать с префиксом login: ("login:12345"), иначе он будет воспринят как uid.
  2. expand — дополнительные поля в ответе: "groups" — группы, в которые входит пользователь.

Источник: https://yandex.ru/support/tracker/ru/api/users/get-user

get_myself

async def get_myself(self, expand: str | None = None) -> FullUser: ...

Возвращает учётную запись, от имени которой выполняются запросы к API.

me = await tracker.get_myself()
print(me.uid, me.display)
  1. expand — дополнительные поля в ответе: "groups" — группы, в которые входит пользователь.

Источник: https://yandex.ru/support/tracker/ru/api/users/get-user-info

Модели

FullUser

Полная учётная запись пользователя — то, что возвращают get_users, get_users_relative, get_user и get_myself. Это не наследник User ниже: в ответах этих запросов пользователь адресуется по uid, а не по id.

Поле Тип Описание
url str Ссылка на учётную запись (в API — поле self)
uid str Уникальный идентификатор учётной записи в Трекере
login str Логин пользователя
display str Отображаемое имя пользователя
id str \| None Идентификатор пользователя. В справочнике этих запросов не указан (пользователь адресуется по uid); поле оставлено опциональным на случай, если в ответ попадёт короткая ссылка на пользователя, использованная как FullUser
tracker_uid str \| None Уникальный идентификатор учётной записи в Трекере
passport_uid str \| None Уникальный идентификатор аккаунта в Яндекс 360 для бизнеса / Яндекс ID
cloud_uid str \| None Уникальный идентификатор пользователя в Yandex Identity Hub
first_name str \| None Имя пользователя
last_name str \| None Фамилия пользователя
email str \| None Email пользователя
groups list[Ref] \| None Группы, в которые входит пользователь. Присутствует только при expand="groups", иначе None
external bool \| None Служебный параметр
has_license bool \| None Есть ли у пользователя полный доступ к Трекеру: True — полный доступ, False — только чтение
dismissed bool \| None Удалён ли пользователь из организации
use_new_filters bool \| None Служебный параметр
disable_notifications bool \| None Принудительно ли отключены уведомления для пользователя
first_login_date datetime \| None Дата и время первой авторизации в Трекере
last_login_date datetime \| None Дата и время последней авторизации в Трекере
welcome_mail_sent bool \| None Как пользователь был добавлен: True — приглашением на почту, False — иначе
sources list[str] \| None Источники данных учётной записи, например ["directory"] для корпоративного каталога. Документировано только для get_users_relative
position str \| None Должность пользователя. Документировано только для get_users_relative и отсутствует в примерах ответа

has_license

has_license=False не означает, что пользователя нет в организации — это может быть учётная запись с доступом только на чтение (без лицензии). Для статуса «уволен» из организации смотрите dismissed.

UsersPage

Страница пользователей, которую возвращает get_users_relative.

Поле Тип Описание
users list[FullUser] Пользователи текущей страницы, отсортированные по возрастанию uid
has_next bool Есть ли ещё страницы

User

Короткая ссылка на пользователя, которой в других объектах API (задачах, очередях, комментариях и т. п.) представлен автор, исполнитель и подобные роли. Это не то же самое, что FullUser — в User нет ни email, ни дат авторизации, ни группы.

Поле Тип Описание
url str Ссылка на пользователя (в API — поле self)
id str Идентификатор пользователя
display str Отображаемое имя пользователя
passport_uid int \| None Уникальный идентификатор аккаунта в Яндекс 360 для бизнеса / Яндекс ID
cloud_uid str \| None Уникальный идентификатор пользователя в Yandex Identity Hub

Идентификаторы аккаунта могут отсутствовать

passportUid и cloudUid приходят в большинстве ответов API (в том числе в createdBy, assignee, updatedBy и подобных вложенных объектах), но документация не гарантирует их наличие, поэтому оба поля необязательные. passport_uid — число (как и в ChecklistAssignee), cloud_uid — строка.

Типичный сценарий

Узнать, от чьего имени работает интеграция, затем пройтись по всем пользователям организации, которые входят хотя бы в одну группу:

me = await tracker.get_myself()
print("Работаем от имени:", me.display)

async for user in tracker.iter_users(per_page=100, expand="groups"):
    if user.groups:
        print(user.login, [group.display for group in user.groups])