v1.1.2

Миграция на v1

Подробное руководство по миграции приложения с Bitrix24 JS SDK v0 на Bitrix24 JS SDK v1.
CHANGELOG

Это руководство содержит пошаговые инструкции по миграции приложения на Bitrix24 JS SDK v1.

Мы старались сохранить совместимость, но если возникнут проблемы, сообщите нам.

После обновления до Bitrix24 JS SDK v1 обратите внимание на следующие важные изменения:

Изменения

PlacementManager.title

Для согласованности с документацией и устранения путаницы свойство PlacementManager.title переименовано в PlacementManager.placement.

- if (b24Frame.placement.title === 'DEFAULT') {
+ if (b24Frame.placement.placement === 'DEFAULT') {
  // some code
}

TypeB24.getTargetOriginWithPath

Получает адрес аккаунта Bitrix24 с путём

Функция теперь возвращает пути для restApi:v2 и restApi:v3.

+ import { ApiVersion } from '@bitrix24/b24jssdk'

- b24.getTargetOriginWithPath()
+ b24.getTargetOriginWithPath().get(ApiVersion.v2)
+ b24.getTargetOriginWithPath().get(ApiVersion.v3)

TypeB24.getHttpClient

Возвращает HTTP-клиент для выполнения запроса.

Функция теперь возвращает HTTP-клиент для restApi:v2 и restApi:v3.

+ import { ApiVersion } from '@bitrix24/b24jssdk'

- b24.getHttpClient()
+ b24.getHttpClient(ApiVersion.v2)
+ b24.getHttpClient(ApiVersion.v3)

Error

Все ошибки теперь наследуются от SdkError. Учитывайте это.

+ import { SdkError } from '@bitrix24/b24jssdk'

try {
  // ...
} catch (error) {
-  if (error instanceof Error) {
+  if (error instanceof SdkError) {
   // ...
  }
}

Удалено

Неиспользуемые методы TypeHttp

Методы регистрации запросов:

  • TypeHttp.setLogTag()
  • TypeHttp.clearLogTag()

Теперь для этих целей нужно использовать параметр requestId.

Неиспользуемые методы Http

Метод вывода системных сообщений Http.getSystemLogger()

Теперь используется принудительный вывод через LoggerFactory.forcedLog()

Restriction Manager

Класс RestrictionManager удалён. Вместо него используется система Limiters.

- import { RestrictionManagerParamsForEnterprise } from '@bitrix24/b24jssdk'
+ import { ParamsFactory } from '@bitrix24/b24jssdk'

- $b24.getHttpClient().setRestrictionManagerParams( RestrictionManagerParamsForEnterprise )
+ $b24.setRestrictionManagerParams( ParamsFactory.getEnterprise() )
// or
+ const b24 = B24Hook.fromWebhookUrl(hookPath, { restrictionParams: ParamsFactory.getEnterprise() })

- $b24.getHttpClient().setRestrictionManagerParams( { sleep: 600, speed: 0.01, amount: 30 * 5 } )
+ $b24.setRestrictionManagerParams( { rateLimit: { burstLimit: 250, drainRate: 5 } } )

Устарело

AbstractB24.batchSize

Максимальная длина пакетного ответа.

Эта константа устарела и будет удалена в версии 3.0.0.

- if (size < AbstractB24.batchSize) {
+ if (size < 50) {
  // some code ...
}

TypeB24.callMethod

Вызывает метод REST API Bitrix24.

Этот метод устарел и будет удалён в версии 3.0.0.

Для restApi:v2 следует использовать метод b24.actions.v2.call.make(options).

- await b24.callMethod('some.method', { filter: { '>id': 123 } }, 100)
+ await b24.actions.v2.call.make({
+   method: 'some.method',
+   params: {
+     filter: { '>id': 123 },
+     start: 100
+   },
+   requestId: 'unique-request-id'
+ })

TypeB24.callListMethod

Вызывает list-метод REST API Bitrix24 для получения всех данных.

Этот метод устарел и будет удалён в версии 3.0.0.

Для restApi:v2 следует использовать метод b24.actions.v2.callList.make(options).

- await b24.callListMethod('some.method', { filter: { '>id': 123 } }, null, 'items')
+ await b24.actions.v2.callList.make({
+   method: 'some.method',
+   params: { filter: { '>id': 123 } },
+   idKey: 'id',
+   customKeyForResult: 'items',
+   requestId: 'unique-request-id'
+ })

TypeB24.fetchListMethod

Вызывает list-метод REST API Bitrix24 и возвращает асинхронный генератор.

Этот метод устарел и будет удалён в версии 3.0.0.

Для restApi:v2 следует использовать метод b24.actions.v2.fetchList.make(options).

- b24.fetchListMethod('some.method', { filter: { '>id': 123 } }, 'id', 'items')
+ b24.actions.v2.fetchList.make({
+   method: 'some.method',
+   params: { filter: { '>id': 123 } },
+   idKey: 'id',
+   customKeyForResult: 'items',
+   requestId: 'unique-request-id'
+ })

TypeB24.callBatch

Выполняет пакетный запрос к REST API Bitrix24.

Этот метод устарел и будет удалён в версии 3.0.0.

Для restApi:v2 следует использовать метод b24.actions.v2.batch.make(options).

- await b24.callBatch([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true, true)
+ await b24.actions.v2.batch.make({
+   calls: [
+     ['some.method.1', { filter: { '>id': 123 } }],
+     ['some.method.2', { filter: { '<id': 456 } }],
+   ],
+   options: { 
+     isHaltOnError: true,
+     returnAjaxResult: true,
+     requestId: 'unique-request-id'
+   }
+ })

TypeB24.callBatchByChunk

Выполняет пакетный запрос к REST API Bitrix24 с автоматическим разбиением на чанки для любого числа команд.

Этот метод устарел и будет удалён в версии 3.0.0.

Для restApi:v2 следует использовать метод b24.actions.v2.batchByChunk.make(options).

- await b24.callBatchByChunk([['some.method.1', { filter: { '>id': 123 } }], ['some.method.2', { filter: { '<id': 456 } }]], true)
+ await b24.actions.v2.batchByChunk.make({
+   calls: [
+     ['some.method.1', { filter: { '>id': 123 } }],
+     ['some.method.2', { filter: { '<id': 456 } }],
+   ],
+   options: { 
+     isHaltOnError: true,
+     requestId: 'unique-request-id'
+   }
+ })

LoggerBrowser

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

Этот класс устарел и будет удалён в версии 3.0.0.

Теперь используется более универсальная система логирования, отчасти похожая на Monolog (PHP).

- import { LoggerBrowser } from '@bitrix24/b24jssdk'
+ import { LoggerFactory } from '@bitrix24/b24jssdk'

- const $logger = LoggerBrowser.build('MyApp', import.meta.env?.DEV === true)
+ const $logger = LoggerFactory.createForBrowser('MyApp', import.meta.env?.DEV === true)

const dataList = { key1: value1, key2: value2 }

- $logger.info('response', dataList)
+ $logger.info('response', { someInfo: dataList })

UMD

Руководство по использованию UMD-версии Bitrix24 JS SDK в ваших приложениях.

v2 → v3

Как уйти с устаревшей REST-поверхности, которая удаляется в Bitrix24 JS SDK 3.0.0.