new NGSI.Connection(url [, options])
Creates a new NGSI Connection.
Parameters:
Name | Type | Description |
---|---|---|
url |
String | URL | URL of the context broker |
[options ] |
Object | Object with extra options:
|
Examples
var connection = new NGSI.Connection("https://orion.example.com");
var connection = new NGSI.Connection("http://orion.lab.fiware.org:1026", {
headers: {
"X-Auth-Token": token
}
});
Methods
-
getServerDetails([options])
-
Retrieves context broker server information.
Parameters:
Name Type Description [ options
]Object Object with extra options:
correlator
(String
): Transaction id
Returns:
- Type
- Promise
Example
connection.getServerDetails().then( (response) => { // Server information retrieved successfully // response.details contains all the details returned by the server. // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving server information // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v1.addAttributes(toAdd [, options])
-
Adds or updates entity attributes. This operation will create attributes and entities.
Parameters:
Name Type Description toAdd
Array attribute additions
[ options
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.addAttributes([ { 'entity': {type: 'Technician', id: 'entity1'}, 'attributes': [ {'name': 'new_attribute', 'type': 'string', 'contextValue': 'value'} ] } ], { onSuccess: function (data, partial_errors) { } } );
-
v1.cancelAvailabilitySubscription(subId [, callbacks])
-
Cancels an existing context availability subscription.
Parameters:
Name Type Description subId
String id of the subscription to cancel
[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
-
v1.cancelSubscription(subId [, options])
-
Cancels a context subscription
Parameters:
Name Type Description subId
String id of the context subscription to cancel
[ options
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.cancelSubscription('sub1', { onSuccess: function (data) { // Subscription canceled successfully // data.subscriptionId should be equal to 'sub1' } } );
-
v1.createAvailabilitySubscription(entities, attributeNames, duration, restriction [, options])
-
Creates a subscription about context availability.
Parameters:
Name Type Description entities
Array the list of Entities that are going to be queried
attributeNames
Array list of attribute names to query. Use
null
for retrieving all the attributesduration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
restriction
Object [ options
]Object onNotify
: URL of the service or callback function to be used for notifying updates in the context availabilityonSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
-
v1.createRegistration(entities, attributes, duration, providingApplication [, callbacks])
-
Registers context information (entities and attributes) into the NGSI server.
Parameters:
Name Type Description entities
Array the list of entities that are going to be registered
attributes
Array the list of attributes that are going to be assigned to the entities
duration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
providingApplication
String the URI of the application to which this registration will belongs to
[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.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 } } );
-
v1.createSubscription(entities, attributeNames, duration, throttling, cond [, options])
-
Creates a context information subscription.
Parameters:
Name Type Description entities
Array the list of Entities that are going to be queried
attributeNames
Array list of attribute names to query. Use
null
for retrieving all the attributesduration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
throttling
String minimal period of time in seconds which must elapse between two consecutive notifications. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
cond
Array declare the condition or conditions that will trigger notifications.
[ options
]Object onNotify
: URL of the service or callback function to be used for notifying updates in the context availabilityonSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.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 } } );
-
v1.deleteAttributes(toDelete [, callbacks])
-
Deletes attributes form entities. This method also removes entities from the context broker server.
Parameters:
Name Type Description toDelete
Array attributes to remove
[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Examples
connection.v1.deleteAttributes([ { 'entity': {type: 'City', id: 'Madrid'}, 'attributes': { 'name': 'position', 'type': 'coords' } } ], { onSuccess: function (data, partial_errors) { } } );
** connection.v1.deleteAttributes([ { 'entity': {type: 'City', id: 'Madrid'} } ], { onSuccess: function (data, partial_errors) { } } );
-
v1.discoverAvailability(entities, attributeNames [, callbacks])
-
Discovers context information registrations on the NGSI server.
Parameters:
Name Type Description entities
Array the list of Entities that are going to be queried
attributeNames
Array list of attribute names to query. Use
null
for retrieving all the attributes[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.discoverAvailability([ {type: 'Technician', id: 'entity1'}, {type: 'Van', id: '.*', isPattern: true}, ], null, { onSuccess: function (registrations) { ... } } );
-
v1.getAvailableTypes([options])
-
Gets 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).
Parameters:
Name Type Description [ options
]Object details
(Boolean
; default:true
): Request total countlimit
(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 beginningonSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.getAvailableTypes({ onSuccess: function (types, details) { // The types parameter contains the information // about the available types, see next slide for // more info } });
-
v1.getTypeInfo(type, options)
-
Gets 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).
Parameters:
Name Type Description type
String Name of the type to query about
options
Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.getTypeInfo("Room", { onSuccess: function (type_info) { // The type_info parameter contains the information // about the Room type, see next slide for more info } });
-
v1.query(Entities, attributeNames, options)
-
Query for context information. That information is returned using pagination (see supported options), so its very recommended the use of the
details
option.Parameters:
Name Type Description Entities
Array list of Entities to query
attributeNames
Array list of attribute names to query. Use
null
for retrieving all the attributesoptions
Object details
(Boolean
; default:false
): Request total countlimit
(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 beginningonSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.query([ {type: 'Technician', id: '.*', isPattern: true} ], null, { limit: 100, offset: 200, details: true onSuccess: function (data, details) { ... } } );
-
v1.updateAttributes(update [, options])
-
Updates entity attributes
Parameters:
Name Type Description update
Array attribute changes
[ options
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.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) { } } );
-
v1.updateAvailabilitySubscription(subId, entities, attributeNames, duration, restriction [, callbacks])
-
Updates an existing context availability subscription.
Parameters:
Name Type Description subId
String id of the subscription to update
entities
Array the list of Entities that are going to be queried
attributeNames
Array list of attribute names to query. Use
null
for retrieving all the attributesduration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
restriction
Object [ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
-
v1.updateRegistration(regId, entities, attributes, duration, providingApplication [, callbacks])
-
Updates an existing registration.
Parameters:
Name Type Description regId
String id of the registration to update
entities
Array list of entities to update
attributes
Array list of attributes to associate with this registration
duration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
providingApplication
String URL identifing the source of the context information
[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.updateRegistration("167", [ {type: 'Technician', id: 'entity1'} ], [ {name: 'attr1', type: 'string'}, {name: 'attr2'} ], 'PT24H', 'http://app.example.com/' );
-
v1.updateRegistration(regId [, callbacks])
-
Cancels an existing registration by marking it as expired.
Parameters:
Name Type Description regId
String id of the registration to cancelRegistration
[ callbacks
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.cancelRegistration("167", { onSuccess: function () { // Registration cancelled successfully } });
-
v1.updateSubscription(subId, duration, throttling, cond [, options])
-
Updates a context subcription.
Parameters:
Name Type Description subId
String id of the subscription to update
duration
String time interval during which the registration will be active, using as reference the current time. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
throttling
String minimal period of time in seconds which must elapse between two consecutive notifications. String following the format defined at http://books.xmlschemata.org/relaxng/ch19-77073.html.
cond
Object declare the condition or conditions that will trigger notifications. Pass
null
for not modifying current conditions.[ options
]Object onSuccess
: callback called if the request finishes successfullyonFailure
: callback called if the request finishes with errorsonComplete
: callback called regardless of whether the request is successful or not
Example
connection.v1.updateSubscription( 'sub1', 'PT20H', null, null, { onSuccess: function (response_data) { // subscription updated successfully } } );
-
v2.appendEntityAttributes(changes [, options])
-
Updates or appends attributes to an entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object New values for the attributes. Must contain the
id
of the entity to update and may contain thetype
option to avoid ambiguity in case there are several entities with the same entity id.[ options
]Object Object with extra options:
correlator
(String
): transaction idkeyValues
(Boolean
; default:false
): Use flat attributesstrict
(Boolean
; default:false
): Force strict append semanticsservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.appendEntityAttributes({ "id": "Bcn-Welt", "temperature": { "value": 31.5 } }).then( (response) => { // Attributes appended successfully // response.correlator transaction id associated with the server response }, (error) => { // Error appending the attributes to the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.appendEntityAttributes({ "id": "Bcn-Welt", "temperature": 31.5 }, { strict: true, keyValues: true }).then( (response) => { // Attributes appended successfully // response.correlator transaction id associated with the server response }, (error) => { // Error appending the attributes to the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.batchQuery(query [, options])
-
This operation allows to make several entity queries at once.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description query
Object Object with the parameters to make the entity queries. Composed of those attributes:
entities
(Array
): a list of entites to search for. Each element is represented by a JSON object with the following elements:id
oridPattern
: Id or pattern of the affected entities. Both cannot be used at the same time, but one of them must be present.type
ortypePattern
: Type or type pattern of the entities total search for. Both cannot be used at the same time. If omitted, it means "any entity type"
attributes
(Array
): a list of attribute names to search for. If omitted, it means "all attributes".metadata
(Array
): a list of metadata names to include in the response. See "Filtering out attributes and metadata" section for more detail.
[ options
]Object Object with extra options:
correlator
(String
): Transaction idcount
(Boolean
; default:false
): Request total countlimit
(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 beginningorderBy
(String
): Criteria for ordering resultsservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationunique
(Boolean
): Represent entities as an array of non-repeated attribute values.values
(Boolean
): Represent entities as an array of attribute values
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.batchQuery({ "entities": [ { "idPattern": ".*", "type": "myFooType" }, { "id": "myBar", "type": "myBarType" } ], "attributes": [ "temperature", "humidity" ] }).then( (response) => { // Entities retrieved successfully // response.correlator transaction id associated with the server response // response.limit contains the used page size // response.results is an array with the retrieved entities // response.offset contains the offset used in the request }, (error) => { // Error retrieving entities // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.batchUpdate(changes [, options])
-
This operation allows to create, update and/or delete several entities in a single batch operation.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object [ options
]Object Object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.batchUpdate({ "actionType": "APPEND", "entities": [ { "type": "Room", "id": "Bcn-Welt", "temperature": { "value": 21.7 }, "humidity": { "value": 60 } }, { "type": "Room", "id": "Mad_Aud", "temperature": { "value": 22.9 }, "humidity": { "value": 85 } } ] }).then( (response) => { // Attributes appended successfully // response.correlator transaction id associated with the server response }, (error) => { // Error appending attributes to the entities // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.createEntity(entity [, options])
-
Creates a new entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description entity
Object values to be used for creating the new entity. Requires at least the
id
value for the new entity.[ options
]Object Object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationupsert
(Boolean
; default:false
): Iftrue
, entity is updated if already exits. Ifupsert
isfalse
this operation will fail if the entity already exists.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.createEntity({ "id": "Spain-Road-A62", "type": "Road", "name": {"value": "A-62"}, "alternateName": {"value": "E-80"}, "description": {"value": "Autovía de Castilla"}, "roadClass": {"value": "motorway"}, "length": {"value": 355}, "refRoadSegment": { "value": [ "Spain-RoadSegment-A62-0-355-forwards", "Spain-RoadSegment-A62-0-355-backwards" ] }, "responsible": {"value": "Ministerio de Fomento - Gobierno de España"} }).then( (response) => { // Entity created successfully // response.correlator transaction id associated with the server response }, (error) => { // Error creating the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.createEntity({ "id": "Spain-Road-A62", "type": "Road", "name": "A-62", "alternateName": "E-80", "description": "Autovía de Castilla", "roadClass": "motorway", "length": 355, "refRoadSegment": [ "Spain-RoadSegment-A62-0-355-forwards", "Spain-RoadSegment-A62-0-355-backwards" ], "responsible": "Ministerio de Fomento - Gobierno de España" }, {keyValues: true}).then( (response) => { // Entity created successfully // response.correlator transaction id associated with the server response }, (error) => { // Error creating the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.createRegistration(registration [, options])
-
Creates a new registration.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description registration
Object values to be used for creating it
[ options
]Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.3.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.createRegistration({ "description": "One registration to rule them all", "dataProvided": { "entities": [ { "id": "room1", "type": "Room" } ], "attrs": [ "temperature", "humidity" ] }, "provider": { "http": { "url": "http://localhost:1234" }, "legacyForwarding": true, "supportedForwardingMode": "all" } }).then( (response) => { // Registration created successfully // response.correlator transaction id associated with the server response }, (error) => { // Error creating the registration // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.createSubscription(subscription [, options])
-
Creates a new subscription.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description subscription
Object values to be used for creating it
[ options
]Object Object with extra options:
skipInitialNotification
(Boolean
; Default:false
): Skip Initial Context Broker notificationcorrelator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.createSubscription({ "description": "One subscription to rule them all", "subject": { "entities": [ { "idPattern": ".*", "type": "Room" } ], "condition": { "attrs": [ "temperature" ], "expression": { "q": "temperature>40" } } }, "notification": { "http": { "url": "http://localhost:1234" }, "attrs": [ "temperature", "humidity" ] }, "expires": "2016-04-05T14:00:00.00Z", "throttling": 5 }).then( (response) => { // Subscription created successfully // response.correlator transaction id associated with the server response }, (error) => { // Error creating the subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.createSubscription({ "description": "One subscription to rule them all", "subject": { "entities": [ { "idPattern": ".*", "type": "Room" } ], "condition": { "attrs": [ "temperature" ], "expression": { "q": "temperature>40" } } }, "notification": { "callback": function (notification, headers, error) { // notification.attrsformat provides information about the format used by notification.data // notification.data contains the modified entities // notification.subscriptionId provides the associated subscription id // etc... // In case of disconnection from the ngsi-proxy, this method // will be called with error = true and notification and // header being null }, "attrs": [ "temperature", "humidity" ] }, "expires": "2016-04-05T14:00:00.00Z", "throttling": 5 }).then( (response) => { // Subscription created successfully // response.correlator transaction id associated with the server response }, (error) => { // Error creating the subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.deleteEntity(options)
-
Removes an entity from the orion context broker server.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object String with the entity id to remove or an object providing options:
correlator
(String
): Transaction idid
(String
, required): Id of the entity to removeservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.deleteEntity("Spain-Road-A62").then( (response) => { // Entity deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.deleteEntity({ id: "Spain-Road-A62", type: "Road" }).then( (response) => { // Entity deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.deleteEntityAttribute(options)
-
Removes a single attribute from an entity stored in the orion context broker server.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
Object Object providing information about the attribute to remove and any extra options:
attribute
(String
, required): Name of the attribute to deletecorrelator
(String
): Transaction idid
(String
, required): Id of the entity to modifyservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.deleteEntityAttribute({ id: "Bcn_Welt", attribute: "temperature" }).then( (response) => { // Entity attribute deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.deleteEntityAttribute({ id: "Bcn_Welt", type: "Room", attribute: "temperature" }).then( (response) => { // Entity attribute deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.deleteRegistration(options)
-
Removes a registration from the orion context broker server.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object String with the id of the registration to remove or an object with options:
correlator
(String
): Transaction idid
(String
): Id of the registration to removeservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.3.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.deleteRegistration("57f7787a5f817988e4eb3dda").then( (response) => { // Registration deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting registration // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.deleteSubscription(options)
-
Removes a subscription from the orion context broker server.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object String with the id of the subscription to remove or an object with options:
correlator
(String
): Transaction idid
(String
): Id of the subscription to removeservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.deleteSubscription("57f7787a5f817988e4eb3dda").then( (response) => { // Subscription deleted successfully // response.correlator transaction id associated with the server response }, (error) => { // Error deleting subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getEntity(options)
-
Gets all the details of an entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object String with the id of the entity to query or an object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesid
(String
, required): Id of the entity to queryservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.getEntity("Spain-Road-A62").then( (response) => { // Entity details retrieved successfully // response.entity entity details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.getEntity({ id: "Spain-Road-A62", type: "Road", keyValues: true }).then( (response) => { // Entity details retrieved successfully // response.entity entity details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getEntityAttribute(options)
-
Gets the details about an entity attribute.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
Object Object with options:
attribute
(String
, required): Name of the attribute to querycorrelator
(String
): Transaction idid
(String
, required): Id of the entity to queryservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.getEntityAttribute({ id: "Bcn_Welt", attribute: "temperature" }).then( (response) => { // Entity details retrieved successfully // response.attribute attribute details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.getEntityAttribute({ id: "Bcn_Welt", type: "Room", attribute: "temperature" }).then( (response) => { // Entity details retrieved successfully // response.attribute attribute details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getEntityAttributes(options)
-
Gets all the attributes of an entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object String with the id of the entity to query or an object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesid
(String
, required): Id of the entity to queryservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.getEntityAttributes("Spain-Road-A62").then( (response) => { // Entity attributes retrieved successfully // response.attributes entity attributes // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.getEntityAttributes({ id: "Spain-Road-A62", type: "Road", keyValues: true }).then( (response) => { // Entity attributes retrieved successfully // response.attributes entity attributes // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getEntityAttributeValue(options)
-
Gets the value of an entity attribute.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
Object Object with extra options:
attribute
(String
, required): Name of the attribute to querycorrelator
(String
): Transaction idid
(String
, required): Id of the entity to queryservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.getEntityAttributeValue({ id: "Bcn_Welt", attribute: "temperature" }).then( (response) => { // Entity value retrieved successfully // response.value entity value // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving attribute value // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.getEntityAttributeValue({ id: "Bcn_Welt", type: "Room", attribute: "temperature" }).then( (response) => { // Entity value retrieved successfully // response.value entity value // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving attribute value // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getRegistration(options)
-
Gets all the details of a registration.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.3.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.getRegistration("abcdef").then( (response) => { // Registration details retrieved successfully // response.registration registration details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving registration // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getSubscription(options)
-
Gets all the details of a subscription.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.getSubscription("abcdef").then( (response) => { // Subscription details retrieved successfully // response.subscription subscription details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.getType(options)
-
Gets all the details about an entity type.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
String | Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Example
connection.v2.getType("Room").then( (response) => { // Type details retrieved successfully // response.type type details // response.correlator transaction id associated with the server response }, (error) => { // Error retrieving type // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.listEntities([options])
-
Retrieves the available entities using pagination.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description [ options
]Object Object with extra options:
attrs
(String
): Comma-separated list of attribute names whose data are to be included in the response. The attributes are retrieved in the order specified by this parameter. If this parameter is not included, the attributes are retrieved in arbitrary order.correlator
(String
): Transaction idcount
(Boolean
; default:false
): Request total countid
(String
): A comma-separated list of entity ids to retrieve. Incompatible with theidPattern
option.idPattern
(String
): A correctly formated regular expression. Retrieve entities whose ID matches the regular expression. Incompatible with theid
optionlimit
(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 beginningmetadata
(String
): A comma-separated list of metadata names to include in the responsemq
(String
): A query expression for attribute metadata, composed of a list of statements separated by semicolons (;
)orderBy
(String
): Criteria for ordering resultsq
(String
): A query expression, composed of a list of statements separated by semicolons (;
)georel
(String
): Spatial relationship between matching entities and a reference shape. See "Geographical Queries" section in NGSIv2 specification for details.geometry
(String
): Geographical area to which the query is restricted. See "Geographical Queries" section in NGSIv2 specification for details.coords
(String
): List of latitude-longitude pairs of coordinates separated by ';'. See "Geographical Queries" section in NGSIv2 specification for details.service
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): A comma-separated list of entity types to retrieve. Incompatible with thetypePattern
option.typePattern
(String
): A correctly formated regular expression. Retrieve entities whose type matches the regular expression. Incompatible with thetype
option.unique
(Boolean
): Represent entities as an array of non-repeated attribute values.values
(Boolean
): Represent entities as an array of attribute values
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.listEntities().then( (response) => { // Entities retrieved successfully // response.correlator transaction id associated with the server response // response.limit contains the used page size // response.results is an array with the retrieved entities // response.offset contains the offset used in the request }, (error) => { // Error retrieving entities // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.listEntities({offset: 20, count: true}).then( (response) => { // Entities retrieved successfully // response.results is an array with the retrieved entities // response.correlator transaction id associated with the server response // response.count contains the total number of entities selected // by this query // response.offset contains the offset used in the request }, (error) => { // Error retrieving entities // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.listRegistrations([options])
-
Retrieves the available registrations (using pagination).
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description [ options
]Object Object with extra options:
correlator
(String
): Transaction idcount
(Boolean
; default:false
): request total countlimit
(Number
; default:20
): This option allow you to specify the maximum number of registrations you want to receive from the serveroffset
(Number
; default:0
): Allows you to skip a given number of elements at the beginningservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.3.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.listRegistrations().then( (response) => { // Registrations retrieved successfully // response.results is an array with the retrieved registrations }, (error) => { // Error retrieving registrations // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.listRegistrations({offset: 20, count: true}).then( (response) => { // Registrations retrieved successfully // response.correlator transaction id associated with the server response // response.limit contains the used page size // response.results is an array with the retrieved registrations // response.count contains the number of available registrations // response.offset contains the offset used in the request }, (error) => { // Error retrieving registrations // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.listSubscriptions([options])
-
Retrieves the available subscriptions (using pagination).
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description [ options
]Object Object with extra options:
correlator
(String
): Transaction idcount
(Boolean
; default:false
): request total countlimit
(Number
; default:20
): This option allow you to specify the maximum number of subscriptions you want to receive from the serveroffset
(Number
; default:0
): Allows you to skip a given number of elements at the beginningservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.listSubscriptions().then( (response) => { // Subscriptions retrieved successfully // response.results is an array with the retrieved subscriptions }, (error) => { // Error retrieving subscriptions // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.listSubscriptions({offset: 20, details: true}).then( (response) => { // Subscriptions retrieved successfully // response.correlator transaction id associated with the server response // response.limit contains the used page size // response.results is an array with the retrieved subscriptions // response.count contains the number of available subscriptions // response.offset contains the offset used in the request }, (error) => { // Error retrieving subscriptions // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.listTypes([options])
-
Retrieves the available types (using pagination).
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description [ options
]Object Object with extra options:
correlator
(String
): Transaction idcount
(Boolean
; default:false
): request total countlimit
(Number
; default:20
): This option allow you to specify the maximum number of subscriptions you want to receive from the serveroffset
(Number
; default:0
): Allows you to skip a given number of elements at the beginningservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.listTypes().then( (response) => { // Types retrieved successfully // response.results is an array with the retrieved subscriptions }, (error) => { // Error retrieving available types // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.listTypes({offset: 20, count: true}).then( (response) => { // Types retrieved successfully // response.correlator transaction id associated with the server response // response.limit contains the used page size // response.results is an array with the retrieved subscriptions // response.count contains the number of available subscriptions // response.offset contains the offset used in the request }, (error) => { // Error retrieving available types // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.replaceEntityAttribute(changes [, options])
-
Update the details about an entity attribute.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object Object with the new values for the attribute. Can also be used for providing options. See the
options
parameter.[ options
]Object Object with options (those options can also be passed inside the changes parameter):
attribute
(String
, required): Name of the attribute to modifycorrelator
(String
): Transaction idid
(String
, required): Id of the entity to modifyservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationtype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.replaceEntityAttribute({ id: "Bcn_Welt", attribute: "temperature" value: 25, metadata: { "unitCode": { "value": "CEL" } } }).then( (response) => { // Entity attribute replaced successfully // response.attribute attribute details // response.correlator transaction id associated with the server response }, (error) => { // Error replacing entity attribute // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id // Entity details retrieved successfully } );
connection.v2.getEntityAttribute({ id: "Bcn_Welt", attribute: "temperature" }).then((response) => { var changes = response.attribute; changes.metadata.unitCode = { "value": "FAR" }; return connection.v2.replaceEntityAttribute(changes, { id: "Bcn_Welt", attribute: "temperature" }); }).then( (response) => { // Entity attribute replaced successfully // response.attribute attribute details // response.correlator transaction id associated with the server response }, (error) => { // Error replacing entity attribute // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.replaceEntityAttributes(entity [, options])
-
Replaces all the attributes associated with a entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description entity
Object New values for the attributes. Must contain the
id
of the entity to update and may contain thetype
option to avoid ambiguity in case there are several entities with the same entity id.[ options
]Object Object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.replaceEntityAttributes({ "id": "Spain-Road-A62", "type": "Road", "name": {"value": "A-62"}, "alternateName": {"value": "E-80"}, "description": {"value": "Autovía de Castilla"}, "roadClass": {"value": "motorway"}, "length": {"value": 355}, "refRoadSegment": { "value": [ "Spain-RoadSegment-A62-0-355-forwards", "Spain-RoadSegment-A62-0-355-backwards" ] }, "responsible": {"value": "Ministerio de Fomento - Gobierno de España"} }).then( (response) => { // Entity attributes replaced successfully // response.correlator transaction id associated with the server response }, (error) => { // Error replacing the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.replaceEntityAttributes({ "id": "Spain-Road-A62", "type": "Road", "name": "A-62", "alternateName": "E-80", "description": "Autovía de Castilla", "roadClass": "motorway", "length": 355, "refRoadSegment": [ "Spain-RoadSegment-A62-0-355-forwards", "Spain-RoadSegment-A62-0-355-backwards" ], "responsible": "Ministerio de Fomento - Gobierno de España" }, {keyValues: true}).then( (response) => { // Entity attributes replaced successfully // response.correlator transaction id associated with the server response }, (error) => { // Error replacing the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.replaceEntityAttributeValue(options)
-
Updates the value of an entity attribute.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description options
Object Object with options:
attribute
(String
, required): Name of the attribute to querycorrelator
(String
): Transaction idid
(String
, required): Id of the entity to queryservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operationvalue
(String
|Boolean
|Number
|Object
|Array
, required) new valuetype
(String
): Entity type, to avoid ambiguity in case there are several entities with the same entity id.
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.replaceEntityAttributeValue({ id: "Bcn_Welt", attribute: "temperature", value: 21 }).then( (response) => { // Entity value replaced successfully // response.value entity value // response.correlator transaction id associated with the server response }, (error) => { // Error replacing attribute value // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.replaceEntityAttributeValue({ id: "Bcn_Welt", type: "Room", attribute: "temperature", value: 21 }).then( (response) => { // Entity value replaced successfully // response.value entity value // response.correlator transaction id associated with the server response }, (error) => { // Error replacing attribute value // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.updateEntityAttributes(changes [, options])
-
Updates attributes of an entity.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object New values for the attributes. Must contain the
id
of the entity to update and may contain thetype
option to avoid ambiguity in case there are several entities with the same entity id.[ options
]Object Object with extra options:
correlator
(String
): Transaction idkeyValues
(Boolean
; default:false
): Use flat attributesservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.updateEntityAttributes({ "id": "sensor", "temperature": { "value": 31.5 }, "humidity": { "value": 50.2 } }).then( (response) => { // Attributes updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.updateEntityAttributes({ "id": "sensor", "temperature": 31.5 "humidity": 50.2 }, { keyValues: true }).then( (response) => { // Attributes updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating the attributes of the entity // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
-
v2.updateRegistration(changes [, options])
-
Updates a registration.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object [ options
]Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.3.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.updateRegistration({ "id": "abcdef", "description": "Context Source" }).then( (response) => { // Registration updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating registration // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.updateRegistration({ "id": "abcdef", "description": "Context Source" }, { servicepath: "/Spain/Madrid" }).then( (response) => { // Registration updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating registration // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } ); Note: PATCH /v2/registration/<id> is not implemented in FIWARE Orion 2.3 See https://fiware-orion.readthedocs.io/en/master/user/ngsiv2_implementation_notes/index.html#registrations, https://github.com/telefonicaid/fiware-orion/issues/3007
-
v2.updateSubscription(changes [, options])
-
Updates a subscription.
This method uses v2 of the FIWARE's NGSI Specification
Parameters:
Name Type Description changes
Object [ options
]Object Object with extra options:
correlator
(String
): Transaction idservice
(String
): Service/tenant to use in this operationservicepath
(String
): Service path to use in this operation
- Since:
-
- 1.0
Throws:
Returns:
- Type
- Promise
Examples
connection.v2.updateSubscription({ "id": "abcdef", "expires": "2016-04-05T14:00:00.00Z" }).then( (response) => { // Subscription updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );
connection.v2.updateSubscription({ "id": "abcdef", "expires": "2016-04-05T14:00:00.00Z" }, { servicepath: "/Spain/Madrid" }).then( (response) => { // Subscription updated successfully // response.correlator transaction id associated with the server response }, (error) => { // Error updating subscription // If the error was reported by Orion, error.correlator will be // filled with the associated transaction id } );