This document is the reference documentation of the NGSI API provided by WireCloud. For being able to use this API you have to add a requirement on this API thought the description file of the widget/operator. See the Using Orion Context Broker tutorial for more detailed documentation (and examples) on how to use this API.
Data types used by the library¶
-
The Entity type is used to reference entities. This type is defined as an object composed of the following fields:
id
is a string with the id of the entity. Some times you will be able to use patterns in this field.isPattern
is a boolean indicating whether the id field contains a regular expression pattern. (Optional field)type
is the type of the Entity. (Optional field)
-
The Attribute type is used to reference attributes. This type is defined as an object composed of the following fields:
name
is the name of the attributetype
is the type of the Attribute. (Optional field)
-
The Duration type is used to describe time intervals and defined as a string following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
-
The Condition type is used to declare the condition that will trigger notifications. This type is defined as an object composed of the following fields:
type
is an string containingONTIMEINTERVAL
orONCHANGE
values
: array of string. Depends on the value of the type field:ONTIMEINTERVAL
: exactly one value SHALL be present and SHALL represent the time interval between notificationsONCHANGE
: this element SHALL contain the name(s) of the Context Attributes to be monitored for changes
-
MetadataValue type is used to assign metadata to attributes. This type is defined as an object composed of the following fields:
name
is the name of the attribute metadatatype
is the type of the attribute metadatavalue
is the value to assign to the attribute metadata
-
The AttributeValue type is used to assign values to attributes. This type is defined as an object composed of the following fields:
name
is the name of the attributetype
is the type of the attribute. (Optional field)contextValue
is the value to assign to the attributemetadata
is the metadata associated with the attribute. This field is defined as a MetadataValue array
-
The AttributeUpdate type is used to describe a context update. This type is defined as an object composed of the following fields:
entity
is the entity affected by the update. This field is defined as an Entity array -attributes
is the new values for the attributes of the entity. This field is defined as an AttributeValue array
-
The AttributeDeletion type is used to describe the deletion of attributes from an entity. This type is defined as an object composed of the following fields:
- `entity` is the entity affected by the update. This field is defined as an **Entity** array - `attributes` is the new values for the attributes of the entity. This field is defined as an **AttributeValue** array. If you use `null` or an empty array for this field, the entity will be entirely removed.
NGSI.Connection¶
A new NGSI.Connection
can be instantiated using the following constructor:
NGSI.Connection(url[, options])
url
(String): is the url of the Orion Pub/Sub Context Broker instanceoptions
(Object; defaultnull
): This parameter may benull
if no extra option is needed. Current supported options are: -ngsi_proxy_url
(String; defaultnull
): URL of the NGSI proxy used for subscriptions -request_headers
(Object; defaultnull
): A set of key-value pairs, with properties representing header names. These extra headers will be use when making request to the context broker -use_user_fiware_token
(Boolean; default:false
): Use current user authentication token retrieved from the IdM system
Usage example:
This code creates a connection using the credentials of the user logged in WireCloud and supporting subcriptions through the FIWARE Lab's NGSI proxy:
var connection = new NGSI.Connection("http://orion.lab.fiware.org:1026/", {
ngsi_proxy_url: "https://ngsiproxy.lab.fiware.org",
use_user_fiware_token: true
});
This code creates a connection using the FIWARE-Service
header to make use of the multitenancy support provided by the
context broker:
var connection = new NGSI.Connection("http://<mi_context_broker_ip>:1026/", {
request_headers: {
"FIWARE-Service": "fiwareiot"
}
});
Callback options¶
All the method of NGSI.Connection
support at least the following callbacks:
onSuccess
is called when the request finishes successfullyonFailure
is called when the request finishes with errorsonComplete
is called when the request finishes regardless of whether the request is successful or not
createRegistration
¶
Register context information (entities and attributes) in the NGSI server
createRegistration(entities, attributes, duration, providingApplication[, options])
entities
is the list of Entities that are going to be registeredattributes
is a list of the Attributes that are going to be assigned to the previous list of entitiesduration
is the Duration for this registrationprovidingApplication
is the URI of the application to which this registration belongs to
The onSuccess
callback will receive an object with the following fields:
registrationId
is the final assigned idduration
is the final assigned duration for this registration
Usage example:
connection.createRegistration(
[{ type: "Technician", id: "entity1" }],
[{ name: "attr1", type: "string" }, { name: "attr2" }, { name: "attr3", type: "number" }],
"PT24H",
"http://app.example.com/",
{
onSuccess: function(data) {
//data.subscriptionId
}
}
);
updateRegistration
¶
Updates a particular registration.
updateRegistration(entities, attributes, duration, providingApplication, options);
regId
is the id of the registration to updateentities
is the list of Entities that its going to replace the previous established oneattributes
is a list of the Attributes that are going to be assigned to the provided list of entitiesduration
is the new Duration for the registration identified byregId
providingApplication
is the new value for the providingApplication property of the registration
The onSuccess
callback will receive an object with the following fields:
registrationId
is the id of the registrationduration
is the final assigned duration for this registration
Example usage:
connection.updateRegistration(
"167",
[{ type: "Technician", id: "entity1" }],
[{ name: "attr1", type: "string" }, { name: "attr2" }],
"PT24H",
"http://app.example.com/"
);
cancelRegistration
¶
Cancels or deletes a particular registration.
cancelRegistration(regId[, options])
regId
is the id of the registration to cancel
Example usage:
connection.cancelRegistration("167", {
onSuccess: function() {
// Registration cancelled successfully
}
});
discoverAvailability
¶
Discover context information registrations in the NGSI server.
discoverAvailability(entities, attributeNames[, options])
entities
is the list of Entities that are going to be queriedattributeNames
is the list of attribute names that are going to be queried. This parameter is optional and thusnull
is a valid value
The onSuccess
callback will receive an array with the registrations meeting the query requirements as the first
parameter.
Example usage:
connection.discoverAvailability([
{type: 'Technician', id: 'entity1'},
{type: 'Van', id: '.*', isPattern: true},
],
null,
{
onSuccess: function (registrations) {
...
}
}
);
query
¶
Query for context information. That information is returned using pagination (see supported options), so its very
recommended the use of the details
option. This option is currently disabled by default, but expect it to be enabled
by default in next versions of WireCloud.
query(entities, attributeNames[, options])
entities
is the list of Entities to queryattributeNames
is the list of attribute names to query. Usenull
for retrieving all the attributes
The query
method supports other extra options:
flat
(Boolean; default:false
): This options is used for simplifying the data structure used for representing the returned datalimit
(Number; default: 20): This option allow you to specify the maximum number of entities you want to receive from the serveroffset
(Number; default: 0): Allows you to skip a given number of elements at the beginningdetails
(Boolean; default:false
): Makes the server return more detailed information about the request (currently those details are related to the pagination)
Example usage:
connection.query([
{type: 'Technician', id: '.*', isPattern: true}
],
null,
{
limit: 100,
offset: 200,
details: true
onSuccess: function (data, details) {
...
}
}
);
This is the value of the data parameter passed to the onSuccess
callback when using the flat
is false
:
[
{
"entity": {
"id": "van1",
"type": "Van"
},
"attributes": [
{
"name": "current_position",
"type": "coordinates",
"contextValue": "43.47557, -3.8048315",
"metadata": [{ "name": "location", "type": "string", "value": "WGS84" }]
}
]
},
{
"entity": {
"id": "van2",
"type": "Van"
},
"attributes": [
{
"name": "current_position",
"type": "coordinates",
"contextValue": "43.47258, -3.8026643",
"metadata": [{ "name": "location", "type": "string", "value": "WGS84" }]
}
]
},
{
"entity": {
"id": "van3",
"type": "Van"
},
"attributes": [
{
"name": "current_position",
"type": "coordinates",
"contextValue": "43.47866, -3.7991238",
"metadata": [{ "name": "location", "type": "string", "value": "WGS84" }]
}
]
},
{
"entity": {
"id": "van4",
"type": "Van"
},
"attributes": [
{
"name": "current_position",
"type": "coordinates",
"contextValue": "43.471214, -3.7994885",
"metadata": [{ "name": "location", "type": "string", "value": "WGS84" }]
}
]
}
]
This is the value of the data parameter when flat
is true
:
{
"van1": {
"id": "van1",
"type": "Van",
"current_position": "43.47557, -3.8048315"
},
"van2": {
"id": "van2",
"type": "Van",
"current_position": "43.47258, -3.8026643"
},
"van3": {
"id": "van3",
"type": "Van",
"current_position": "43.47866, -3.7991238"
},
"van4": {
"id": "van4",
"type": "Van",
"current_position": "43.471214, -3.7994885"
}
}
updateAttributes
¶
Update context information.
updateAttributes(update[, options])
update
a list of AttributeUpdates
The onSuccess
callback will receive an array with the response and a array with the not accepted updates as the first
and the second parameter respectively.
Example usage:
connection.updateAttributes(
[
{
entity: { type: "Technician", id: "entity1" },
attributes: [
{ name: "mobile_phone", type: "string", contextValue: "0034223456789" },
{ name: "attr2", contextValue: "value" },
{ name: "attr3", contextValue: 5 }
]
}
],
{
onSuccess: function(data) {}
}
);
addAttributes
¶
Add/update entity attributes. This operation will create the attribute on those entities where they doesn't exist. In addition to this, this operation will also create entities if they doesn't exist.
addAttributes(toAdd[, options])
toAdd
a list of AttributeUpdates
The onSuccess
callback will receive an array with the response and a array with the not accepted updates as the first
and the second parameter respectively.
Example usage:
connection.addAttributes(
[
{
entity: { type: "Technician", id: "entity1" },
attributes: [{ name: "new_attribute", type: "string", contextValue: "value" }]
}
],
{
onSuccess: function(data, partial_errors) {}
}
);
deleteAttributes
¶
Delete attributes form entities. This method can be use also for removing entities from the context broker.
deleteAttributes(toDelete[, options])
toDelete
a list of AttributeDeletion
The onSuccess
callback will receive an array with the response and a array with the not accepted updates as the first
and the second parameter respectively.
Example usage (removing the position
attribute from the Madrid
entity):
connection.deleteAttributes(
[
{
entity: { type: "City", id: "Madrid" },
attributes: {
name: "position",
type: "coords"
}
}
],
{
onSuccess: function(data, partial_errors) {}
}
);
Example usage (removing Madrid
from the context broker):
connection.deleteAttributes(
[
{
entity: { type: "City", id: "Madrid" }
}
],
{
onSuccess: function(data, partial_errors) {}
}
);
createSubscription
¶
Subscribe to changes in the context information.
createSubscription(entities, attributeNames, duration, throttling, conditions, options);
entities
is the list of Entities to query in this subscriptionattributeNames
is the list of attribute names to query in this subscription. Usenull
for retrieving all the attributesduration
is the Duration of this subscriptionthrottling
is the proposed minimum interval between notifications. This value must be provided using the Duration type. You can also passnull
if you don't want to provide a throttling valueconditions
is a list of Conditions that will trigger queries using the provided information and their subsequent notifications to theonNotify
callback
This method, supports a new type of callback: onNotify
. This callback is required and can be either an URL or a
function. In the later case, the NGSI Connection must be created using a NGSI proxy and will be called every time a
notification comes from the NGSI server.
The first parameter of a onNotify
callback function will be an object with the response data.
In addition to this, the createSubscription
method supports an extra option:
flat
(Boolean; default:false
): This options is used for simplifying the data structure used for representing the returned data
Example usage:
connection.createSubscription(
[{ type: "Technician", id: "tech*", isPattern: true }, { type: "Van", id: "van1" }],
null,
"PT24H",
null,
[{ type: "ONCHANGE", condValues: ["position"] }],
{
onNotify: function(data) {
// called when a notification arrives
},
onSuccess: function(data) {
// subscription created successfully
// data.subscriptionId contains the id associated with the created subscription
}
}
);
updateSubscription
¶
Update context subscription.
updateSubscription(subId, duration, throttling, conditions[, options])
subId
is the id of the context subscription to cancelduration
is the Duration of this subscriptionthrottling
is the proposed minimum interval between notifications. This value must be provided using the Duration type. This parameter is optional acceptingnull
, in that case the throttling configuration of the subscription will not be updatedconditions
is a list of Conditions that will trigger queries using the provided information and their subsequent notifications to theonNotify
callback. This parameter is optional acceptingnull
, in that case the conditions configuration of the subscription will not be updated
Example usage:
connection.updateSubscription("sub1", "PT20H", null, null, {
onSuccess: function(response_data) {
// subscription updated successfully
}
});
cancelSubscription
¶
Cancels or deletes context subscription.
cancelSubscription(subId[, options])
subId
is the id of the context subscription to cancel
Example usage:
connection.cancelSubscription("sub1", {
onSuccess: function(data) {
// Subscription canceled successfully
// data.subscriptionId should be equal to 'sub1'
}
});
getAvailableTypes
¶
Get info about about the used context types. This information is currently composed of the type name and the attributes used with that type (the attribute set returned by this operation is the union of the attributes used in each of the entities belonging to that type).
getAvailableTypes(options);
The getAvailableTypes
method supports an extra option:
limit
(Number; default: 20): This option allow you to specify the maximum number of entities you want to receive from the serveroffset
(Number; default: 0): Allows you to skip a given number of elements at the beginningdetails
(Boolean; default:true
): Makes the server return more detailed information about the request (currently those details are related to the pagination)
Example usage:
connection.getAvailableTypes({
onSuccess: function(types, details) {
// The types parameter contains the information
// about the available types, see next slide for
// more info
}
});
types
parameter example:
[
{
"attributes": ["speed", "fuel", "temperature"],
"name": "Car"
},
{
"attributes": ["pressure", "hummidity", "temperature"],
"name": "Room"
}
]
getTypeInfo
¶
Get info about about a concrete entity type. This information is currently composed of the type name and the attributes used with that type (the attribute set returned by this operation is the union of the attributes used in each of the entities belonging to that type).
getTypeInfo(type, options);
Example usage:
connection.getTypeInfo("Room", {
onSuccess: function(type_info) {
// The type_info parameter contains the information
// about the Room type, see next slide for more info
}
});
type_info
parameter example:
{
"attributes": ["hummidity", "pressure", "temperature"],
"name": "Room"
}