Использование API для работы с учетными записями, ролями и организациями
Клиент access предоставляет инструменты для работы с пользователями и организациями.
Методы API разделены на следующие группы:
Описания и примеры приведены для TypeScript (среда выполнения Deno) и Python.
Подготовка клиента для работы с пользователями и организациями
Чтобы работать с отчетами с помощью пакета SDK, импортируйте его и инициализируйте клиент:
import * as sdk from '@playbooks/sdk '
...
export async function main() {
const v = await sdk.access.<method_name>({ <arg_1>, <arg_2>, ... })
console.log(v)
}
from playbooks.report import AccessClient
...
def main():
client = AccessClient.initialize()
v = client.<method_name>(<arg_1>, <arg_2>, ...)
print(v)
Методы для работы с учетными записями пользователей
Клиент позволяет получать данные пользователей через следующие методы:
-
данные пользователя по заданному UUID (
get_user); -
данные текущего пользователя (
get_current_user); -
полный список системных пользователей с возможностью фильтрации (
list_users).
Для назначения ролей пользователю используйте метод add_roles_to_user.
|
Возвращаемые данные пользователя
Методы, возвращающие данные пользователя, предоставляют объект со следующими полями:
-
id: идентификатор (UUID); -
username: логин; -
is_parmanently_blocked: заблокирован ли пользователь; -
is_super_admin: имеет ли пользователь статус Суперадминистратор; -
failed_login_attempts: количество неудачных попыток входа в систему; -
group_ids: идентификаторы групп пользователя; -
role_ids: идентификаторы ролей; -
source: источник создания; -
status: статус пользователя — активный или заблокированный; -
type: тип учетной записи; -
record_date_time: время изменений учетной записи:-
created_at: дата и время создания; -
updated_at: дата и время последнего изменения; -
deleted_at: дата и время удаления;
-
-
is_password_valid: соответствует ли пароль требованиям парольной политики (если применимо); -
blocked_by: пользователь, заблокировавший учетную запись (если применимо); -
blocked_until: срок блокировки пользователя (если применимо); -
created_by: пользователь, инициировавший создание учетной записи (если применимо); -
deleted_by: пользователь, удаливший учетную запись (если применимо); -
descrtiption: описание учетной записи (если указано); -
email: адрес электронной почты (если указан); -
fullname: полное имя пользователя (если указано); -
last_visit_at: время последнего входа (если применимо); -
ldap_connection_id: идентификатор интеграции с LDAP-сервером (если применимо); -
password_expired_at: время истечения срока действия пароля (если применимо); -
password_updated_at: время последнего изменения пароля (если применимо); -
phone: номер телефона (если указан); -
position: должность (если указана); -
updated_by: пользователь, последним изменивший учетную запись (если применимо).
Получение данных о пользователе (get_user)
Метод используется для получения данных определенного пользователя.
get_user в TypeScriptget_user({
id: <user_id> // string
})
get_user в Pythonget_user(
id=<user_id> # str
)
В методе используется следующий параметр:
-
<user_id>— UUID пользователя (строка).
Метод возвращает объект запрошенного пользователя.
Примеры получения данных о пользователе
Пример скрипта с get_user в TypeScript
id: get_user_deno
name: Получение информации о другом пользователе
version: 0.0.1
type: script
source: !deno |
import * as sdk from "@playbooks/sdk"
export async function main() {
try {
const userId = "c74bbab9-f6a8-4a6f-9b6f-f63c8b6abb79";
console.log(`Получение пользователя по ID: ${userId}`);
const user = await sdk.access.get_user({ id: userId });
console.log(` Найден пользователь: ${user.username}`);
console.log(` Email: ${user.email || 'N/A'}`);
console.log(` Status: ${user.status}`);
console.log(` Группы: ${user.groupIds.length}`);
console.log(` Роли: ${user.roleIds.length}`);
// Краткие метаданные для пользователя.
console.log(` Основные метаданные:`);
console.log(` • SuperAdmin: ${user.isSuperAdmin}`);
console.log(` • Source: ${user.source}`);
console.log(` • Type: ${user.type}`);
if (user.recordDatetime) {
const rdt = user.recordDatetime;
console.log(` • Created: ${rdt.createdAt || 'N/A'}`);
console.log(` • Updated: ${rdt.updatedAt || 'N/A'}`);
}
console.log(` • Fullname: ${user.fullname || 'N/A'}`);
console.log(` • Position: ${user.position || 'N/A'}`);
console.log(` • Last visit: ${user.lastVisitAt || 'N/A'}`);
} catch (error) {
console.error(` Ошибка при получении пользователя ${userId}: ${error}`);
}
}
Пример скрипта с get_user в Python
id: get_user_py
name: Получение информации о другом пользователе
version: 0.0.1
type: script
source: !py |
from playbooks.access import AccessClient
def main():
client = AccessClient.initialize()
user_id = 'c74bbab9-f6a8-4a6f-9b6f-f63c8b6abb79'
print(f" Получение другого пользователя по ID: {user_id}")
try:
user = client.get_user(id=user_id)
print(f" Найден пользователь: {user.username}")
print(f" Email: {user.email}")
print(f" Status: {user.status}")
print(f" Группы: {len(user.group_ids)}")
print(f" Роли: {len(user.role_ids)}")
print(f" Основные метаданные:")
print(f" • SuperAdmin: {user.is_super_admin}")
print(f" • Source: {user.source}")
print(f" • Type: {user.type}")
if hasattr(user, 'record_date_time') and user.record_date_time:
rdt = user.record_date_time
print(f" • Created: {rdt.created_at or 'N/A'}")
print(f" • Updated: {rdt.updated_at or 'N/A'}")
print(f" • Fullname: {user.fullname or 'N/A'}")
print(f" • Position: {user.position or 'N/A'}")
print(f" • Last visit: {user.last_visit_at or 'N/A'}")
except Exception as e:
print(f" Ошибка при получении пользователя {user_id}: {e}")
Получение данных о текущем пользователе (get_current_user)
Метод используется для получения данных текущего пользователя.
get_current_user()
Метод возвращает объект текущего пользователя.
Примеры получения данных о текущем пользователе
Пример скрипта с get_current_user в TypeScript
id: get_user_deno_current
name: Получение записи о текущем пользователе
version: 0.0.1
type: script
source: !deno |
import * as sdk from "@playbooks/sdk"
export async function main() {
try {
const currentUser = await sdk.access.get_current_user()
console.log(` ${currentUser.username} (${currentUser.email || 'N/A'})`);
console.log(` Status: ${currentUser.status}, SuperAdmin: ${currentUser.isSuperAdmin}`);
// Вывод всех метаданных текущего пользователя.
console.log(" Метаданные текущего пользователя:");
console.log(` • ID: ${currentUser.id}`);
console.log(` • Permanently blocked: ${currentUser.isPermanentlyBlocked}`);
console.log(` • Failed login attempts: ${currentUser.failedLoginAttempts}`);
console.log(` • Source: ${currentUser.source}`);
console.log(` • Type: ${currentUser.type}`);
console.log(` • Valid password: ${currentUser.isPasswordValid || 'N/A'}`);
console.log(` • Groups: ${currentUser.groupIds.length}`);
console.log(` • Roles: ${currentUser.roleIds.length}`);
// Даты.
if (currentUser.recordDatetime) {
const rdt = currentUser.recordDatetime;
console.log(` • Created: ${rdt.createdAt || 'N/A'}`);
console.log(` • Updated: ${rdt.updatedAt || 'N/A'}`);
console.log(` • Deleted: ${rdt.deletedAt || 'N/A'}`);
}
// Опциональные поля.
console.log(` • Blocked by: ${currentUser.blockedBy || 'N/A'}`);
console.log(` • Blocked until: ${currentUser.blockedUntil || 'N/A'}`);
console.log(` • Created by: ${currentUser.createdBy || 'N/A'}`);
console.log(` • Deleted by: ${currentUser.deletedBy || 'N/A'}`);
console.log(` • Description: ${currentUser.description || 'N/A'}`);
console.log(` • Fullname: ${currentUser.fullname || 'N/A'}`);
console.log(` • Last visit: ${currentUser.lastVisitAt || 'N/A'}`);
console.log(` • LDAP ID: ${currentUser.ldapConnectionId || 'N/A'}`);
console.log(` • Password expired: ${currentUser.passwordExpiredAt || 'N/A'}`);
console.log(` • Password updated: ${currentUser.passwordUpdatedAt || 'N/A'}`);
console.log(` • Phone: ${currentUser.phone || 'N/A'}`);
console.log(` • Position: ${currentUser.position || 'N/A'}`);
console.log(` • Updated by: ${currentUser.updatedBy || 'N/A'}`);
} catch (error) {
// Вывод ошибки в консоль, если произошла ошибка при получении данных пользователя.
console.log(error)
}
}
Пример скрипта с get_current_user в Python
id: get_user_py_current
name: Получение записи о текущем пользователе
version: 0.0.1
type: script
source: !py |
from playbooks.access import AccessClient
def main():
client = AccessClient.initialize()
try:
current_user = client.get_current_user()
print(f"{current_user.username} ({current_user.email})")
print(f"Status: {current_user.status}, SuperAdmin: {current_user.is_super_admin}")
# Вывод всех метаданных текущего пользователя с проверкой атрибутов.
print("Метаданные текущего пользователя:")
print(f" • ID: {current_user.id}")
if hasattr(current, 'is_parmanently_blocked'):
print(f" • Permanently blocked: {current_user.is_parmanently_blocked}")
else:
print(f" • Permanently blocked: атрибут недоступен")
print(f" • Failed login attempts: {current_user.failed_login_attempts}")
print(f" • Source: {current_user.source}")
print(f" • Type: {current_user.type}")
if hasattr(current, 'is_password_valid'):
print(f" • Valid password: {current_user.is_password_valid}")
else:
print(f" • Valid password: атрибут недоступен")
print(f" • Groups: {len(current_user.group_ids)}")
print(f" • Roles: {len(current_user.role_ids)}")
if hasattr(current_user, 'record_date_time') and current_user.record_date_time:
rdt = current_user.record_date_time
print(f" • Created: {rdt.created_at or 'N/A'}")
print(f" • Updated: {rdt.updated_at or 'N/A'}")
print(f" • Deleted: {rdt.deleted_at or 'N/A'}")
optional_fields = [
'blocked_by', 'blocked_until', 'created_by', 'deleted_by','descrtiption', 'fullname', 'last_visit_at', 'ldap_connection_id','password_expired_at', 'password_updated_at', 'phone', 'position','updated_by'
]
for field in optional_fields:
if hasattr(current_user, field):
value = getattr(current_user, field) or 'N/A'
print(f" • {field.replace('_', ' ').title()}: {value}")
else:
print(f" • {field.replace('_', ' ').title()}: атрибут недоступен")
except Exception as e:
print(f" Ошибка при получении пользователя {current_user.id}: {e}")
Получение списка пользователей (list_users)
Метод используется для получения отфильтрованного и отсортированного массива данных необходимых пользователей. Фильтры для уточнения запроса, порядок сортировки и количество выводимых результатов задаются с помощью параметров.
list_users в TypeScriptlist_users(
filter: {
groupIds: <group_ids>, // string[]
roleIds: <role_ids>, // string[]
sources: <sources>, // string[]
statuses: <statuses>, // string[]
types: <types>, // string[]
updatedSince: <updated_since>, // string | undefined
isSuperAdmin: <is_super_admin>, // boolean | undefined
query: <query> // string | undefined
},
page_request: {
countTotal: <count_total>, // boolean
key: <key>, // Buffer
limit: <limit>, // number
reverse: <reverse>, // boolean
offset: <offset> // string | undefined
},
order_by: <order_by> // string | undefined
)
list_users в Pythonlist_users(
filter={
"group_ids": <group_ids>, # List[str]
"role_ids": <role_ids>, # List[str]
"sources": <sources>, # List[enum]
"statuses": <statuses>, # List[enum]
"types": <types>, # List[enum]
"updated_since": <updated_since>, # str | None
"is_super_admin": <is_super_admin>, # bool | None
"query": <query> # str | None
},
page_request={
"count_total": <count_total>, # bool
"limit": <limit>, # int
"reverse": <reverse>, # bool
"offset": <offset> # str | None
},
order_by=<order_by> # str | None
)
Параметры метода включают в себя:
-
Настройки фильтрации списка (необязательный блок):
-
<group_ids>: идентификаторы групп пользователей (массив строк); -
<role_ids>: идентификаторы ролей пользователей (массив строк); -
<sources>: источники создания пользователей (массив значений перечисления); -
<statuses>: статусы пользователей (массив значений перечисления); -
<types>: типы пользователей (массив значений перечисления); -
<updated_since>(необязательный): дата, начиная с которой были обновлены учетные записи (строка); -
<is_super_admin>(необязательный): являются ли пользователи суперадминистраторами (логическое значение); -
<query>(необязательный): запрос для поиска по полямusername,fullname,position(строка);
-
-
Ограничение количества выводимых результатов (необязательный блок):
-
<count_total>: флаг включения общего количества записей в ответ (логическое значение); -
<key>: ключ для продолжения постраничного вывода на основе значения, возвращенного сервером в предыдущем ответе (байтовое значение). Не используется вместе с параметромlimit:; -
<limit>: максимальное количество записей в ответе (число); -
<reverse>: флаг сортировки по убыванию (логическое значение); -
<offset>(необязательный): порядковый номер первой записи, начиная с которой выводится ответ (число);
-
-
<order_by>(необязательный): поле, по которому сортируется список (строка).
Метод возвращает массив объектов пользователей.
Примеры получения списка пользователей
В приведенных примерах скрипт запрашивает список учетных записей, обновленных за последние 30 дней.
Пример скрипта с list_users в TypeScript
id: all_system_users_deno
name: all_system_users_deno
version: 0.0.1
type: script
source: !deno |
import * as sdk from '@playbooks/sdk'
export async function main() {
try {
// Дата 30 дней назад.
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
.toISOString();
console.log(`Пользователи, обновленные за последние 30 дней: ${thirtyDaysAgo}`);
const updatedUsers = await sdk.access.list_users({
filter: {
groupIds: [],
roleIds: [],
sources: [],
statuses: [],
types: [],
updatedSince: thirtyDaysAgo
}
});
console.log(` Найдено пользователей, обновленных после ${thirtyDaysAgo}: ${updatedUsers.length}`);
updatedUsers.forEach((user, index) => {
const updatedAt = user.recordDatetime?.updatedAt;
console.log(` ${index + 1}. ${user.username} - Обновлен: ${updatedAt || 'N/A'} - Статус: ${user.status}`);
});
} catch (error: any) {
console.error(` Ошибка: ${error}`);
if (error.details) {
console.log(` Детали ошибки: ${JSON.stringify(error.details, null, 2)}`);
}
}
Пример скрипта с list_users в Python
id: all_system_users__py
name: all_system_users_py
description: Получение данных пользователей с фильтрацией
type: script
source: !py |
from playbooks.access import AccessClient
from datetime import datetime, timedelta
def main():
client = AccessClient.initialize()
thirty_days_ago = (datetime.now() - timedelta(days=30)).strftime('%Y-%m-%dT%H:%M:%SZ')
print(f"Пользователи, обновленные за последние 30 дней ({thirty_days_ago}):")
try:
recent_users = client.list_users(
filter={
"group_ids": [],
"role_ids": [],
"sources": [],
"statuses": [],
"types": []
"updated_since": thirty_days_ago
}
)
if isinstance(recent_users, list):
print(f" Найдено обновленных пользователей: {len(recent_users)}")
for i, u in enumerate(recent_users[:5], 1):
if hasattr(u, 'record_date_time') and u.record_date_time:
updated = u.record_date_time.updated_at or 'N/A'
print(f" {i}. {u.username} - Обновлен: {updated}")
else:
print(f" {i}. {u.username} - Дата обновления недоступна")
else:
print(f" 📋 Получен объект: {recent_users.username}")
except Exception as e:
print(f" Ошибка: {e}")
print()
Методы для работы с ролями
Методы для работы с ролями включают:
-
создание роли (
create_role); -
добавление разрешений для роли (
add_permission_to_role); -
назначение ролей пользователю (
add_roles_to_user).
Создание роли (create_role)
Метод create_role позволяет создать новую роль в системе.
create_role в TypeScriptcreate_role({
id: <role_id>, // string | undefined
name: <name>, // string
tenantId: <tenant_id>, // string
description: <description>, // string | undefined
isSystem: <is_system>, // boolean
permissionKeys: <permission_keys>, // string[]
frontendPermissionKeys: <frontend_permission_keys> // string[]
})
create_role в Pythoncreate_role(
id=<role_id>, # str | None
name=<name>, # str
tenant_id=<tenant_id>, # str
description=<description>, # str | None
is_system=<is_system>, # bool
permission_keys=<permission_keys>, # List[str]
frontend_permission_keys=<frontend_permission_keys> # List[str]
)
Параметры метода включают:
-
<role_id>(необязательный): уникальный идентификатор роли (строка); -
<name>: название роли (строка); -
<tenant_id>: идентификатор тенанта (строка); -
<description>(необязательный): описание роли (строка); -
<is_system>: переключатель создания роли как системной (логическое значение); -
<permission_keys>: идентификаторы разрешений роли (массив строк); -
<frontend_permission_keys>: идентификаторы разрешений роли на действия в интерфейсе (массив строк).
Метод возвращает идентификатор созданной роли.
Примеры создания роли
Пример скрипта с create_role в TypeScript
id: create_role_ts
name: create_role_ts
description: Создание роли
version: 0.0.1
type: script
source: !deno |
import * as sdk from "@playbooks/sdk"
const ORG_ID = "00000000-0000-0000-0000-000000000000"
export async function main() {
// Создаем роль с фронтенд-разрешением на просмотр экспертизы.
const roleId = await sdk.access.create_role({
frontendPermissionKeys: ['evo.streams.expertise.view'],
isSystem: false,
name: 'testRole1',
permissionKeys: [],
tenantId: [ORG_ID],
})
}
Пример скрипта с create_role в Python
id: create_role_py
name: create_role_py
version: 0.0.1
type: script
source: !py |
from playbooks.access import AccessClient, UserRole
ORG_ID = '00000000-0000-0000-0000-000000000000'
def main():
client = AccessClient.initialize()
# Создаем роль с фронтенд-разрешением на просмотр экспертизы.
role_id = client.create_role(frontend_permission_keys=['evo.streams.expertise.view'], permission_keys=[], is_system=False, name='testRole2', tenant_id=ORG_ID)
Добавление разрешений для роли (add_permission_to_role)
Метод используется для расширения набора разрешений существующей роли.
add_permissions_to_role в TypeScriptadd_permissions_to_role({
id: <role_id>, // string
permissionKeys: <permission_keys>, // string[]
frontendPermissionKeys: <frontend_permission_keys> // string[]
})
add_permissions_to_role в Pythonadd_permissions_to_role(
id=<role_id>, # str
permission_keys=<permission_keys>, # List[str]
frontend_permission_keys=<frontend_permission_keys> # List[str]
)
Параметры метода включают:
-
<role_id>: идентификатор роли (строка); -
<permission_keys>: идентификаторы разрешений, которые нужно добавить для роли (массив строк); -
<frontend_permission_keys>: идентификаторы разрешений на действия в интерфейсе, которые нужно добавить для роли (массив строк).
Метод возвращает идентификатор обновленной роли.
Примеры добавления разрешений для роли
Пример скрипта с add_permission_to_role в TypeScript
id: add_permission_to_role_ts
name: add_permission_to_role_ts
description: Создание роли
version: 0.0.1
type: script
source: !deno |
import * as sdk from "@playbooks/sdk"
const ORG_ID = "00000000-0000-0000-0000-000000000000"
export async function main() {
// Создаем роль с фронтенд-разрешением на просмотр экспертизы.
const roleId = await sdk.access.create_role({
frontendPermissionKeys: ['evo.streams.expertise.view'],
isSystem: false,
name: 'testRole3',
permissionKeys: [],
tenantId: [ORG_ID],
})
// Добавляем к созданной роли фронтенд-разрешение на просмотр конфигураций.
await sdk.access.add_permissions_to_role({
frontendPermissionKeys: ['evo.playbooks.resources.configurations.management.view'],
id: roleId,
permissionKeys: [],
})
}
Пример скрипта с add_permission_to_role в Python
id: add_permission_to_role_py
name: add_permission_to_role_py
version: 0.0.1
type: script
source: !py |
from playbooks.access import AccessClient, UserRole
ORG_ID = '00000000-0000-0000-0000-000000000000'
def main():
client = AccessClient.initialize()
# Создаем роль с фронтенд-разрешением на просмотр экспертизы.
role_id = client.create_role(frontend_permission_keys=['evo.streams.expertise.view'], permission_keys=[], is_system=False, name='testRole4', tenant_id=ORG_ID)
# Добавляем к созданной роли фронтенд-разрешение на просмотр конфигураций.
client.add_permissions_to_role(frontend_permission_keys=['evo.playbooks.resources.configurations.management.view'], id=role_id, permission_keys=[])
Назначение ролей пользователю (add_roles_to_user)
Метод add_roles_to_user позволяет назначить пользователю одну или несколько ролей.
add_roles_to_user в TypeScriptadd_roles_to_user({
id: <user_id>, // string
roles: [
{
id: <policy_id>, // string | None
roleId: <role_id>, // string
organizationIds: <org_ids> // string[]
}
]
})
add_roles_to_user в Pythonadd_roles_to_user(
id=<user_id>, # str
roles=<user_roles> # List[UserRole]
)
Параметры метода включают:
-
<user_id>: идентификатор пользователя (строка); -
массив объектов ролей с полями:
-
<policy_id>(необязательный): идентификатор политики доступа (строка); -
<role_id>: идентификатор роли (строка) -
<org_ids>: идентификаторы организаций (массив строк).
-
Примеры назначения роли пользователю
Пример скрипта с add_roles_to_user в TypeScript
id: add_roles_to_user_ts
name: add_roles_to_user_ts
description: Создание роли
version: 0.0.1
type: script
source: !deno |
import * as sdk from "@playbooks/sdk"
const ORG_ID = "00000000-0000-0000-0000-000000000000"
const userId = "c74bbab9-f6a8-4a6f-9b6f-f63c8b6abb79"
export async function main() {
// Создаем роль с фронтенд-разрешением на просмотр экспертизы.
const roleId = await sdk.access.create_role({
frontendPermissionKeys: ['evo.streams.expertise.view'],
isSystem: false,
name: 'testRole3',
permissionKeys: [],
tenantId: [ORG_ID],
})
// Добавляем созданную роль пользователю.
await sdk.access.add_roles_to_user({
id: userId,
roles: [{ organizationIds: [ORG_ID], roleId: roleId }],
}
Пример скрипта с add_roles_to_user в Python
id: add_roles_to_user_py
name: add_roles_to_user_py
version: 0.0.1
type: script
source: !py |
from playbooks.access import AccessClient, UserRole
ORG_ID = '00000000-0000-0000-0000-000000000000'
USER_ID = 'c74bbab9-f6a8-4a6f-9b6f-f63c8b6abb79'
def main():
client = AccessClient.initialize()
# Создаем роль с фронтенд-разрешением на просмотр экспертизы.
role_id = client.create_role(frontend_permission_keys=['evo.streams.expertise.view'], permission_keys=[], is_system=False, name='testRole4', tenant_id=ORG_ID)
# Добавляем созданную роль пользователю.
client.add_roles_to_user(id=USER_ID, roles=[UserRole(role_id=role_id, organization_ids=[ORG_ID])])
Методы для работы с организациями
Получение данных об организации (batch_get_orgs)
Метод используется для получения массива данных об указанных организациях. Данные об организации включают ее название, описание, идентификатор родительской организации, а также сведения о создании и изменении организации.
batch_get_orgs в TypeScriptbatch_get_orgs({
assertAvailability: <assert_availability> // boolean | undefined
ids: <org_ids> // string[]
})
batch_get_orgs в Pythonbatch_get_orgs(
assert_availability=<assert_availability> # bool | None
ids=<org_ids> # List[str]
)
Параметры метода включают в себя:
-
<assert_availability>(необязательный): флаг проверки доступности организаций (логическое значение, по умолчанию —false); -
<org_ids>: идентификаторы организаций (массив строк).
Метод возвращает массив объектов со следующими полями:
-
id: идентификатор (UUID); -
name: имя организации; -
tenant_id: тенант, в рамках которого существует организация; -
parent_id: родительская организация, внутри которой содержится текущая организация; -
description: описание организации. -
created_by_id: пользователь, инициировавший создание организации; -
updated_by_id: пользователь, выполнивший последнее изменение организации; -
record_date_time: время изменений:-
created_at: дата и время создания организации; -
updated_at: дата и время последнего изменения организации.
-
Была ли полезна эта страница?