D3 API - Интерфейс к данным Digispot извне¶
- Table of contents
- D3 API - Интерфейс к данным Digispot извне
Назначение¶
Сервис предоставляет программный интерфейс (API) для с содержимым Расписания и МБД.
Для работы сервису требуется для сервиса из Digispot 3:
Установка сервиса¶
Описание - Установка_D3_API_сервиса_для_интеграции
Общие замечания¶
Сервис реализован в виде WCF SOAP сервиса с подключением через интерфейс HTTP. Такой способ предоставления удобен для автоматического синтеза клиента, т.к. предоставляет автоматическое описание методов сервиса через WSDL.
При обращение к URL сервиса в браузере, например, по http://localhost:8015/D3Services/ApiService, то в ответ будет регенерирована страничка с указанием URL для получения WSDL.
Форматы дат и длительностей¶
Даты указываются в формате yyyy-MM-dd HH:mm:ss
Длительность указываются в формате [HH:]mm:ss[.fff]
Модели данных¶
Для простых типов данных в API предусмотрены типы, например, Schedule для описания расписания.
Сложные типы данных описываются строкой JSON
- блок
- элемент блока
- элемент МБД
При формировании новых элементов или редактировании существующих необходимо указывать только минимально необходимый набор полей.
При редактировании объектов указываются только поля, которые необходимо изменить и минимально необходимые поля для идентификации редактируемых объектов.
Атрибуты МБД¶
Аттрибутами в МБД являются стандартные свойства Категория, Автор, Исполнитель, Вокал и пользовательские.
Информация о доступных атрибутах предоставляется методом
- AttributeInfo[] GetAttriributeList(), AttributeInfo описывает один атрибут
- AttributeValue[] GetAttributeValueList(string attribute_id) - предоставляет множество доступных значений атрибута.
Атрибуты МБД хранятся при описании элементов расписания и МБД в виде поля Attributes.
"Attributes": [
{
"Identity": "1", <- идентификатор атрибута = AttributeInfo.UID
"Values": [ <- массив значений атрибута
{
"Value": "AAA" <- значение атрибута, AttributeValue.Title
}
]
}
Ограничения¶
Модели данных содержат основной набор полей, но не позволяют пока полностью описать редактируемый объекты Digispot II.
Для обеспечения возможности создания новых элементов (МБД, блоков или элементов блока) с любыми доступными в Digispot II полями, предусмотрена возможность для клонирования существующих объектов. При клонировании в метод передается идентификатор уже существующего объекта, с которого снимается копия. Подробнее это описано в методах, использующих этот подход.
Редактирование МБД¶
Добавление элементов¶
Для добавления в МБД нового элемента необходимо вызвать метод string[] AddDBItems(string[] db_items_to_create)
с заполненным массивом db_items_to_create.
Каждым элементом db_items_to_create является JSON строка, описывающая создаваемый объект. Сервис попытается создать столько элементов, сколько элементов заполнено в db_items_to_create.
Метод вернет массив созданных объектов по размерности совпадающий с db_items_to_create.
Если при создании какого-либо элемента произошла ошибка - то в результирующем массиве в соответствующей позиции окажется элемент с Indentity = 0.
Есть два способа создания - описание свойствами или клонирование существующего элемента.
Создание¶
Для создания необходимо как минимум заполнить следующие значения
- Title - название элемента
- PartitionType, строка, раздел МБД, может принимать значения
- MT_COMMERCIALS
- MT_JINGLES
- MT_MUSIC
- MT_BROADCAST
- MT_NEWS
- Sort - строка, тип содержимого
- PAUSE
- PHONOGRAM
- INFO
- ROTATE_POS
- VIDEO
- PLACEHOLDER
Скорее всего понадобится указать
- категорию хранения элемента (см. выше)
Клонирование¶
В объекте DBItem необходимо указать идентификатор существующего элемента МБД в поле Identity. В результате будет создан новый элемент, полная копия указанного.
Если такого элемента нет - элемент не будет создан.
Возвращенный объект содержит описание нового созданного элемента с новым Identity.
Дополнительно к Identity можно указать другие поля, они будут применены к новому объекту, заменив скопированные значения.
Редактирование элемента МБД¶
Аналогично клонированию элемента для обновляемого элемента указывается Identity и поля, значения которых необходимо установить.
Выборка элементов¶
- string[] GetDBItemsByIds - возвращает массив элементов по массиву Identity
- string[] GetDBItemsByQuery(string partition_id, string category_id, int skip, int number, string[] field_ids)
Возвращает множество элементов в разделе МБД с идентификторм partition_id, входящих в категорию с идентификатором category_id.
Возвращается take элементов, начиная со skip. Так реализуется страничное листание. - field_ids указывает список полей, которые нужно получить для каждого элемента, пока не реализован и должен содержать null
Идентификатор раздела можно узнать, вызвав GetPartitions, идентификатор категории - вызвав GetCategoryList
Удаление¶
Для удаления вызывается метод DeleteDBItems и ему передается множество Identity удаляемых элементов.
Удаляемый элемент не удаляется физически, а отмечается как удаленный и может быть найден в корзине.
Редактирование расписания¶
Одно расписание описывается типом Schedule, содержащим уникальный идентификатор и название. Получить список можно методом Schedule[] GetScheduleList().
Один блок расписания описывается строкой JSON, состоящий из
- полей блока
- Массива SheduleItems, в котором находятся элементы блока.
Элементы блока в целом похожи на элементы МБД, основным отличием является поле InBlockId, содержащее идентификатор элемента в блоке.
Пример JSON-содержимого блока: http://jsoneditoronline.org/?id=110eef24e4bb02f99557622f24b35801
Получение существующих блоков¶
string[] GetScheduleBlockListByInterval(string schedule_id, DateTime from, DateTime to)
Возвращает все блоки, в порядке следования в расписании, время начала которых попадает в указанный интервал.
Создание новых блоков¶
void AddScheduleBlock(string schedule_id, string block_json, string template_name = null)
Блок может быть создан по шаблону блока или только описанием его полей.
После создания блока его описание можно получить, повторно запросив блоки из расписания.
Создание по шаблону¶
Для создания по шаблону необходимо передать имя шаблона блока в параметре template_name.
Все остальные параметры блока: время, размер и пр. будут применены к содержимому шаблона. Cозданный в расписании блока будет содержать все свойства шаблона, даже если они не доступны для редактирования через API.
Создание по описанию¶
Необходимо указать как минимум
- StartTime - Дата и время начала начала блока, например,
2017-10-09 00:00:00.000
- BlockType - Тип блока
- NewsBlock
- MusicBlock,
- CommercialBlock,
- BroadcastBlock,
- UndefinedBlock
- Size - Размер блока, например "00:10:00.000"
Если указать и заполнить ScheduleItems, то блок будет создан сразу вместе с элементами.
Редактирование блока¶
Редактирование блока происходит через метод
void UpdateScheduleBlock(string schedule_id, string block_id, DateTime time, string block_json)
Этот метод одновременно редактирует свойства самого блока и его элементов.
Необходимо указать
- schedule_id - идентификатор расписания
- block_id - идентификатор блока в расписании. Это поле Identity существующего блока.
- time - дату и время начала блока
- block_json - набор полей, которые необходимо изменить у блока.
Если какое-то поле не указано - оно не изменяется.
Редактирование элементов¶
Если ScheduleItems отсутствует в списке полей блока, то редактирование элементов блока не происходит.
Если ScheduleItems указан, то элементы блока будут заменены содержимым ScheduleItems по следующим правилам:
- если у элемента отсутствие InBlockId, то он будет создан в блоке (подробнее про создание см. ниже)
- если у элемента указан InBlockId, то если он находится в другой позиции, он будет перемещен, кроме этого, будут установлены другие указанные поля, как и при создании нового элемента блока.
- если в блоке ранее был элемент InBlockId, который отсутствует в ScheduleItems, то он будет удален.
При создании элемента блока можно клонировать существующий элемент МБД. Для этого необходимо указать его Identity в наборе свойств элемента.
Если такого элемента в МБД нет, метод завершится ошибкой(FaultException) и блок не будет изменен вообще.
Если элемент в блоке уже существовал, то его содержимое будет заменено на содержимое элементов МБД с указанным Identity, с сохранением идентификатора в блоке (InBlockId).