Общие замечания¶

Ошибки, опечатки, не соответствия¶

В данном документе могут быть ошибки и опечатки. Реальное поведение API может иногда отличаться от описанного.

При доработке и изменении API мы оставляем обратную совместимость (на время или на всегда), но при исправлении ошибок вида "поведение API не соответствует документации" такого не происходит, так как исправляется явная ошибка.

Если реальное поведение API отличается от описанного здесь, то настоятельно рекомендуется не ориентироваться на "то что есть", а связаться с нами написав наask@sendsay.ruсообщение о найденной проблеме.

Формат дробных чисел¶

Разделителем целой и дробной частей является точка

123.456

точность дробной части и её наличие зависит от источника числа.

Кастомизированные ссылки¶

Все ссылки указываемые в вызовах и предназначенные для получения по ним данных (списков, файлов, картинок..) могут содержать метки для подстановки элементов текущих даты и +/- сдвиг и для подстановки случайного числа.

Кастомизация случайном числом записывается в виде

{RND}

Результат - число из 19 цифр. Несколько RND в одном url дадут один и тот же результат.

Кастомизация временем записывается в виде

{DT.format +D day +h hour round +m minute round +s second}

Все поля задающие сдвиг не обязательны, но их порядок от дня к секунде должен соблюдаться.

Знак сдвига обязателен и может быть "+" (как в примере) или "-".

К названию величины можно добавлять на конце "s"

Формат вывода даты-времени задаваемый в format не должен содержать пробельных символов (запишите две подстановки {DT}), а следующие последовательности заменяются в нём на компоненты даты текущей даты в момент использования ссылки для получения данных +/- сдвиг.

YYYY - год (4 цифры)

MM -  месяц (2 цифры)
DD -  день (2 цифры)
hh -  час (2 цифры)
mm -  минута (2 цифры)
ss -  секунда (2 цифры)

M -  месяц (1 или 2 цифры)
D -  день (1 или 2 цифры)
h -  час (1 или 2 цифры)
m -  минута (1 или 2 цифры)
s -  секунда (1 или 2 цифры)

Основное назначение этой особенности - облегчение создания действий по расписанию. Например, вам требуется ежедневно импортировать данные, но файл с ними имеет в названии текущий месяц и день. Тогда параметр со ссылкой на данные будет выглядеть как"http://test.ru/a/b/file{DT.MMDD}.csv".

Примеры

{DT.YYYY-MM-DD_hh:mm:ss + 1 day} - завтрашняя дата с точностью до секунды. "2015-03-24_18:00:43"

{DT.YYYY-MM-DD + 1 day} {DT.YYYY-MM-DD + 1 day} - завтрашняя дата с точностью до секунды через пробел. "2015-03-24 18:00:43"

{DT.DDMMYYYY - 2 days} - позавчерашняя дата с точностью до дня записанная слитно."22032015"

Указание на количество попыток получения данных¶

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

Создавать действие с несколькими запусками в этом случае не верно - после появления данных запланированное действие выполнится несколько раз, а не один.

Для выхода из такой ситуации, предусмотрена возможность вместе с адресом данных указать сколько раз пытаться их по ссылке получить и какую паузу делать между попытками.

Это работает во всех случаях когда в api-вызове требуется указать адрес для получения данных.

Система будет пытаться получить данные пока не наступит одно из событий

Данные будут получены (ответ http с кодом 200)
Закончатся все попытки
Закончится день в который было сделан api-вызов

Если ссылка содержит кастомизацию временем с помощью {DT} или случайным числом {RND}, то кастомизация будет вычисляться каждый раз заново при каждой новой попытке.

Для того что бы воспользоваться такой возможностью необходимо ссылку на данные записать не строкой, а объектом вида

{
 "uri" : "ссылка на данные" 

,"retrys" : "количество попыток" -- число от 2 до 288

,"retrys.delay" : "секунд между попытками" -- число от 60 до 3600

}

Например для импорта

{
 "action" : "member.import" 

.......

 ,"users.url" : {
                 "uri" : "http://test.ru/data{DT.YYYYMMDD}.csv" 

                ,"retrys" : 100

                ,"retrys.delay" : 300
                }

.......

}

Особенности работы сравнений в фильтрах.¶

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

Для строк при сравнении null или отсутствующее значение считается равным "".

Для чисел пустое, null или отсутствующее значение считается равным 0.

Для даты пустое, null или отсутствующее значение считается равным "0001-01-01" и обычным образом укорачивается до необходимой точности если надо.

Для даты-времени пустое или отсутствующее значение считается равным "0001-01-01 00:00:00" и обычным образом укорачивается до необходимой точности если надо.

Такие особенности введены специально для разрешения неоднозначностей при использовании в фильтрах отрицания вхождения в группу.

Например, у вас есть подписчик А со значением параметра dt равным "2023-12-01" и подписчик Б со значением параметра dt равным "2023-09-01"

Как и ожидается, в группу 1 с фильтром "dt < '2023-10-15" подпадёт только подписчик Б

А в группу 2 с фильтром "dt >= '2023-10-15" попадёт только подписчик А

И при использовании групп 1 и 2 в других группах с условием отрицания вхождения (!in_group) всё тоже будет ожидаемо.

Под условие !in_group(1) попадёт А, а под условие !in_group(2) попадёт Б.

Теперь добавим подписчика Ё c пустым значением dt.

Если не приравнивать пустую дату к 0001-01-00, то он не будет подходить под условия ни группы 1 ни группы 2.

Но будет подходить и под !in_group(1) и под !in_group(2) обе одновременно.

И если первое обычно понимаемо, то второе - его вхождение при отрицании в оба результата - вызывает у большинства пользователей панику и утверждения, что так не правильно.

В целом, вопрос не однозначный и зависит от бизнес-логики клиента.

Мы приняли решение как описано выше - пусто, null и отсутствие это некое значение - которое в 99.9999% устраивает всех клиентов.

Если для вас важно различать пустые значения чисел и дат при сравнении, то используйте явную дополнительную проверку на пусто и обязательно тестируйте варианты с !in_group.

JSON и числа¶

Обратите внимание, что если указывать числа (целые и дробные) именно как числа (а не как стоки - в кавычках), то надо помнить о строгости JSON в этом вопросе

не допустимы лидирующие нули ( 0123 - ошибка )
не допустим плюс ( +123 - ошибка )

Пользовательские метки объектов¶

Часть типов объектов (в перспективе все типы) позволяют присвоить каждому их экземпляру пару чисел для отметки их в пользовательских целях.

Такие объекты имеют параметры reltype (предполагается что это значение хранит некий обобщённый тип классификации) и relref (указатель на что-то внутри классификации).

По умолчанию при создании оба поля получают значения равные 0.

У обоих полей все отрицательные значения зарезервированы для системных нужд. Используйте для себя положительные значения во избежание конфликтов.

Тестирование с локальными адресами¶

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

К таким адресам относятся, например:

     10.0.0.0        -   10.255.255.255  (10/8 prefix)
     127.0.0.0       -   127.255.255.255 (127/8 prefix)
     172.16.0.0      -   172.31.255.255  (172.16/12 prefix)
     192.168.0.0     -   192.168.255.255 (192.168/16 prefix)

С полным списком можно ознакомиться в RFC 5735https://datatracker.ietf.org/doc/html/rfc5735