API в скриптах

API предоставляет пользователям возможность работать программными средствами с объектами доменов. Для использования API при работе с объектами доменов используется пакет SDK @playbooks/sdk. Он содержит клиенты для работы со следующими ресурсами:

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

Использование API для объектов доменов

Клиент, содержащийся в пакете, позволяет работать с объектами (экземплярами сущностей) доменов с использованием описанных ниже методов.

Методы API для работы с объектами доменов включают:

Описания и примеры приведены для TypeScript (среда выполнения Deno) и Python.

Подготовка клиента для работы с объектами

Чтобы работать с объектами доменов с помощью пакета SDK, импортируйте его:

Синтаксис импорта в TypeScript
import * as sdk from '@playbooks/sdk'
...
export async function main() {
...
  const v = await sdk.cms.<method_name>(<arg_1>, <arg_2>, ..., <arg_m>)
  console.log(v)
...
}
Синтаксис импорта в Python
from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order
...
def main() {
...
    client = CmsClient.initialize()
    v = client.<method_name>(<arg_1>, <arg_2>, ..., <arg_m>)
    print(v)
...
}

Здесь:

  • <method_name>: имя используемого метода;

  • <arg_N>: параметры метода.

Получение данных об объекте (get)

Метод используется для получения определенного объекта.

Синтаксис get в TypeScript
get({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  refFields: <reference_attributes>, // string[] | undefined
})
Синтаксис get в Python
get(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id>, # str
    ref_fields=<reference_fields> # List[str] | None
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <object_id>: идентификатор объекта (строка);

  • <reference_fields> (необязательный): дополнительные поля, которые нужно включить в ответ. Это поля объектов, на которые ссылаются атрибуты типа Reference (массив строк вида refAttributeId.attributeId).

Метод get возвращает следующие данные:

  • id: идентификатор объекта CMS.

  • domain_id: идентификатор домена CMS.

  • entity_id: идентификатор сущности.

  • values: атрибуты объекта и их значения.

  • tenant_id: идентификатор тенанта.

  • created_at: дата создания объекта.

  • created_by: идентификатор пользователя, создавшего объект.

  • updated_at: дата последнего изменения объекта.

  • updated_by: идентификатор пользователя, который в последний раз изменил объект.

  • version: версия объекта.

  • label: поле label объекта (отображаемое название).

Примеры получения данных об объекте

Пример скрипта с get в TypeScript
id: get_object_in_cms_ts
name: 'get_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Вызов функции получения объекта с передачей objectId, domainId и entityId.
      const cmsObject = await sdk.cms.get({ domainId, entityId, id: objectId })

      // Вывод полученного объекта в консоль.
      console.log(cmsObject)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при получении объекта.
      console.log(error)
    }
  }
Пример скрипта с get в Python
id: get_object_in_cms_py
name: get_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id, entity_id и object_id - id домена, сущности и объекта.
    domain_id = 'example.com'
    entity_id = 'Person'
    object_id = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

    def main():
        try:
            client = CmsClient.initialize()
            cms_object = client.get(id=object_id, domain_id=domain_id, entity_id=entity_id) # Получение объекта по указанному id.

            print('Print object:') # Вывод объекта в консоль.
            print(cms_object)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при получении объекта.
            print('An exception occurred:', error)

Метод используется для получения массива связей объекта. Фильтры для уточнения запроса, порядок сортировки и количество выводимых результатов задаются с помощью параметров.

Синтаксис find_object_links в TypeScript
find_object_links({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  linkRequests: [
    {
      domainId: <domain_id>, // string
      linkageId: <linkage_id>, // string
      filterLink: {
        conditions: <conditions>, // string | undefined
        linkIds: <link_ids> // string[] | undefined
        objectIds: <object_ids> // string[] | undefined
      },
      side: <side_number>, // 1 | 2 | undefined
      sorting: {
        order: <order_dir>, // 'asc' | 'desc'
        orderBy: <order_rule>, // string
      },
      pagination: {
        limit: <limit>, // number
        offset: <offset>, // number | undefined
      },
      refFields: <reference_fields>, // string[] | undefined
    },
    ...,
  ],
})
Синтаксис find_object_links в Python
find_object_links(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id>, # str
    link_requests=[
        LinkRequest(
            domain_id=<domain_id>, # str
            linkage_id=<linkage_id>, # str
            filter_link=FilterLink(
                conditions=<conditions>, # str | None
                link_ids=<link_ids>, # List[str] | None
                object_ids=<object_ids> # List[str] | None
            ),
            side=<side_number>, # 1 | 2 | None
            sorting=Sorting(
                Order.<order_dir>, # Desc | Asc
                <order_rule> # str
            ),
            pagination=Pagination(
                <limit>, # int
                <offset> # int | None
            ),
            ref_fields=<reference_fields>, # List[str] | None
        ),
        ...,
    ]
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <object_id>: идентификатор объекта (строка);

  • массив запросов для фильтрации связей объекта. Каждый запрос включает:

    • <domain_id>: идентификатор домена (строка);

    • <linkage_id>: идентификатор связи в домене (строка);

    • настройки фильтрации списка связанных объектов (необязательный блок):

      • <conditions> (необязательный): условие фильтрации в виде строки, содержащей JSON в формате запросов MikroORM (строка);

      • <link_ids> (необязательный): список идентификаторов связей (массив строк);

      • <object_ids> (необязательный): список идентификаторов объектов (массив строк);

    • <side_number> (обязателен только при симметричной направленной связи): сторона связи (число, 1 или 2);

    • настройки сортировки списка по данным объектов на другой стороне связи (необязательный блок):

      • <order_dir>: порядок сортировки ('asc'/Asc — по возрастанию или 'desc'/Desc — по убыванию);

      • <order_rule>: идентификатор одного из правил сортировки, определенного в поле sorting для сущности на другой стороне связи (строка);

    • ограничение количества выводимых результатов (необязательный блок):

      • <limit>: максимальное количество записей в ответе (число);

      • <offset> (необязательный): порядковый номер первой записи, начиная с которой выводится ответ (число);

    • <reference_fields> (необязательный): дополнительные поля, которые нужно включить в ответ. Это поля объектов, на которые ссылаются атрибуты типа Reference сущности на другой стороне связи (массив строк вида refAttributeId.attributeId).

В приведенных примерах скрипт запрашивает список связей типа ProjectContribution указанного объекта Person. У объектов на другой стороне связи значение поля priority должно быть равным high. Запрос возвращает результаты отсортированными в порядке возрастания согласно правилу projectName, указанному в объектах на другой стороне связи.

Пример скрипта с find_object_links в TypeScript
id: find_object_links_ts
name: SDK CMS Find Object Links
version: 0.0.2
type: script
tags: [links]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objId = '694aa0c4-70c9-4837-9beb-720535c44eb4'

  export async function main() {
    try {
      // Вызов функции получения связей объекта с передачей objId, domainId и entityId.
      const findObjectLinks = await sdk.cms.find_object_links({
        domainId,
        entityId,
        id: objId,
        linkRequests: [
          {
            domainId: 'example.com',
            filterLink: {
              conditions: '{"$or":[{"priority":{"$eq":"high"}}]}',
            },
            linkageId: 'ProjectContribution',
            sorting: {
              order: 'asc',
              orderBy: 'projectName',
            },
          },
        ],
      })

      // Вывод полученных связей объекта в консоль.
      console.log(findObjectLinks)
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при получении связей объекта.
      console.log(e)
    }
  }
Пример скрипта с find_object_links в Python
id: find_object_links_py
name: SDK CMS Find Object Links
version: 0.0.2
tags: [links]
type: script
source: !py |
    from playbooks.cms import FilterLink, LinkRequest, CmsClient, Sorting, Order

    domain_id = 'example.com'
    entity_id = 'Person'
    object_id = '694aa0c4-70c9-4837-9beb-720535c44eb4'

    def main():
        client = CmsClient.initialize()
        filter_link = FilterLink(
            conditions='{\"$or\":[{\"priority\":{\"$eq\":\"high\@}}]}'
        )

        sorting = Sorting(Order.Asc, 'projectName')

        link_request = LinkRequest(
            domain_id='example.com',
            linkage_id='ProjectContribution',
            filter_link=filter_link,
            sorting=sorting
        )

        res = client.find_object_links(id=object_id, domain_id=domain_id, entity_id=entity_id, link_requests=[link_request])
        print(res[0].id)
        print(res[0].values)

Получение списка объектов (list)

Метод используется для получения отфильтрованного и отсортированного массива необходимых объектов. Фильтры для уточнения запроса, порядок сортировки и количество выводимых результатов задаются с помощью параметров.

Синтаксис list в TypeScript
list({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  filter: {
    conditions: <conditions>, // string | undefined
    ids: <object_ids>, // string[] | undefined
    query: <query>, // string | undefined
    links: {
      <operator>: [
        {
          domainId: <domain_id>, // string
          linkageId: <linkage_id>, // string
          ids: <link_ids>, // string[] | undefined
          object: {
            conditions: <links_conditions>, // string | undefined
            ids: <linked_object_ids> // string[] | undefined
          },
          side: <side_number> // 1 | 2 | undefined
        },
        ...,
      ]
    },
  },
  sorting: {
    order: <order_dir>, // 'asc' | 'desc'
    orderBy: <order_rule>, // string
  },
  pagination: {
    limit: <limit>, // number
    offset: <offset>, // number | undefined
  },
  refFields: <reference_fields>, // string[] | undefined
})
Синтаксис list в Python
list(
  domain_id=<domain_id>, # str
  entity_id=<entity_id>, # str
  filter=Filter(
      conditions=<conditions>, # str | None
      ids=<object_ids>, # str | None
      query=<query>, # str | None
      links=Links(
          operator=<operator>, # str
          links=[
              Link(
                  domain_id=<domain_id>, # str
                  linkage_id=<linkage_id>, # str
                  ids=<link_ids>, # List[str] | None
                  object=FilterLink(
                      conditions=<links_conditions>, # str | None
                      ids=<linked_object_ids>, # List[str] | None
                  ),
                  side=<side_number>, # 1 | 2 | None
              ),
              ...
          ]
      ),
  ),
  sorting=Sorting(
      Order.<order_dir>, # Desc | Asc
      <order_rule> # str
  ),
  pagination=Pagination(
      <limit>, # int
      <offset> # int | None
  ),
  ref_fields=<reference_fields>, # List[str] | None
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • настройки фильтрации списка (необязательный блок):

    • <conditions> (необязательный): условие фильтрации в виде строки, содержащей JSON в формате запросов MikroORM (строка);

    • <object_ids> (необязательный): список идентификаторов требуемых объектов (массив строк);

    • <query> (необязательный): запрос для поиска по атрибутам сущностей, на которые ссылается поле label, находящееся в поле entities схемы домена (строка);

    • запрос для фильтрации по связям объектов, который включает:

      • <operator>: логический оператор and (все перечисленные условия должны быть выполнены) или or (достаточно выполнения хотя бы одного условия из перечня);

      • <domain_id>: идентификатор домена (строка);

      • <linkage_id>: идентификатор связи в домене (строка);

      • <link_ids> (необязательный): список идентификаторов связей (массив строк);

      • <links_conditions> (необязательный): условие фильтрации в виде строки, содержащей JSON в формате запросов MikroORM (строка);

      • <linked_object_ids> (необязательный): список идентификаторов связанных объектов (массив строк);

      • <side_number> (обязателен только при симметричной направленной связи): сторона связи (число, 1 или 2);

  • настройки сортировки списка (необязательный блок):

    • <order_dir>: порядок сортировки ('asc'/Asc — по возрастанию или 'desc'/Desc — по убыванию);

    • <order_rule>: идентификатор одного из правил сортировки, определенного в поле sorting сущности (строка);

  • ограничение количества выводимых результатов (необязательный блок):

    • <limit> (обязателен, если ограничение указано): максимальное количество записей в ответе (число);

    • <offset> (необязательный): порядковый номер первой записи, начиная с которой выводится ответ (число);

  • <reference_fields> (необязательный): дополнительные поля, которые нужно включить в ответ. Это поля объектов, на которые ссылаются атрибуты типа Reference (массив строк вида refAttributeId.attributeId).

Примеры получения списка объектов

В приведенных примерах скрипт запрашивает список экземпляров сущности Person, которые имеют указанные идентификаторы объектов и атрибут department со значением IT department. Запрос должен вернуть не более 10 результатов, отсортированных согласно правилу fullName в порядке возрастания.

Пример скрипта с list в TypeScript
id: list_object_in_cms_ts
name: 'list_object_in_cms_ts'
version: 0.0.1
type: script
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId и entityId.
  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Вызов функции получения объекта с передачей domainId и entityId.
      const cmsObjects = await sdk.cms.list({
        domainId,
        entityId,
        filter: {
          conditions: '{\"$or\":[{\"department\":{\"$eq\":\"IT department\"}}]}',
          ids: [
            'a1b2c3d4-5678-90ab-cdef-1234567890ab',
            'f1e2d3c4-b567-89a0-bcde-0987654321ff',
            ...,
          ],
        },
        pagination: {
          limit: 10,
          offset: 0,
        },
        sorting: {
          order: 'asc',
          orderBy: 'fullName',
        },
      })

      // Вывод полученных объектов в консоль.
      console.log(cmsObjects)
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при получении объектов.
      console.log(e)
    }
  }
Пример скрипта с list в Python
id: list_object_in_cms_py
name: list_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id и entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()
            cmsObjects = client.list(
                domain_id=domain_id,
                entity_id=entity_id,
                filter=Filter(
                    '{\"$or\":[{\"department\":{\"$eq\":\"IT department\"}}]}',
                    [
                        'a1b2c3d4-5678-90ab-cdef-1234567890ab',
                        'f1e2d3c4-b567-89a0-bcde-0987654321ff',
                        ...,
                    ],
                    None),
                sorting=Sorting(Order.Asc, 'fullName'),
                pagination=Pagination(10, 0)
            )  # Получение списка объектов с указанными параметрами.

            # Вывод списка объектов в консоль.
            print('print objects:')
            for obj in cmsObjects:
                print(obj)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при получении списка объектов.
            print('An exception occurred:', error)

В примерах приведены значения поля filter для фильтрации полученных данных по связям.

Получение объектов, у которых нет ни одной указанной связи с любым другим объектом
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$none\":{}}'
        },
        'side': 2
      }
    ]
  }
}
Получение списка объектов, у которых нет ни одной указанной связи с определенным объектом
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$none\":{\"id\":\"9b2f8822-b932-44a7-991b-3cb432cd6b98\"}}' // Условие фильтрации, здесь '9b2f8822-b932-44a7-991b-3cb432cd6b98' -- идентификатор объекта, с которым у возвращенных объектов не должно быть связей.
        },
        'side': 2
      }
    ]
  }
}
Получение списка объектов, у которых есть хотя бы одна указанная связь с определенным объектом
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$some\":{\"id\":\"9b2f8822-b932-44a7-991b-3cb432cd6b98\"}}' // Условие фильтрации, здесь '9b2f8822-b932-44a7-991b-3cb432cd6b98' -- идентификатор объекта, с которым у возвращаемых объектов должна быть хотя бы одна связь.
        },
        'side': 2
      }
    ]
  }
}
Получение списка объектов, имеющих хотя бы одну указанную связь с объектами, в которых значение поля name равно 'Ivan'
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$some\":{\"name\":\"Ivan\"}}'
        },
        'side': 2
      }
    ]
  }
}
Получение списка объектов, не имеющих ни одной указанной связи с объектами со значением поля name, равным 'Ivan'
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$none\":{\"name\":\"Ivan\"}}'
        },
        'side': 2
      }
    ]
  }
}
Получение списка объектов, у которых нет никаких других указанных связей, кроме как с объектами со значением поля name, равным 'Ivan'
{
  'links': {
    'and': [
      {
        'domainId': 'example.com',
        'linkageId': 'ProjectContribution',
        'object': {
          'conditions': '{\"$every\":{\"name\":\"Ivan\"}}'
        },
        'side': 2
      }
    ]
  }
}

Создание объекта (create)

Метод используется для создания объекта. Набор атрибутов объекта и их значения задаются с помощью параметров.

Синтаксис TypeScript
create({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  values: <values>, // Map<string, any>
})
Синтаксис Python
create(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    values=<values>, # str
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <values>: набор пар "ключ — значение" с атрибутами объекта и их значениями (в TypeScript — коллекция Map, в Python — JSON-объект в виде строки).

Примеры создания объекта

Приведенные примеры для TypeScript отличаются способом передачи значений:

  • В первом примере для создания Map используется метод Object.entries().

  • Во втором примере данные сохраняются в mapForCreate как массив массивов вида ['valueAttribute','value'], где valueAttribute — это атрибут из схемы домена, value — значение атрибута.

  • В третьем примере каждая пара атрибутов передается в отдельном вызове метода mapForCreate.set().

Пример скрипта с create в TypeScript (Object.entries())
id: create_object_in_cms_ts_entries
name: 'create_object_in_cms_ts_entries'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию создания объекта.
      const mapForCreate = new Map<string, any>(
        Object.entries({
          department: 'IT department',
          mail: 'mail@example.com',
          ...
        }),
      )

      // Вызов функции создания объекта с передачей domainId, entityId и mapForCreate.
      const cmsObjectToBeCreated = await sdk.cms.create({ domainId, entityId, values: mapForCreate })

      // Вывод созданного объекта в консоль.
      console.log(cmsObjectToBeCreated)
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при создании объекта.
      console.log(e)
    }
  }
Пример скрипта с create в TypeScript (массив массивов значений)
id: create_object_in_cms_ts_arr
name: 'create_object_in_cms_ts_arr'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию создания объекта.
      const mapForCreate = new Map<string, any>([
        ['mail','mail@example.com'],
        ['department','IT department'],
        ...
      ])

      // Вызов функции создания объекта с передачей domainId, entityId и mapForCreate.
      const cmsObjectToBeCreated = await sdk.cms.create({ domainId, entityId, values: mapForCreate })

      // Вывод созданного объекта в консоль.
      console.log(cmsObjectToBeCreated)
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при создании объекта.
      console.log(e)
    }
  }
Пример скрипта с create в TypeScript (set)
id: create_object_in_cms_ts_set
name: 'create_object_in_cms_ts_set'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId и entityId.
  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию создания объекта.
      const mapForCreate = new Map<string, any>()
      mapForCreate.set('mail', 'mail@example.com')
      mapForCreate.set('department', 'IT department')
      ...

      // Вызов функции создания объекта с передачей domainId, entityId и mapForCreate.
      const cmsObjectToBeCreated = await sdk.cms.create({ domainId, entityId, values: mapForCreate })

      // Вывод созданного объекта в консоль.
      console.log(cmsObjectToBeCreated)
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при создании объекта.
      console.log(e)
    }
  }
Пример скрипта с create в Python
id: create_object_in_cms_py
name: create_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id и entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()

            id = client.create(domain_id=domain_id, entity_id=entity_id, values='{'mail':'mail@example.com', 'department':'IT department', ...}').id  # Создание объекта с указанными параметрами.

            print('Object created')  # Вывод сообщения об успешном создании объекта.

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при создании объекта.
            print('An exception occurred:', error)

Примеры массового создания объектов

В приведенных примерах для массового создания экземпляров сущностей используется массив объектов с атрибутами и их значениями. Массив обрабатывается циклом, который поочередно вызывает метод create для каждого объекта.

Пример скрипта с массовым созданием объектов в TypeScript
id: array_create_object_in_cms_ts
name: 'array_create_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание массива для передачи данных в функцию создания объекта.
      const objectsData = [
        { mail: 'mail@example.com', department: 'IT department', ... },
        { mail: 'mail2@example.com', department: 'Sales department', ... },
        ...,
      ]

      for (const item of objectsData) {
        const mapForCreate = new Map(Object.entries(item))

        // Вызов функции создания объекта с передачей domainId, entityId и mapForCreate.
        const cmsObjectToBeCreated = await sdk.cms.create({ domainId, entityId, values: mapForCreate })

        // Вывод созданного объекта в консоль.
        console.log(cmsObjectToBeCreated)
      }
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при создании объекта.
      console.log(e)
    }
  }
Пример скрипта с массовым созданием объектов в Python
id: array_create_object_in_cms_py
name: array_create_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order
    import json

    # Инициализация переменных domain_id и entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()

            # Массив данных для создания объектов.
            objects_data = [
                { 'mail': 'mail@example.com', 'department': 'IT department', ... },
                { 'mail': 'mail2@example.com', 'department': 'Sales department', ... },
                ...,
            ]

            for item in objects_data:
                json_data = json.dumps(item)

                # Создание объекта с указанными параметрами.
                object_id = client.create(domain_id=domain_id, entity_id=entity_id, values=json_data).id

                print(f'Object created with ID: {object_id}')

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при создании объекта.
            print('An exception occurred:', error)

Полное обновление объекта (update)

Метод используется для полного изменения набора атрибутов и значений объекта с сохранением его идентификатора.

Синтаксис TypeScript
update({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  values: <values>, // Map<string, any>
  version: <version>, // string | undefined
})
Синтаксис Python
update(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id>, # str
    values=<values>, # str,
    version=<version>, # int | None
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <object_id>: идентификатор объекта (строка);

  • <values>: набор пар "ключ — значение" с атрибутами объекта и их значениями (в TypeScript — коллекция Map, в Python — JSON-объект в виде строки);

  • <version> (необязательный): версия объекта, используемая для оптимистической блокировки записи (в TypeScript — строка, в Python — целое число).

Примеры обновления объекта

Приведенные примеры для TypeScript отличаются способом передачи значений:

  • В первом примере для создания Map используется метод Object.entries().

  • Во втором примере данные сохраняются в mapForUpdate как массив массивов вида ['valueAttribute','value'], где valueAttribute — это атрибут из схемы домена, value — значение атрибута.

  • В третьем примере каждая пара атрибутов передается в отдельном вызове метода map.set().

Пример скрипта с update в TypeScript (Object.entries())
id: update_object_in_cms_ts_arr
name: 'update_object_in_cms_ts_arr'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию обновления объекта.
      const mapForUpdate = new Map<string, any>(
        Object.entries({
          mail: 'mail@example.com',
          department: 'IT department',
          ...
        })
      )

      // Вызов функции обновления объекта с передачей objectId, domainId, entityId и mapForUpdate.
      const cmsObjectToBeUpdated = await sdk.cms.update({ domainId, entityId, id: objectId, values: mapForUpdate })

      // Вывод обновленного объекта в консоль.
      console.log(cmsObjectToBeUpdated)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при обновлении объекта.
      console.log(error)
    }
  }
Пример скрипта с update в TypeScript (массив массивов значений)
id: update_object_in_cms_ts_arr
name: 'update_object_in_cms_ts_arr'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию обновления объекта.
      const mapForUpdate = new Map<string, any>([
        ['mail', 'new_mail@example.com'],
        ['department', 'IT department'],
        ...
      ])

      // Вызов функции обновления объекта с передачей objectId, domainId, entityId и mapForUpdate.
      const cmsObjectToBeUpdated = await sdk.cms.update({ domainId, entityId, id: objectId, values: mapForUpdate })

      // Вывод обновленного объекта в консоль.
      console.log(cmsObjectToBeUpdated)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при обновлении объекта.
      console.log(error)
    }
  }
Пример скрипта с update в TypeScript (set)
id: update_object_in_cms_ts_set
name: 'update_object_in_cms_ts_set'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Создание Map для передачи данных в функцию обновления объекта.
      const map = new Map<string, any>()
      map.set('mail', 'new_mail@example.com')
      map.set('department', 'IT department')
      ...

      // Вызов функции обновления объекта с передачей objectId, domainId, entityId и map.
      const cmsObjectToBeUpdated = await sdk.cms.update({ domainId, entityId, id: objectId, values: map })

      // Вывод обновленного объекта в консоль.
      console.log(cmsObjectToBeUpdated)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при обновлении объекта.
      console.log(error)
    }
  }
Пример скрипта с update в Python
id: update_object_in_cms_py
name: update_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id, entity_id и object_id - id домена, сущности и объекта.
    domain_id = 'example.com'
    entity_id = 'Person'
    object_id = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

    def main():
        try:
            client = CmsClient.initialize()
            client.update(id=object_id, domain_id=domain_id, entity_id=entity_id, values='{'mail':'new_mail@example.com', 'department':'IT department', ... }') # Обновление объекта с указанными параметрами и новым значением атрибута.

            cms_object = client.get(id=object_id, domain_id=domain_id, entity_id=entity_id)  # Получение обновленного объекта.

            print('Print updated object:') # Вывод сообщения об успешном обновлении объекта и его значений.
            print(cms_object)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при обновлении объекта.
            print('An exception occurred:', error)

Примеры массового обновления объектов

В приведенных примерах для массового обновления экземпляров сущностей используется массив объектов с атрибутами и их значениями. Массив обрабатывается циклом, который поочередно вызывает метод update для каждого объекта.

Пример скрипта с массовым обновлением объектов в TypeScript
id: array_update_object_in_cms_ts
name: 'array_update_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание массива для передачи данных в функцию обновления объекта.
      const objectsData = [
        { id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab', values: { mail: 'new_mail@example.com', department: 'IT department', ..., } },
        { id: 'f1e2d3c4-b567-89a0-bcde-0987654321ff', values: { mail: 'new_mail2@example.com', department: 'Sales department', ..., } },
        ...,
      ]

      for (const item of objectsData) {
        const mapForUpdate = new Map(Object.entries(item.values))

        // Вызов функции обновления объекта с передачей domainId, entityId и mapForUpdate.
        const cmsObjectToBeUpdated = await sdk.cms.update({ domainId, entityId, id: item.id, values: mapForUpdate })

        // Вывод обновленного объекта в консоль.
        console.log(cmsObjectToBeUpdated)
      }
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при обновлении объекта.
      console.log(e)
    }
  }
Пример скрипта с массовым обновлением объектов в Python
id: array_update_object_in_cms_py
name: array_update_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order
    import json

    # Инициализация переменных domain_id и entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()

            # Массив данных для обновления объектов.
            objects_data = [
                { id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab', values: '{'mail':'new_mail@example.com','department':'IT department', ... }' },
                { id: 'f1e2d3c4-b567-89a0-bcde-0987654321ff', values: '{'mail':'new_mail2@example.com','department':'Sales department', ... }' },
                 ...,
            ]

            for item in objects_data:
                object_id = item.get('id')
                entity_values = item.get('values')

                # Обновление объекта с указанными параметрами.
                client.update(id=object_id, domain_id=domain_id, entity_id=entity_id, values=entity_values)

                cms_object = client.get(id=object_id, domain_id=domain_id, entity_id=entity_id)  # Получение обновленного объекта.

                print('Print updated object:') # Вывод сообщения об успешном обновлении объекта и его значений.
                print(cms_object)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при обновлении объекта.
            print('An exception occurred:', error)

Частичное изменение объекта (patch)

Метод используется для изменения отдельных атрибутов и значений объекта с сохранением его идентификатора.

Синтаксис TypeScript
patch({
  attributeIds: <attribute_ids>, // string[]
  delta: <delta>, // string
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  version: <version>, // string | undefined
})
Синтаксис Python
patch(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id>, # str
    attribute_ids=<attribute_ids>, # List[str]
    delta=<delta>, # str
    version=<version>, # int | None
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <object_id>: идентификатор объекта (строка);

  • <attribute_ids>: идентификаторы атрибутов объекта, которые нужно изменить (массив строк);

  • <delta>: набор пар "ключ — значение" с атрибутами объекта и их новыми значениями (JSON-объект в виде строки);

  • <version> (необязательный): версия объекта, используемая для оптимистической блокировки записи (в TypeScript — строка, в Python — целое число).

Примеры изменения объекта

Пример скрипта с patch в TypeScript
id: patch_object_in_cms_ts
name: 'patch_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Вызов функции изменения объекта с передачей objectId, domainId и entityId.
      const cmsObjectToBePatched = await sdk.cms.patch({
        attributeIds: ['mail'],
        delta: '{"mail":"new_mail@example.com"}',
        domainId,
        entityId,
        id: objectId,
      })

      // Вывод объекта в консоль.
      console.log(cmsObjectToBePatched)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при изменении объекта.
      console.log(error)
    }
  }
Пример скрипта с patch в Python
id: patch_object_in_cms_py
name: patch_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    domain_id = 'example.com'
    entity_id = 'Person'
    object_id= 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

    def main():
        try:
          client = CmsClient.initialize()

          # Частичное изменение объекта с указанными параметрами и новым значением атрибута.
          client.patch(id=object_id, domain_id=domain_id, entity_id=entity_id, attribute_ids=['mail'], delta='{"mail":"new_mail@example.com"}')

          cms_object = client.get(id=object_id, domain_id=domain_id, entity_id=entity_id) # Получение обновленного объекта.

          print('Print patched object:') # Вывод сообщения об успешном применении частичного изменения к объекту и его значений.
          print(cms_object)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при изменении объекта.
            print('An exception occurred:', error)

Примеры массового редактирования объектов

В приведенных примерах для массового редактирования объектов используется массив, содержащий атрибуты и их значения. Затем этот массив обрабатывается циклом, который поочередно вызывает метод patch для каждого объекта в массиве.

Пример скрипта с массовым редактированием объектов в TypeScript
id: array_patch_object_in_cms_ts
name: 'array_patch_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      // Создание массива для передачи данных в функцию редактирования объекта.
      const objectsData = [
        { id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab', attributeIds: ['mail'], values: '{'mail':'new_mail@example.com'}' },
        { id: 'f1e2d3c4-b567-89a0-bcde-0987654321ff', attributeIds: ['mail'], values: '{'mail':'new_mail2@example.com'}' },
        ...,
      ]

      for (const item of objectsData) {
        // Вызов функции обновления объекта с передачей domainId, entityId и id объекта.
        const cmsObjectToBePatched = await sdk.cms.patch({
          attributeIds: item.attributeIds,
          delta: item.values,
          domainId,
          entityId,
          id: item.id,
        })

        // Вывод объекта в консоль.
        console.log(cmsObjectToBeUpdated)
      }
    } catch (e) {
      // Вывод ошибки в консоль, если произошла ошибка при изменении объекта.
      console.log(e)
    }
  }
Пример скрипта с массовым редактированием объектов в Python
id: array_patch_object_in_cms_py
name: array_patch_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order
    import json

    # Инициализация переменных domain_id и entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()

            # Массив данных для редактирования объектов.
            objects_data = [
                { id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab', attribute_ids: ['mail'], values: '{'mail':'new_mail@example.com'}' },
                { id: 'f1e2d3c4-b567-89a0-bcde-0987654321ff', attribute_ids: ['mail'], values: '{'mail':'new_mail2@example.com'}' },
                 ...,
            ]

            for item in objects_data:
                object_id = item.get('id')
                attribute_ids = item.get('attribute_ids')
                entity_values = item.get('values')

                # Частичное изменение объекта с указанными параметрами и новым значением атрибута.
                client.patch(id=object_id, domain_id=domain_id, entity_id=entity_id, attribute_ids=attribute_ids, delta=entity_values)

                cms_object = client.get(id=object_id, domain_id=domain_id, entity_id=entity_id) # Получение обновленного объекта.

                print('Print patched object:') # Вывод сообщения об успешном применении частичного изменения к объекту и его значений.
                print(cms_object)

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при изменении объекта.
            print('An exception occurred:', error)

Удаление объекта (delete)

Метод используется для удаления объекта.

Синтаксис TypeScript
delete({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id> // string
})
Синтаксис Python
delete(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id> # str
)

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <entity_id>: идентификатор сущности (строка);

  • <object_id>: идентификатор объекта (строка).

Примеры удаления объекта

Пример скрипта с delete в TypeScript
id: delete_object_in_cms_ts
name: 'delete_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId, entityId и objectId - id экземпляра сущности.
  const domainId = 'example.com'
  const entityId = 'Person'
  const objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

  export async function main() {
    try {
      // Вызов функции удаления объекта с передачей objectId, domainId и entityId.
      const cmsObjectToBeDeleted = await sdk.cms.delete({ domainId, entityId, id: objectId })

      // Вывод объекта в консоль.
      console.log('Result is Ok. Deleted object:')
      console.log(cmsObjectToBeDeleted)
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при удалении объекта.
      console.log(error)
    }
  }
Пример скрипта с delete в Python
id: delete_object_in_cms_py
name: delete_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id, entity_id и object_id - id домена, сущности и объекта.
    domain_id = 'example.com'
    entity_id = 'Person'
    objectId = 'a1b2c3d4-5678-90ab-cdef-1234567890ab'

    def main():
        try:
            client = CmsClient.initialize()
            deleted_object = client.delete(id=objectId, domain_id=domain_id, entity_id=entity_id) # Удаление объекта с указанными параметрами.

            print(f'Deletion successful for object: {deleted_object}') # Вывод сообщения об успешном удалении объекта.

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при удалении объекта.
            print('An exception occurred:', error)

Примеры массового удаления объектов

В приведенных примерах для массового удаления объектов используется массив идентификаторов объектов. Этот массив обрабатывается циклом, который поочередно вызывает метод delete для каждого объекта.

Пример скрипта с массовым удалением объектов в TypeScript
id: array_delete_object_in_cms_ts
name: 'array_delete_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, deno, cms]
source: !deno |
  import * as sdk from '@playbooks/sdk'

  // Инициализация переменных domainId и entityId.
  const domainId = 'example.com'
  const entityId = 'Person'

  export async function main() {
    try {
      const objectsList = [
        'a1b2c3d4-5678-90ab-cdef-1234567890ab',
        'f1e2d3c4-b567-89a0-bcde-0987654321ff',
        ...,
      ]

      for (const item of objectsList) {
        // Вызов функции удаления объекта с передачей objectId, domainId и id объекта.
        const cmsObjectToBeDeleted = await sdk.cms.delete({ domainId, entityId, id: item })

        // Вывод объекта в консоль.
        console.log('Result is Ok. Deleted object:')
        console.log(cmsObjectToBeDeleted)
       }
    } catch (error) {
      // Вывод ошибки в консоль, если произошла ошибка при удалении объекта.
      console.log(error)
    }
  }
Пример скрипта с массовым удалением объектов в Python
id: array_delete_object_in_cms_py
name: array_delete_object_in_cms_py
version: 0.0.1
type: script
tags: [tests, python, cms]
source: !py |
    from playbooks.cms import CmsClient, Filter, Sorting, Pagination, Order

    # Инициализация переменных domain_id, entity_id - id домена и сущности.
    domain_id = 'example.com'
    entity_id = 'Person'

    def main():
        try:
            client = CmsClient.initialize()

            const objects_list = [
                'a1b2c3d4-5678-90ab-cdef-1234567890ab',
                'f1e2d3c4-b567-89a0-bcde-0987654321ff',
                ...
            ]

            for item in objects_list:
                deleted_object = client.delete(id=item, domain_id=domain_id, entity_id=entity_id) # Удаление объекта с указанными параметрами.

                print(f'Deletion successful for object: {deleted_object}') # Вывод сообщения об успешном удалении объекта.

        except Exception as error:
            # Обработка и вывод ошибки, если произошла ошибка при удалении объекта.
            print('An exception occurred:', error)

Отображение ошибок при работе с пакетом SDK

Ранее при запуске любого метода система возвращала информацию об объекте в виде полей, упакованных в структуру Rust. Теперь система возвращает непосредственно информацию о данных объекта. Возможную ошибку, возвращаемую методом, можно перехватить c помощью стандартной конструкции TypeScript try…​catch.

Использование API для счетчиков

Клиент CMS позволяет работать со счетчиками с помощью описанных ниже методов.

Методы API для работы со счетчиками времени включают:

Описания и примеры приведены для TypeScript (среда выполнения Deno).

Создание счетчика (create_counter)

Метод используется для создания счетчика.

Синтаксис TypeScript
create_counter({
  domainId: <domain_id>, // string
  payload: <payload>, // Map<string, any>
})

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <payload>: полезная нагрузка (коллекция Map).

Запуск счетчика (start_counter)

Метод используется для запуска счетчика.

Синтаксис TypeScript
start_counter({
  domainId: <domain_id>, // string
  counterId: <counter_id>, // string
  duration: <duration>, // number
})

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <counter_id>: идентификатор счетчика (строка);

  • <duration>: интервал времени до срабатывания счетчика в миллисекундах (число).

Остановка счетчика (pause_counter)

Метод используется для остановки запущенного счетчика.

Синтаксис TypeScript
pause_counter({
  domainId: <domain_id>, // string
  counterId: <counter_id>, // string
})

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <counter_id>: идентификатор счетчика (строка).

Продолжение работы счетчика (resume_counter)

Метод используется для продолжения работы остановленного счетчика.

Синтаксис TypeScript
resume_counter({
  domainId: <domain_id>, // string
  counterId: <counter_id>, // string
})

Параметры метода включают в себя:

  • <domain_id>: идентификатор домена (строка);

  • <counter_id>: идентификатор счетчика (строка).

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

Пример скрипта TypeScript с созданием, запуском, остановкой и продолжением работы счетчика
id: "test.script.example"
name: "Тут будет название скрипта"
version: 0.0.24
type: script
source: !deno |
  import * as sdk from "@playbooks/sdk";
  export async function main() {
    // Идентификатор домена.
    const domainId = "test.quick.filters";
    // Создать счетчик.
    const result = await sdk.cms.create_counter({domainId, payload: {"test": "test test"}});
    // Создание счетчика возвращает UUID счетчика.
    const counterId = result.counter_id;
    // Запустить счетчикю
    await sdk.cms.start_counter({domainId, counterId, duration: 10000});
    // Остановить счетчик.
    await sdk.cms.pause_counter({domainId, counterId});
    // Продолжить работу счетчика.
    await sdk.cms.resume_counter({domainId, counterId});
  }

Использование API для активных списков

Если планируется добавление значений объектов в активные списки, необходимо выполнить соответствующие шаги настройки API.

Клиент activeList позволяет работать с активными списками с использованием описанных ниже методов.

Методы API для работы с активными списками включают:

Описания и примеры приведены для TypeScript (среда выполнения Deno) и Python.

Подготовка клиента activeList для работы с активными списками

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

Синтаксис импорта в TypeScript
import { SetupActiveList } from '@playbooks/active-list-client'
...
const activeClient = SetupActiveList()
...
export async function main() {
  const v = await activeClient.<method_name>(<arg_1>, <arg_2>, ..., <arg_m>)
  console.log(v)
}
Синтаксис импорта в Python
from playbooks.active_list import ActiveListClient

...
def main() {
...
    client = ActiveListClient.initialize()
    v = client.<method_name>(<arg_1>, <arg_2>, ..., <arg_m>)
    print(v)
...
}

Здесь:

  • <method_name>: имя используемого метода;

  • <arg_N>: параметры метода.

Вывод записи активного списка по ключу (get_record)

Синтаксис TypeScript
get_record({
  activeListId: <active_list_id>, // string
  key: <key> // string
})
Синтаксис Python
get_record(
    id=<active_list_id>, # str
    key=<key> # str
)

Параметры метода включают в себя:

  • <active_list_id>: идентификатор активного списка (строка);

  • <key>: ключ записи (строка).

Примеры получения записи активного списка

Пример скрипта с get_record в TypeScript
id: get_active_list_object_deno
name: Get active list object deno
description: Получение записи активного списка скриптом Deno (TypeScript) с помощью метода get_record
author: John Doe
tags: [deno, typescript, active list]
version: 0.0.1
type: script
source: !deno |
  import { SetupActiveList } from '@playbooks/active-list-client'

  const activeListId = '95aaab6a-9119-485e-8621-c5ff4dbc1a40' // id активного списка.

  export async function main() {
    try {
      // Настройка клиента активного списка.
      const activeClient = SetupActiveList()

      // Вывод id активного списка.
      console.log(`Получение значений из активного списка с id: ${activeListId}`)

      // Получение записи активного списка.
      const activeListObject = await activeClient.get_record({activeListId, key: '1'})

      console.log('Активный список получен успешно:')

      // Вывод значений из ответа.
      console.log('count:', activeListObject.count)
      console.log('created_at:', activeListObject.created_at)
      console.log('expired_at:', activeListObject.expired_at)
      console.log('updated_at:', activeListObject.updated_at)
      console.log('fields:', activeListObject.fields)
      console.log('key:', activeListObject.key)

      // Или вывод полного ответа из запроса:
      // console.log('Полный ответ:', JSON.stringify(activeListObject, null, 2))
    } catch (error) {
      console.error(`Произошла ошибка: ${error.message}`)
    }
  }
Пример скрипта с get_record в Python
id: get_active_list_object_py
name: Get active list object py
description: Получение записи активного списка скриптом Python с помощью метода get_record
author: John Doe
tags: [python, active list]
version: 0.0.1
type: script
source: !py |
    from playbooks.active_list import ActiveListClient

    active_list_id = '95aaab6a-9119-485e-8621-c5ff4dbc1a40' # id активного списка.

    def main():
        try:
            client = ActiveListClient.initialize()

            record = client.get_record(id=active_list_id, key='1') # id активного списка и значение ключа.
            print('Получение записи')
            print('-' * 30)
            print('Запись с ключом', record.key)
            print('Значение', record.fields)

        except Exception as error:
            # Обработка исключения.
            logger.error(f'Произошла ошибка: {error}')

Вывод активного списка (find_records)

Синтаксис TypeScript
find_records({
  activeListId: <active_list_id> // string
})
Синтаксис Python
find_records(
    id=<active_list_id> # str
)

Параметры метода включают в себя:

  • <active_list_id>: идентификатор активного списка.

Примеры получения записи активного списка

Пример скрипта с find_records в TypeScript
id: Find_active_list_object_deno
name: Find active list object deno
description: Получение массива записей активного списка скриптом Deno (TypeScript) с помощью метода find_records
author: John Doe
tags: [typescript, deno, active list]
version: 0.0.1
type: script
source: !deno |
  import { SetupActiveList } from '@playbooks/active-list-client'

  const activeListId = '5aaab6a-9119-485e-8621-c5ff4dbc1a40' // id созданного активного списка.

  export async function main() {
    try {
      // Настройка клиента активного списка.
      const activeClient = SetupActiveList()

      console.log(`Получение списка объектов со значениями из активного списка с id: ${activeListId}`)

      // Поиск записей активного списка. Возвращает Result<Array<ActiveListRecord>>.
      const records = await activeClient.find_records({activeListId})

      console.log('Список записей в активном списке')
      console.log('-'.repeat(30))

      for (const record of records) {
        console.log('Запись с ключом:', record.key)
        console.log('Значение:', record.fields)
        console.log('-'.repeat(30)) // Разделитель для удобства чтения.

      } catch (error) {
        console.error(`Произошла ошибка: ${error.message}`)
      }
  }
Пример скрипта с find_records в Python
id: list_active_list_object_py
name: List active list object py
description: Получение массива записей активного списка скриптом Python с помощью метода find_records
author: John Doe
tags: [python, active list]
version: 0.0.1
type: script
source: !py |
    from playbooks.active_list import ActiveListClient

    active_list_id = '6c707e96-f786-4d84-b787-3956d1b4e7a1' # id созданного активного списка.

        def main():
            try:
                client = ActiveListClient.initialize()

                print(f'Получение списка объектов со значениями из активного списка с id: {active_list_id}')

                records = client.find_records(id=active_list_id)
                print('Список записей в активном списке')
                print('-' * 30)
                for record in records:
                    print('Запись с ключом', record.key)
                    print('Значение', record.fields)
                    print('-' * 30)  # Разделитель для удобства чтения.

            except Exception as error:
                # Обработка исключения.
                logger.error(f'Произошла ошибка: {error}')

Создание записи в активном списке (insert-record)

Метод используется для создания записи активного списка. Значения записи активного списка задаются с помощью параметров.

Синтаксис TypeScript
insert_record({
  activeListId: <active_list_id>, // string
  key: <key>, // Entry[]
  value: <values>, // Entry[]
})
Синтаксис Python
insert_record(
    id=<active_list_id>, # str
    key=<key>, # Dict[str, str | int | float | bool | Timestamp]
    value=<values>, # Dict[str, str | int | float | bool | Timestamp]
)

Параметры метода включают в себя:

  • <active_list_id>: идентификатор активного списка (строка);

  • <key>: ключ записи (в TypeScript — массив пар "ключ — значение", в Python — словарь);

  • <values>: поля записи и их значения (в TypeScript — массив пар "ключ — значение", в Python — словарь).

Синтаксис пары "ключ — значение"
{
  key: <field_name>, // string
  value: {
    <value_type>: <field_value> // number | boolean | string | { nanos: number, seconds: number} | null
  }
}

Здесь:

  • <field_name>: имя поля (строка);

  • <value_type>: тип значения (Integer, Float, Boolean, String, Timestamp, Empty);

  • <field_value>: значение поля.

Примеры создания записи активного списка

Пример скрипта с insert_record в TypeScript
id: create_active_list_object_deno
name: Create active list object deno
description: Создание записи активного списка скриптом Deno (TypeScript) с помощью метода insert_record
author: John Doe
tags: [deno, typescript, active list]
version: 0.0.1
type: script
source: !deno |
  import { SetupActiveList } from '@playbooks/active-list-client'
  const activeListId = '95aaab6a-9119-485e-8621-c5ff4dbc1a40' // id активного списка.
  export async function main() {
    try {
      // Настройка клиента активного списка.
      const activeClient = SetupActiveList()

      // Вывод id активного списка.
      console.log(`Создание в активном списке с id: ${activeListId}`)

      // Создание записей активного списка. Возвращает массив строк с результатами создания. Принимает id, ключ, значение.
      const insertedObject = await activeClient.insert_record({
        activeListId,
        key: [
          {
            key: 'account', // Это ключ.
            value: {
              String: '1'
            }
          }
        ],
        value: [
          {
            key: 'commonName',
            value: {
              String: 'User'
            }
          },
          {
            key: 'upn',
            value: {
              String: 'john.doe@corp.local'
            }
          },
          {
            key: 'cmsObjectId',
            value: {
              String: '5'
            }
          }
        ]
      })

      console.log(`Создан объект с ключом: ${insertedObject}`)
    } catch (err) {
      console.error(`Произошла ошибка: ${err.message}`)
    }
  }
Пример скрипта с insert_record в Python
id: create_active_list_object_py
name: Create active list object py
description: Создание записи активного списка скриптом Python с помошью метода insert_record
author: John Doe
tags: [python, active list]
version: 0.0.1
type: script
source: !py |
    from playbooks.active_list import ActiveListClient

    active_list_id = '95aaab6a-9119-485e-8621-c5ff4dbc1a40' # id активного списка.

    def main():
        try:
            client = ActiveListClient.initialize()

            # Ключ - значение в активном списке.
            key = {
                'account': '1'
            }
            value = {
                'upn': 'john.doe@corp.local',
                'commonName': 'User',
                'cmsObjectId': '5'
            }
            client.insert_record(id=active_list_id, key=key, value=value)
            print(f'Запись создана в {active_list_id}')

        except Exception as error:
            # Обработка исключения.
            logger.error(f'Произошла ошибка: {error}')

Удаление записи активного списка (delete_record)

Метод служит для удаления записи активного списка по ключу.

Синтаксис TypeScript
delete_record({
  activeListId: <active_list_id>, // string
  key: <key> // string
})
Синтаксис Python
delete_record(
    id=<active_list_id>, # str
    key=<key> # str
)

Параметры метода включают в себя:

  • <active_list_id>: идентификатор активного списка (строка);

  • <key>: ключ записи (строка).

Примеры удаления записи активного списка

Пример скрипта с delete_record в TypeScript
id: delete_active_list_object_deno
name: Delete active list object deno
description: Удаление записей активного списка скриптом Deno (TypeScript) с помощью метода delete_record
author: John Doe
tags: [deno, typescript, active list]
version: 0.0.1
type: script
source: !deno |
  import { SetupActiveList } from '@playbooks/active-list-client'

  const activeListId = '95aaab6a-9119-485e-8621-c5ff4dbc1a40'
  const activeListKeys = ['first_key', 'second_key', 'third_key', ...]

  export async function main() {
      try {
        // Настройка клиента активного списка.
        const activeClient = SetupActiveList()

        // Вывод id активного списка.
        console.log(`Удаление объектов из активного списка с id: ${activeListId}`)

        // Удаление записей из активного списка по каждому ключу.
        for (const key of activeListKeys) {
          // Удаление одной записи из активного списка.
          const deletedObject = await activeClient.delete_record({activeListId, key})

          console.log(`Объект с ключом '${key}' удален.`)
        }
      } catch (error) {
        console.error(`Произошла ошибка: ${error.message}`)
      }
    }
Пример скрипта с delete_record в Python
id: delete_active_list_object_py
name: Delete active list object py
description: Удаление записи активного списка скриптом Python с помощью метода delete_record
author: John Doe
tags: [python, active list]
version: 0.0.1
type: script
source: !py |
    from playbooks.active_list import ActiveListClient

    active_list_id = '95aaab6a-9119-485e-8621-c5ff4dbc1a40' # id активного списка.
    key_id = 'account' # Ключ, по которому производится поиск записи.

    def main():
        try:
            client = ActiveListClient.initialize()

            # Удаление записи.
            client.delete_record(id=active_list_id, key=key_id)
            print(f'Запись c ключом {key_id} удалена')

        except Exception as error:
            # Обработка исключения.
            logger.error(f'Произошла ошибка: {error}')

Использование API для схем автоматизации

Клиент calculation, содержащийся в пакете @playbooks/sdk, позволяет работать со схемами автоматизации с использованием описанных ниже методов.

Для схем автоматизации доступен только SDK на TypeScript.

Методы API для работы со схемами автоматизации включают:

Подготовка клиента calculation для работы со схемами автоматизации

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

Синтаксис импорта в TypeScript
import * as sdk from "@playbooks/sdk"
...
export async function main() {
...
  const v = await sdk.calculation.<method_name>(<args>)
  console.log(v)
...
}

Здесь:

  • <method_name>: имя используемого метода;

  • <args>: параметры метода.

Вывод результата выполненного расчета (calculation)

Синтаксис TypeScript
calculation({
  calculationId: <calculation_id>, // string
  calculationSchemaId: <calculation_schema_id>, // string
  objectId: <object_id> // string
})

Параметры метода включают в себя:

  • <calculation_id>: идентификатор расчета;

  • <calculation_schema_id>: идентификатор схемы автоматизации;

  • <object_id>: идентификатор объекта, для которого выполнен расчет.

Примеры получения результатов расчетов

Пример скрипта с calculation в TypeScript
id: get_calculation_result_deno
name: Get calculation result deno
description: Получение результатов расчета скриптом Deno (TypeScript) с помощью метода calculation
author: John Doe
tags: [deno, typescript, calculation]
version: 0.0.1
type: script
source: !deno |
  import * as sdk from '@playbooks/sdk';
  export async function main() {
    const command = {
      calculationId: 'test',
      calculationSchemaId: 'calculate_test',
      objectId: '551471a6-8bd2-4af7-a7ad-7af5432c9bea',
    }

    const { result } = await sdk.calculation.calculation(command);
    console.log('result', result);
    return result;
  }

Выполнение расчета (exec)

Синтаксис TypeScript
exec({
  calculationId: <calculation_id>, // string
  calculationSchemaId: <calculation_schema_id>, // string
  object: {
    domainId: <domain_id>, // string
    entityId: <entity_id>, // string
    id: <id> // string
  },
  cacheFirst: <cache_first> // boolean
})

Параметры метода включают в себя:

  • <calculation_id>: идентификатор расчета;

  • <calculation_schema_id>: идентификатор схемы автоматизации;

  • <domain_id>: идентификатор домена, для объекта которого нужно выполнить расчет;

  • <entity_id>: идентификатор сущности в домене, для объекта которой нужно выполнить расчет;

  • <id>: идентификатор объекта, для которого нужно выполнить расчет;

  • <cache_first>: логическая переменная: если установить значение true, то расчет не будет выполнен заново, если его результат будет найден в кэше; если установить значение false, то расчет будет выполнен заново в любом случае.

Примеры выполнения расчета

Пример скрипта с exec в TypeScript
id: exec_calculation_deno
name: Exec calculation deno
description: Выполнение расчета скриптом Deno (TypeScript) с помощью метода exec
author: John Doe
tags: [deno, typescript, calculation]
version: 0.0.1
type: script
source: !deno |
  import * as sdk from '@playbooks/sdk';
  export async function main() {
    const command = {
      calculationSchemaId: "calculate_test",
      calculationId: "test",
      object: {
        domainId: "evo.entity.category.standards",
        entityId: "Requirement",
        id: "551471a6-8bd2-4af7-a7ad-7af5432c9bea"
      },
      cacheFirst: false
    }

    const result = await sdk.calculation.exec(command);
    console.log('result', result);
    return result;
    }

Выполнение обобщающего расчета (execSummary)

Синтаксис TypeScript
execSummary({
  summaryCalculationId: <summary_calculation_id>, // string
  summaryCalculationSchemaId: <summary_calculation_schema_id>, // string
  calculations: [
    {
      calculationId: <calculation_id>, // string
      calculationSchemaId: <calculation_schema_id>, // string
      object: {
        domainId: <domain_id>, // string
        entityId: <entity_id>, // string
        id: <id> // string
      },
      cacheFirst: <cache_first> // boolean
    },
  ...
  ]
})

Параметры метода включают в себя:

  • <summary_calculation_id>: идентификатор обобщающего расчета;

  • <summary_calculation_schema_id>: идентификатор схемы, в которой определен обобщающий расчет;

  • calculations: массив расчетов, входящих в обобщающий расчет:

    • <calculation_id>: идентификатор расчета;

    • <calculation_schema_id>: идентификатор схемы автоматизации;

    • <domain_id>: идентификатор домена, для объекта которого нужно выполнить расчет;

    • <entity_id>: идентификатор сущности в домене, для объекта которой нужно выполнить расчет;

    • <id>: идентификатор объекта, для которого нужно выполнить расчет;

    • <cache_first>: логическая переменная: если установить значение true, то расчет не будет выполнен заново, если его результат будет найден в кэше; если установить значение false, то расчет будет выполнен заново в любом случае.

Примеры выполнения обобщающего расчета

Пример скрипта с execSummary в TypeScript
id: exec_summary_calculation_deno
name: Exec summary calculation deno
description: Выполнение обобщающего расчета скриптом Deno (TypeScript) с помощью метода execSummary
author: John Doe
tags: [deno, typescript, calculation]
version: 0.0.1
type: script
source: !deno |
  import * as sdk from '@playbooks/sdk';
  export async function main() {
    const command = {
      summaryCalculationSchemaId: "calculate_test",
      summaryCalculationId: "test_summary",
      calculations: [
        {
          calculationSchemaId: "calculate_test",
          calculationId: "test",
          object: {
            domainId: "evo.entity.category.standards",
            entityId: "Requirement",
            id: "551471a6-8bd2-4af7-a7ad-7af5432c9bea"
          },
          cacheFirst: false
        },
        {
          calculationSchemaId: "calculate_test",
          calculationId: "test",
          object: {
            domainId: "evo.entity.category.standards",
            entityId: "Requirement",
            id: "2395982b-0e28-4236-ab3d-3c84a29cb97c"
          },
          cacheFirst: false
        }
      ]
    }

    const result = await sdk.calculation.execSummary(command);
    console.log('result', result);
    return result;
  }

Использование API для данных пользователей

Клиент access предоставляет инструменты для получения данных пользователей через следующие методы:

  • данные пользователя по заданному UUID (get_user);

  • данные текущего пользователя (get_current_user);

  • полный список системных пользователей с возможностью фильтрации (list_users).

Данные пользователя включают:

  • 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: пользователь, последним изменивший учетную запись (если применимо).

Описания и примеры приведены для TypeScript (среда выполнения Deno) и Python.

Получение данных о пользователе (get_user)

Метод используется для получения данных определенного пользователя.

Синтаксис get_user в TypeScript
get_user({
  id: <user_id> // string
})
Синтаксис get_user в Python
get_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()

Примеры получения данных о текущем пользователе

Пример скрипта с 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 в TypeScript
list_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 в Python
list_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()

Работа с контекстом триггера

Если скрипт или плейбук запускается через триггер при наступлении события аудита, внутри скрипта можно получить контекст этого триггера. Контекстом триггера служит информация из поля data события аудита.

Функция получения контекста
get_context()

Примеры получения контекста

Пример скрипта с get_context в TypeScript
id: get_context_deno
name: Получение контекста в Deno
version: 0.0.1
type: script
source: !deno |
  export async function main() {
    const ctx = get_context();
    console.log(ctx);
  }
Пример скрипта с get_context в Python
id: get_context_py
name: Получение контекста в Python
version: 0.0.1
type: script
source: !py |
    def main():
      ctx = get_context()
      print(ctx)

Была ли полезна эта страница?

Обратная связь