Формат данных

В этом разделе описаны флаги, которые можно использовать в различных запросах. От используемых флагов зависит результат, возвращаемый в JSON.

Если в возвращаемом результате необходимо получить значения нескольких флагов одновременно, то в запросе необходимо указать сумму этих флагов. Например, если для группы объектов надо получить значения основных 0x00000001 (1) и произвольных свойств 0x00000002 (2), то в запросе следует указать значение 3.

В запросах флаги указываются в формате DEC. Формат HEX поддерживается только как текстовый, например "flags":"0x101".

Если флаг указан как строка, сервер читает его следующим образом:

• значение, которое начинается с 0x, — число в формате HEX;
• значение, которое начинается с 0, — восьмеричное число;
• любое другое значение — число в формате DEC.

Не добавляйте ведущие нули к флагам, указанным как строки. Например, "flags":"0101" читается как восьмеричное число 101, то есть 65 в формате DEC, а не 101.

Флаги определяют, какие данные вы запрашиваете. Ваши права доступа к элементу определяют, какие из этих данных вы получите.

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

Например, флаг расширенных свойств объекта 0x00000100 (256) возвращает ключи uid, uid2, hw, ph, ph2 и psw пользователям с правом Просмотр настроек подключения, а ключи act, act_reason и dactt — пользователям, у которых есть только право Просмотр элемента и его основных свойств.

Для ключей, которые содержат максимально допустимое количество элементов, обычно требуется право на редактирование коллекции, а не на ее просмотр. Например, флаг геозон ресурса 0x00001000 (4096) возвращает ключ zl пользователям с правом Просмотр геозон, а ключ zlmax — только пользователям с правом Создание, редактирование и удаление геозон.

Чтобы проверить, какие права у вас есть, отправьте базовый флаг 0x00000001 (1) в запросе core/search_item или core/search_items и посмотрите на параметр uacl в возвращаемом результате. Он показывает ваши права на элемент с уже примененными ограничениями токена.

Ключ может отсутствовать также по следующим причинам:

• Флаг токена. Любая сессия создается с токеном, и его флаг (fl) может дополнительно ограничить ваши права доступа. Право, которое не включено во флаг токена, недоступно, даже если оно есть у пользователя. О правах, которые дает каждый флаг токена, см. в разделе Токены.

• Услуги и ограничения тарифного плана. Если тарифный план учетной записи не включает услугу или услуга достигла своего лимита, в возвращаемом результате нет данных по этой услуге, даже если у вас есть все права доступа. Чтобы проверить услуги и права доступа одновременно, используйте core/check_items_billing.

• Флаги подписки. Некоторые флаги не возвращают данные. Вместо этого они подписывают сессию на события. Это относится, например, к флагам Сообщения и Задачи.