Форматы данных для импортирования и Экспресс-выпуска¶
Указание дат и времени для модели АВО¶
В зависимости от точности заданной в анкете для вопроса типа "дата", необходимо использовать один из следующих форматов записи даты или даты-времени в данных импорта:
точность yd - "YYYY-MM-DD" точность yh - "YYYY-MM-DD hh" точность ym - "YYYY-MM-DD hh:mm" точность ys - "YYYY-MM-DD hh:mm:ss"
Указание дат и времени для модели КД¶
Рекомендации для указания даты и времени те же, что и описанные в вызове member.set
Присоединение или удаление дополнительных идентификаторов для модели АВО¶
При внесении пользователей возможно указание его дополнительных идентификаторов для присоединения или удаления.
Специальные колонки называются member.head.attach и member.head.detach и ведут себя аналогично одноимённым вызовам.
В отличии от обычных колонок данных эти специальные колонки могут быть указаны не по одному разу.
Допустимое значение может быть
- Пустым
- Идентификатором для присоединения или удаления
- Списком идентификаторов через "|"
Если идентификаторы в колонке имеют одни и тот же тип который не определяется автоматически, то тип можно указать в названии колонки. Например "member.head.attach:csid".
Указание типа в названии колонки полезно и при внесении автоматически определяемых типов для строго контроля. Например при добавлении номеров телефонов и без строгой типизации случайно попавший в данные email будет обработан. А при строгой типизации - нет.
Вся запись пользователя вносится атомарно - проблема с присоединением или удалением отменит все действия (изменение прочих данных, внесение в группу импорта, создание подписчика).
Пример:
email,a265.q827,member.head.attach:email,a265.q300,member.head.attach:csid
30_m-1@test.ru,30-M1-265+,30_m-1-A@test.ru,30-M1-300,30_m-1-B@test.ru
30_m-2@test.ru,30-M2-265+,,30-M1-300,30_m-2-B@test.ru
30_m-3@test.ru,30-M3-265+,30_m-3-A@test.ru,30-M3-300,30_m-3-B@test.ru|30_m-3-C@test.ru
30_m-4@test.ru,30-M2-265+,,,xxxxxx
Присоединение или удаление дополнительных идентификаторов для модели КД¶
При внесении пользователей возможно указание его дополнительных идентификаторов для присоединения или удаления.
Специальные ключи данных называются member.head.attach и member.head.detach и ведут себя аналогично одноимённым вызовам.
{
"datakey" : "member.head.attach|detach"
,"addr_type" : "тип адреса" -- не обязательно. строгая типизация типа идентификатора.
}
Допустимое значение может быть
- Пустым
- Идентификатором для присоединения или удаления
- Массивом идентификаторов
Если идентификаторы в имеют одни и тот же тип который не определяется автоматически, то тип можно указать в addr_type.
Указание типа полезно и при внесении автоматически определяемых типов для строго контроля. Например при добавлении номеров телефонов и без строгой типизации случайно попавший в данные email будет обработан. А при строгой типизации - нет.
Вся запись пользователя вносится атомарно - проблема с присоединением или удалением отменит все действия (изменение прочих данных, внесение в группу импорта, создание подписчика).
Данные для pushapp¶
При импортировании или Экспресс-Выпуске реест получателей должен обязательно содержать
-
или колонку member.pushap - тогда вы указываете только уже внесённых ранее получателей
-
или следующий набор колонок позволяющих создать нового получателя при его отсутствии
authext_id - номер внешней аутентификации (обязательное)
token - токен юзера (обязательное)
service - fcm | apns | hms - к какому сервису принадлежит (обязательное)
os - android | ios |huawei - операционная система устройства (ОС) (обязательное)
os_version - строка - версия ОС (не обязательно)
device_model - строка - модель устройства (не обязательно)
Описание форматов¶
Для импортирования данных или выпуска рассылки через Экспресс-Выпуск доступны четыре формата описания адресов и их данных.
Данные задаваемые непосредственно в вызове указываются в параметре users.list
Внешние данные указываются ссылкой в параметре users.url
Вместо настоящего идентификатора подписчика вы можете указывать номер подписчика в системе - id:DDDD - где DDD номер подписчика доступный через member.id (только для уже существующих подписчиков)
При использовании в модели ABO значение для вопроса с выбором может быть как кодом ответа, так и названием ответа.
Если значение совпало с имеющимся кодом - значит это код.
Иначе значение сопоставляется с названиями ответов и при нахождении точного соответствия будет использовать код ответа найденного названия.
Если два ответа имеют одинаковое название - выбирается первый по порядку строчной сортировки их кодов.
JSON-массив¶
Непосредственно задание массива содержащего объекты каждый из которых описывает один адрес и его данных любой структуры.(только Экспресс-выпуск)
Данные трактуются по модели КД.
При выпуске почтовой рассылки адрес получателя задаётся ключом member.email
При выпуске sms рассылки номер получателя задаётся ключом member.cellphone
При выпуске viber рассылки номер получателя задаётся ключом member.viber
Остальные данные не обязательны и могут быть любой структуры, что в сочетании с возможностью шаблонизатора организовывать циклы, получать списки ключей и значений объектов позволяет создавать очень сложные шаблоны.
JSON-объект-АВО¶
Непосредственно задание объекта содержащего массив caption для описания соответствия столбцов данных анкетам и массив rows для самих данных.
При выпуске почтовой рассылки адрес получателя находится в колонке member.email.
При выпуске sms рассылки номер получателя находится в колонке member.cellphone.
При выпуске viber рассылки номер получателя находится в колонке member.viber.
Остальные данные не обязательны, но при их наличии каждая колонка содержит только по одному значению для каждого адреса (не может быть массивом или объектом) и должна быть описана в caption.
JSON-объект-КД¶
Непосредственно задание объекта содержащего массив caption для описания соответствия столбцов ключам данных и массив rows для самих данных.(только импорт)
XLSX¶
Представление содержимого файла XLSX (Excel 2007) в виде строки.
Данные трактуются по модели АВО
Рекомендуется всё же CSV - XLSX всё равно преобразуется внутри в CSV для того, что бы подключить многопоточную обработку, а преобразование хоть и быстрое (тысячи строк с секунду) но на большом реестре всё равно займёт заметное время.
Первый лист должен содержать в первой строке описание какой анкете и ответу соответствует данная колонка (в формате коданкеты.кодвопроса).
При импорте возможно задание этого соответствия в параметре caption вместо первой строки первого листа.
Одна ячейка может содержать только одно значение для каждого адреса (не может быть массивом или объектом).
Понимаются данных сжатые архиватором zip, хотя пользы от этого ни какой - xlsx и так является zip-архивом и повторное сжатие нечего не даст.
CSV¶
Представление содержимого файла CSV в виде строки.
Данные трактуются по модели АВО
Разделитель колонок - запятая или точка с запятой.
Символ экранирования - двойная кавычка.
Содержимое ячейки может быть заключено в кавычки.
Если надо внести сразу несколько ответов на вопрос с множественным выбором, то ячейка должна содержать кода необходимых ответов разделенной символом вертикальной черты "|".
Первая может содержать "#charset=кошка" для однозначного определения кодировки.
Тогда следующая строка должна содержать описание какой анкете и ответу соответствует данная колонка (в формате коданкеты.кодвопроса).
При импорте возможно задание этого соответствия в параметре caption вместо строки.
Одна ячейка может содержать только одно значение для каждого адреса (не может быть массивом или объектом).
Понимаются данных сжатые архиватором zip.
Если в колонке как часть его значения встречается символ разделитель колонок, то значение колонки должно быть взято в кавычки. Если в колонке как часть его значения встречается символ экранирования, то значение колонки должно быть взято в кавычки, а символ экранирования удвоен.
Верно: test@test.ru,"ЗАО ""Рога и копыта""",+70000000000 test@test.ru,"Рога, копыта и хвосты",+70000000000
НЕ верно:
Порядок определения формата при использовании users.list¶
1) Если значение массив, то данные считаются заданными в формате JSON-массив
2) Если значение объект, то данные считаются заданными в формате JSON-объект
3) Если значение строка представляющая zip-архив и он содержит файл workbook.xml, то считается что это XLSX (технически XLSX это zip-архив со специальным набором файлов)
4) Если значение строка представляющая zip-архив и он не содержит файл workbook.xml, берётся первый по порядку файл архива и считается, что это данные в формате CSV
5) Если значение строка не-zip-архив, то считается, что это данные в формате CSV
Порядок определения формата при использовании users.url¶
1) Если content-type ответа application/json, то данные должны описывать массив или объект и формат выбирается как описано выше в пунктах 1 и 2.
2) При другом значении content-type выбор происходит как описано выше в пунктах 3, 4 и 5.
Пример задания JSON-массив¶
Доступ к этим данным при Экспресс-выпуске осуществляется с использованием префикса "anketa".
Например:[% anketa.member.email %] [% anketa.hash.DEF %] [% anketa.peronal.something[0].aaa %]
"users.list" : [
{
"member" : { "email" : "test@test.ru" },
-- простые данные
"string" : "строка текста какой-то длинные",
"hash" : {
"DEF" : "значение ключа DEF"
,"ABC" : "значение ключа ABC"
},
"array" : [ "первый элемент" ,"второй элемент" ,"третий элемент" ....],
-- структура с вложенными данными
"personal" : {
"fio" : {
"fam" : "Фамилия"
,"name" : "Имя"
}
"homephone" : "112",
"gender" : "есть",
"something" : [ { "aaa" : "bbb", "ccc" : "ddd" }, "eeeee", [ "ffff", "ggg", "hhh"] ]
}
-- ещё структура
"kredit-payment-by-month" : [
{
"month" : "2012-12"
,"summa" : "1234"
},
{
"month" : "2013-01"
,"summa" : "4567"
},
{
"month" : "2013-02"
,"summa" : "8901"
}
]
},
{
"member" : { "email" : "test2@test.ru" },
.........
},
.....
]
Пример задания JSON-объект-АВО¶
"users.list" : {
"caption" : [
{
"anketa" : "member"
,"quest" : "cellphone"
},
{
"anketa" : "info"
,"quest" : "firstname"
},
{
"anketa" : "info"
,"quest" : "title"
},
{
"anketa" : "info"
,"quest" : "middlename"
},
],
"rows" : [
[ "+70000000000","Павел","Иванович","Уважаемый" ],
[ "+70000000000","Алексей","Алексеевич","Глубоко уважаемый" ],
......
]
}
Пример задания JSON-объект-КД¶
Параметр caption может содержать
- ignore - со значение 1 для игнорирования столбца - описание ключа данных datakey, режима mode и, не обязательно, тип данных "type" - в ячейке данных любая структура - указание на динамический ключ dynamic - в ячейке данных структура аналогичная единичной записи изменения данных как в member.set c datakey или null (ячейка игнорируется)
Изменение данных происходит по тем же правилам, что и при вызове member.set
Можно думать о импорте JSON-объект-КД как о массовом member.set с индивидуальными данными для каждого.
"users.list" : {
"caption":[
{
"datakey" : "ключ данных 1"
,"mode" : "режим 1"
,"type" : "тип данных-1"
}
,
{
"ignore" : 1
}
,
{
"datakey" : "ключ данных 2"
,"mode" : "режим 2"
,"type" : "тип данных-2"
}
,
{
"dynamic" : 1
}
.......
]
"rows" : [ -- в колонках данные любой структуры
[ "+70000000000","Павел","Иванович",[1,2,3] ],
[ "+70000000000","Алексей","Алексеевич",{ "a" : "B", "c" : "D" } ],
......
]
}
Пример задания XLSX¶
Все ячейки должны иметь тип "строка", не содержать ни какого форматирования или оформления.
В виду двоичного содержимого файла, он не может быть приведён в документации и доступен по ссылке
https://sendsay.ru/api/sample.xlsx