Ключи данных¶
"Ключ Данных" это строка описывающая путь к данным хранимым для данного адреса.
Этот новый формат доступы к данным разработан для замены форматы АВО и поддержки хранения сложных структур данных.
На самом деле вы уже знакомы в ключами данных если:
-
впускаете Экспресс-Выпуск с данными в формате JSON-массив
-
используете внешние данные для персонализации писем
-
даже просто пользуетесь персонализацией выпуска (запись [% anketa.person.name %] это доступ по ключу данных из трёх элементов :)
Синтаксис¶
Ключ данных описывает путь по структуре данных который надо пройти для получения нужного значения.
Путь состоит из отдельных элементов (минимум из одного) разделяемых точками:
Ключ из трёх элементов - "aaa","bbb","ccc"
Набор символов элемента пути технически не ограничен, однако стоит проявить разумную сдержанность:
Ключ с на китайском 關鍵.數據
Точка внутри сегмента экранируется обратным слэшем aaa.b@b.b.ccc
Ключ по прежнему из трёх элементов - "aaa","b@b.b","ccc"
Для доступа к элементу объекта его ключ в объекте записываетсячерез точкупосле пути до объекта.
В элементе "aaa" взять "bbb", а от него "ccc" aaa.bbb.ccc
Для доступа к элементу массива его индекс записывается в квадратных скобкахсразу послепути до массива.
Есть специальные ключи данных - "*", "$" и "@" - они описаны в вызовах которые их поддерживают.
Преимущества¶
-
Данные формата АВО полностью доступны через КД
-
Нет ограничения на набор хранимых данных
-
Нет ограничений на сложность иерархии хранения данных и их сочетание (например, "адреса подписчика" могут представлять собой массив из объектов хранящих структуру одного адреса по компонентам (страна, город, улица, дом, квартира, координаты), а компоненты адреса в свою очередь там же быть объектами - "координаты" это "широта" и "долгота").
-
Нет ограничений на формат данных
-
У разных подписчиков по одному и тому же ключу данных можно хранить разные структуры и типы данных
-
Доступ к данным в выпуске рассылки осуществляется как и прежде путём прямой записи [% anketa.ключ.данных] или через функцию datakey() - [datakey(anketa,keyvar) %], где keyvar это переменная значением которой является ключ данных (для доступа по динамически формируемым ключам или в случае когда ключ содержит символы не подходящие для прямой записи anketa.ключ.данных)
Совместимость¶
Все данные старого формата АВО доступны через КД без каких-либо ухищрений.
Код "Анекты" становится первым элементом пути в ключе данных, код вопроса - вторым: "aid.qid"
Большинство вызовов уже поддерживает КД. Не поддерживают КД только вызовы form., format.. Это будет сделано в ближайшее время.
Есть только два момента, которые необходимо учесть:
-
значение для того, что в АВО называется "вопрос с выбором" это объект, а не массив и не скалар. Ключами объекта - кода ответов, значения - null.
-
внутренний формат даты в модели АВО это "YYYYMMDDhhmmss", а в модели КД это "YYYY-MM-DD hh:mm:ss".
Это учитывается автоматически при использовании вызова member.get, но при персонализации выпуска рассылки эта разница может быть заметна.
При использовании member.set за этим необходимо следить самостоятельно
- при записи вопроса с множественным вызовом необходимо записывать правильный объект с правильным количеством (не болей одного если вопрос с единственным выбором) ключей (ключи должны быть из тех что описаны в анкете)
- при записи даты, если только у вас что-то не зависит сильно от её старого формата, лучше использовать новый формат "YYYY-MM-DD hh:mm:ss"
Если вы проверили формат КД для решения своих задач и убедились что он вам подходит, то мы можем помочь вам с автоматизированным переводом формата хранения даты в новый вид - обратитесь в Службу поддержки. (формально вы и сами можете провести такое преобразование, но мы сделаем это для вас проще и быстрее).
Данные формата КД ограниченно доступны при использовании доступа по модели АВО так как только самые простые варианты структур данных доступны через АВО.
Возможные изменения¶
Длина одного компонента пути ключа данных и всего ключа данных в данный момент не зафиксирована окончательно что бы изучить потребности клиентов. Скорее всего общая длина будет ограничена 255 символами.
Длина строки данных в данный момент не зафиксирована окончательно что бы изучить потребности клиентов. Скорее всего она длина будет ограничена 255 символами, но с предоставлением альтернативы "больших строк".
Для численных операций, минимальное и максимальное целое число в данный момент не определены, но ориентируйтесь на возможности предоставляемые 64-битными вычислениями.
Для численных операций, точность числа с плавающей точкой в данный момент не определена, но ориентируйтесь на возможности предоставляемые 64-битными вычислениями.
По одному и тому же ключу данных у разных подписчиков могут хранится данные разной структуры. Это экспериментальная возможность. Скорее всего она будет отменена с введением типизации и словаря данных.
По одному и тому же ключу данных у разных подписчиков могут хранится данные разного типа. Это экспериментальная возможность. Скорее всего она будет отменена с введением типизации и словаря данных.
В данный момент не проводится проверки данных вносимых через вызовы member.set и member.import на соответствие тому или иному типу данных (кроме проверки дат и времени). С введением типизации и словаря данных такие проверки станут как минимум возможны по вашему желанию, а в некоторых случаях проводится автоматически.
Форматы данных¶
Все данных поддерживают набор символов Unicode.
Для хранения и доступа с использованием Ключей Данных доступны следующие типы величин:
Скаляр¶
"Просто значение" представляющее собой число или строку.
null¶
Специальный вариант скаляра обозначающий "неопределённое значение".
Записывается просто как
Без кавычек !
Массив (список)¶
Упорядоченный набор других величин (любых).
Каждая величина имеет свой "индекс" (начиная в 0) в массиве описывающих её позицию.
Например, массив из трёх величин, последняя из которых - другой массив
Объект (словарь)¶
Набор пар "ключ - значение", где "ключ" - скаляр, а "значение" - любая величина.
Каждый ключ объекта уникален и имеет только одну соответствующую ему величину.
Например
{
"один" : "111"
,"зима" : [ декабрь", "январь", "февраль"]
,"килограмм" : {
"грамм" : 1000
,"унция" : 36.81
}
,"關鍵" : { 數據" : "關鍵數據是最好的事情" }
}
Пример структуры данных¶
Пример структуры данных описывающей несколько адресов у одного из подписчиков:
{
"member" : { ............}
,"contact" : [
{
"title" : "Центральный офис"
,"phone:" : [ "+78216550011" ,"88003336963" ]
,"is_office" : "1"
,"address" : {
"country" : "Россия"
,"index" : "197022"
,"city" : ", Санкт-Петербург"
,"street" : "ул. Профессора Попова "
,"building" : "д.23 лит.Д"
,"apartment" : "пом. 27Н (офис 413)"
,"alias" : "БЦ «Гайот»"
,"location" : {
"latitude" : "59.972256"
,"longitude" : "30.311468"
}
}
}
,{
"title" : "Московский офис"
,"phone:" : [ "+74952695015" ,"88003336963" ]
,"is_office" : "1"
,"address" : {
"country" : "Россия"
,"index" : "121087"
,"city" : "Москва"
,"street" : "Улица Барклая"
,"building" : "д. 6 стр. 5"
,"apartment" : "офис № 217"
,"alias" : "бизнес-центр «Барклай Плаза»"
,"location" : {
"latitude" : "55.752678"
,"longitude" : "37.702110"
}
}
}
]
}
Второй номер телефона основного офиса -"contact[0].phone[1]"
Город московского офиса -"contact[1].address.city"
Координаты основного офиса -"contact[0].location"
Широта основного офиса -"contact[0].location.latitude"
Хранение данных о подписчике¶
Данные об одном подписчике представляются как корневой объект имеющий как минимум ключ "member" по которому во вложенном объекте хранятся системные данных об адресе, а остальные ключи корневого объекта вы используете по своему усмотрению.
{
"member" : {
"id" : ....
,"email" : ....
,"domain" : ....
,....
}
,"ваш ключ-1" : ............
,"ваш ключ-2" : ............
,"ваш ключ-3" : ............
}
Использование в персонализации писем¶
Доступ к данным подписчика в выпуске рассылки осуществляется как и прежде - через объект anketa:
Функция datakey() полезна когда ключ данных содержит символы, не допустимые напрямую в командах персонализатора (это временно), или когда ключ данных хранится в другой переменной (например в результатах фильтра с has/save).
[% datakey(anketa,keyvar) %], где keyvar это переменная значением которой является ключ данных.
[% datakey(anketa,"ключ.данных") %], где "ключ.данных" это строка, непосредственно задающая ключ данных.
Формально datakey() предназначен для помощи в косвенной адресации и первым параметром функции может быть любая переменная персонализации, не обязательно только anketa.