API в скриптах

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

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

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

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

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

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

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

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

Пример 1. Синтаксис импорта в 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)
...
}
Пример 2. Синтаксис импорта в 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)

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

Пример 3. Синтаксис get в TypeScript
get({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  refFields: <reference_attributes>, // string[] | undefined
})
Пример 4. Синтаксис 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 в TypeScript
id: get_object_in_cms_ts
name: 'get_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, bun, cms]
source: !bun |
  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)

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

Пример 5. Синтаксис 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
    },
    ...,
  ],
})
Пример 6. Синтаксис 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: !bun |
  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)

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

Пример 7. Синтаксис 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
})
Пример 8. Синтаксис 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: !bun |
  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 для фильтрации полученных данных по связям.

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

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

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

Пример 15. Синтаксис TypeScript
create({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  values: <values>, // Map<string, any>
})
Пример 16. Синтаксис 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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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)

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

Пример 17. Синтаксис TypeScript
update({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
  values: <values>, // Map<string, any>
})
Пример 18. Синтаксис Python
update(
    domain_id=<domain_id>, # str
    entity_id=<entity_id>, # str
    id=<object_id>, # str
    values=<values>, # str
)

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

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

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

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

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

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

Приведенные примеры для 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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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)

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

Пример 19. Синтаксис TypeScript
patch({
  attributeIds: <attribute_ids>, // string[]
  delta: <delta>, // string
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id>, // string
})
Пример 20. Синтаксис 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
)

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

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

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

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

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

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

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

Пример скрипта с patch в TypeScript
id: patch_object_in_cms_ts
name: 'patch_object_in_cms_ts'
version: 0.0.1
type: script
tags: [tests, typescript, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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)

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

Пример 21. Синтаксис TypeScript
delete({
  domainId: <domain_id>, // string
  entityId: <entity_id>, // string
  id: <object_id> // string
})
Пример 22. Синтаксис 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, bun, cms]
source: !bun |
  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, bun, cms]
source: !bun |
  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 для активных списков

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

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

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

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

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

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

Пример 23. Синтаксис импорта в 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)
}
Пример 24. Синтаксис импорта в 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)

Пример 25. Синтаксис TypeScript
get_record({
  activeListId: <active_list_id>, // string
  key: <key> // string
})
Пример 26. Синтаксис Python
get_record(
    id=<active_list_id>, # str
    key=<key> # str
)

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

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

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

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

Пример скрипта с get_record в TypeScript
id: get_active_list_object_bun
name: Get active list object bun
description: Получение записи активного списка скриптом Bun (TypeScript) с помощью метода get_record
author: John Doe
tags: [bun, typescript, active list]
version: 0.0.1
type: script
source: !bun |
  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)

Пример 27. Синтаксис TypeScript
find_records({
  activeListId: <active_list_id> // string
})
Пример 28. Синтаксис Python
find_records(
    id=<active_list_id> # str
)

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

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

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

Пример скрипта с find_records в TypeScript
id: Find_active_list_object_bun
name: Find active list object bun
description: Получение массива записей активного списка скриптом Bun (TypeScript) с помощью метода find_records
author: John Doe
tags: [typescript, bun, active list]
version: 0.0.1
type: script
source: !bun |
  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)

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

Пример 29. Синтаксис TypeScript
insert_record({
  activeListId: <active_list_id>, // string
  key: <key>, // Entry[]
  value: <values>, // Entry[]
})
Пример 30. Синтаксис 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 — словарь).

Пример 31. Синтаксис пары "ключ — значение"
{
  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_bun
name: Create active list object bun
description: Создание записи активного списка скриптом Bun (TypeScript) с помощью метода insert_record
author: John Doe
tags: [bun, typescript, active list]
version: 0.0.1
type: script
source: !bun |
  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)

Пример 32. Синтаксис TypeScript
delete_record({
  activeListId: <active_list_id>, // string
  key: <key> // string
})
Пример 33. Синтаксис Python
delete_record(
    id=<active_list_id>, # str
    key=<key> # str
)

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

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

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

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

Пример скрипта с delete_record в TypeScript
id: delete_active_list_object_bun
name: Delete active list object bun
description: Удаление записей активного списка скриптом Bun (TypeScript) с помощью метода delete_record
author: John Doe
tags: [bun, typescript, active list]
version: 0.0.1
type: script
source: !bun |
  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, импортируйте его:

Пример 34. Синтаксис импорта в 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)

Пример 35. Синтаксис 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_bun
name: Get calculation result bun
description: Получение результатов расчета скриптом Bun (TypeScript) с помощью метода calculation
author: John Doe
tags: [bun, typescript, calculation]
version: 0.0.1
type: script
source: !bun |
  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)

Пример 36. Синтаксис 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_bun
name: Exec calculation bun
description: Выполнение расчета скриптом Bun (TypeScript) с помощью метода exec
author: John Doe
tags: [bun, typescript, calculation]
version: 0.0.1
type: script
source: !bun |
  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)

Пример 37. Синтаксис 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_bun
name: Exec summary calculation bun
description: Выполнение обобщающего расчета скриптом Bun (TypeScript) с помощью метода execSummary
author: John Doe
tags: [bun, typescript, calculation]
version: 0.0.1
type: script
source: !bun |
  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;
  }