How it Works
BrightSign
Loading...
Network Web API
User Manual
17 pgs855.05 Kb0

BrightSign Network Web API User Manual

Download
API REFERENCE MANUAL
BrightSign Network Version 3.8
BrightSign, LLC. 16795 Lark Ave., Suite 200 Los Gatos, CA 95032 | 408-852-9263 | www.brightsign.biz
TABLE OF CONTENTS
Introduction .......................................................................................................................... 1
Entities .............................................................................................................................................................................. 1
Methods ............................................................................................................................................................................ 2
Object Permissions ......................................................................................................................................................... 4
SOAP Endpoints .............................................................................................................................................................. 4
SOAP Access Point URLs ............................................................................................................................................... 5
User Authentication......................................................................................................................................................... 6
Development Tools ......................................................................................................................................................... 6
Content .................................................................................................................................. 7
Content Entity .................................................................................................................................................................. 7
ContentFolder Entity ....................................................................................................................................................... 8
ContentType Enumeration .............................................................................................................................................. 8
ContentTransition Enumeration ..................................................................................................................................... 8
DynamicPlaylistContent Entity-Relation ....................................................................................................................... 9
PresentationContent Entity-Relation ........................................................................................................................... 10
DynamicPlaylistInfo Structure ...................................................................................................................................... 11
PresentationInfo Structure ........................................................................................................................................... 11
Content Management Web Methods ............................................................................................................................ 11
Content Upload .................................................................................................................. 18
Overview ......................................................................................................................................................................... 18
Web Page Upload Work Flow ....................................................................................................................................... 18
Web Page Update Work Flow ....................................................................................................................................... 19
Content Upload Web Methods ...................................................................................................................................... 20
ContentUploadStatus StartFileUpload(string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum
ContentType, dateTime fileLastModifiedDate, string virtualPath, base64Binary fileThumb, string sha1Hash) .................................................. 21
ContentUploadStatus CompleteFileUpload(string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum
ContentType, dateTime fileLastModifiedDate, string virtualPath, base64Binary fileThumb, string sha1Hash) .................................................. 23
WebPageUploadStatus StartWebPageUploadSession(array webpageAssets[], string uploadToken, string sessionToken, string filename, long
filesize, int chunksCount, enum ContentType, string virtualPath, base64Binary fileThumb, string sha1Hash) .................................................. 25
WebPageUploadStatus CompleteWebPageUploadSession(array webpageAssets[], string sessionToken, string filename, long filesize, int
chunksCount, enum ContentType, string virtualPath, base64Binary fileThumb, string sha1Hash) .................................................................... 27
Dynamic Playlist ................................................................................................................. 31
ImageVideoDynamicPlaylist Entity .............................................................................................................................. 31
AudioDynamicPlaylist Entity ........................................................................................................................................ 31
Dynamic Playlist Management Web Methods ............................................................................................................. 32
Live Text Feed .................................................................................................................... 44
LiveTextFeed Entity ....................................................................................................................................................... 44
LiveTextFeedItem Entity-Relation ................................................................................................................................ 44
Live Text Feed Management Web Methods ................................................................................................................. 45
Live Media Feed ................................................................................................................. 53
LiveMediaFeed Entity .................................................................................................................................................... 53
LiveMediaFeedContent Entity-Relation ....................................................................................................................... 53
Live Media Feed Management Web Methods .............................................................................................................. 54
Web Page ............................................................................................................................ 62
WebPage Entity ............................................................................................................................................................. 62
WebPageAsset Entity-Relation .................................................................................................................................... 62
PresentationContent Entity-Relation ........................................................................................................................... 63
Web Page Management Web Methods ........................................................................................................................ 63
Device Web Page ............................................................................................................... 70
DeviceWebPage Entity .................................................................................................................................................. 70
Device Web Page Management Web Methods ............................................................................................................ 70
Presentation ....................................................................................................................... 77
Presentation Entity ........................................................................................................................................................ 77
DeviceModel Enumeration ............................................................................................................................................ 78
PresentationLanguage Enumeration ........................................................................................................................... 78
ScreenSettings Structure .............................................................................................................................................. 78
PresentationZone Structure ......................................................................................................................................... 81
VideoOrImagesPresentationZone Structure ............................................................................................................... 81
EnhancedAudioPresentationZone ............................................................................................................................... 82
GroupInfo Structure ...................................................................................................................................................... 83
Presentation Management Web Methods .................................................................................................................... 83
Group .................................................................................................................................. 94
Group Entity ................................................................................................................................................................... 94
Group Management Web Methods ............................................................................................................................... 95
Schedule ........................................................................................................................... 100
ScheduledPresentation Entity-Relation ..................................................................................................................... 100
Schedule Management Web Methods ........................................................................................................................ 101
Device ................................................................................................................................ 107
Device Entity ................................................................................................................................................................ 107
DeviceLogReport Entity .............................................................................................................................................. 110
DeviceSubscriptionType Enumeration ...................................................................................................................... 111
DeviceLogType Enumeration ..................................................................................................................................... 111
DeviceSubscriptionStatus Enumeration ................................................................................................................... 111
DeviceConnectionsPeriod Enumeration ................................................................................................................... 112
DeviceNetworkSettings Structure .............................................................................................................................. 112
DeviceWiredSettings Structure .................................................................................................................................. 113
DeviceWirelessSettings Structure ............................................................................................................................. 113
DeviceLogsSettings Structure ................................................................................................................................... 114
DeviceHealthStatus Enumeration .............................................................................................................................. 114
DeviceError Structure ................................................................................................................................................. 115
DeviceDownload Structure ......................................................................................................................................... 115
Device Management Web Methods ............................................................................................................................ 115
1
INTRODUCTION
The BrightSign Network API exposes a large set of WebUI functionality using a standardized set of
entities, methods, and properties. Developers can use this API to build new interfaces that have a
different look and feel from, but provide a similar feature set to, the BrightSign Network WebUI.
This API Reference Manual first outlines the general working principles of interfacing with the BrightSign
Network API. It then describes the properties and methods of each entity in detail.
Entities
Identifiers
Each entity has a unique ID consisting of an incremental integer value that functions as its Primary Key. This allows for
simple identification and retrieval of a particular object instance. This value is usually not revealed to end users of the UI
because it is only useful for internal client/server operations.
Some entities also have Alternate Keys (the [string] Name property, for example) because the system often requires
the uniqueness of an entity within a BSN account. You can retrieve an entity using any of its keys, whether primary or
alternate.
Dependency
Almost all entities have “parent” and “child” entities contained within a dependency tree: For example, a Dynamic Playlist
entity includes Content entities on one hand, but is referenced by Presentation entities on the other. In this case, each
Content entity is the “child” of the Dynamic Playlist entity, while each Presentation entity functions as the “parent” of the
Dynamic Playlist entity.
If a particular object instance has one or more parent objects, then it is considered “in use”. In most cases, this status will
affect the operations that can be performed with it.
2
Methods
The BSN Web API provides different methods to perform similar operations. It is possible, for example, to retrieve/update
either all or a specified subgroup of properties. This allows you to choose which methods suit your deployment best in
terms of usability, responsiveness, etc.
Entity Retrieval Methods
Currently, there are four types of entity retrieval method:
Get{EntityName(s)}
Methods of this type retrieve all entities of the corresponding type and return paged results with initialized parent
dependencies and/or usage indicators. For performance reasons, they do not return child entities. The page size is limited
to a certain number depending on the method.
The BrightSign Network Web API implements a markers-based approach similar to the Amazon REST 3 API: The client
specifies the marker (entity ID) of the starting element in the list, as well as the number of entities to receive. The server
will indicate whether the response is truncated (i.e. there are more elements that can be retrieved by the next request)
and provide the marker for the next object instance.
Note: If a client has retrieved a first page and is in the process of retrieving the second while another client adds, updates,
or removes two objects on different pages, the first client may receive an inconsistent state.
GetSpecified{EntityName(s)}
Methods of this type retrieve entities with specified keys. The results will not be paged; as a result, there is a limit on the
number of entities that can be requested. This type of method will initialize only parent dependencies.
3
Find{EntityName(s)}
Methods of this type allow you to search for entities using a [string] Name pattern (including wildcards). This method
type only exists for entities that have a Name alternate key. These methods return paged results with initialized parent
dependencies and/or usage indicators.
Get{EntityName} / Get{EntityName}ByName
Methods of this type retrieve a single object instance using one of its Keys. Unlike other method types, these methods
allow retrieval of child entities along with the requested entity. This behavior is useful for entity properties dialogues (e.g. a
Group Properties dialogue that shows general information about a particular group) and entity management pages (e.g. a
Dynamic Playlist management page that can be initialized with a single call).
Entity Update Methods
Currently, there are two types of entity update method:
General Update Methods: e.g. UpdateGroup
These methods receive a complete object in its updated state and attempt to detect and store all changes on the
server side. These methods are useful in cases where a client retrieves an object first, allows the user to make
changes, and then passes the new state to the server without the need to track user changes or construct call
chains for applying a particular change (e.g. selecting the Edit button of a Dynamic Playlist in the BrightSign
Network WebUI)—this is a use case that fits most WebUI and some BrightAuthor scenarios.
These methods can also update object relations, so the client will be able to store not only all new property values,
but also, for instance, updated sets of Dynamic Playlists or presentation contents in a single transactional service
call without intermediate states.
4
Specific Update Methods: e.g. UpdateGroupsAutorun
These methods receive Entity IDs and one or more values for updating logically related properties within that entity
(for example, changing the minimum required firmware values for a group). Methods of this type don’t require the
client to retrieve the object first. This may be useful for small dialogs, groups of controls (such as those in
BrightAuthor), or internal client logic for sealing off certain parts of functionality from end users.
Object Permissions
Currently, all supported entities have a predetermined set of Object Permissions that cannot be changed. Customizable
permissions will be implemented in the future.
SOAP Endpoints
Currently, the BrightSign Network Web API consists of two web services with nearly identical configurations: the
Application Service and the Content Upload Service. Each web service has two SOAP endpoints: One is configured to
use the WS-* specification and the other to use the WS-I Basic Profile.
WS-*
The WS-* endpoint is intended for rich, multifunctional server or desktop applications that support features such as
sessions and transactions. The endpoint also supports its own rich security module and complex messaging format.
It would be difficult and time consuming to manually implement the required functionality for WS-*, including message
serialization/de-serialization, encoding/decoding, connection management, and state management. Therefore, in order to
utilize this endpoint, you will first need find a library that can create a service reference (i.e. proxy class) for your language
and/or platform. Windows features built-in tools for creating service references for .NET applications, where the WS-*
specification is the default web service endpoint configuration. Official or third-party tools/libraries have also been built for
some, but not all, languages and platforms.
5
Once you find such a tool/library for your platform, you will be able to create a service reference for the web service and
work with it using familiar methods in the code.
WS-I Basic
The WS-I Basic endpoint is defined for simple clients that support a small number of functions or don’t support the WS-*
specification. This specification does not support sessions or transactions. It does not have its own security module, using
IIS instead. As a result, the message format is much simpler. WS-I Basic is also supported by all languages and
platforms; it is even possible to use it directly without a service reference (i.e. proxy class) if needed (for example, through
JavaScript).
SOAP Access Point URLs
Use the following URLs to create service references:
• https://api.brightsignnetwork.com/2014/07/SOAP/WSDL/
• https://api.brightsignnetwork.com/Uploads/2014/07/SOAP/WSDL/
The service-endpoints addresses are specified in the WSDLs. Most SOAP tools and libraries used to create references
will find the addresses automatically. The current service endpoint URLs are as follows:
• http://api.brightsignnetwork.com/2014/07/SOAP/WS/
• https://api.brightsignnetwork.com/2014/07/SOAP/Basic/
• http://api.brightsignnetwork.com/Uploads/2014/07/SOAP/WS/
• https://api.brightsignnetwork.com/Uploads/2014/07/SOAP/Basic/
Note: Each URL has a specified API version (e.g. “2014/04/”). API versions will rarely, if ever, be changed after
production release, the exception being changes that will extend functionality but not affect existing clients. Older API
version URLs may be removed at a later time if deemed obsolete.
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use