filip.clients.ngsi_v2 package

HTTP clients for FIWARE’s NGSIv2 APIs

Submodules

filip.clients.ngsi_v2.cb module

Context Broker Module for API Client

class filip.clients.ngsi_v2.cb.ContextBrokerClient(url: str | None = None, *, session: Session | None = None, fiware_header: FiwareHeader | None = None, **kwargs)[source]

Bases: BaseHttpClient

Implementation of NGSI Context Broker functionalities, such as creating entities and subscriptions; retrieving, updating and deleting data. Further documentation: https://fiware-orion.readthedocs.io/en/master/

Api specifications for v2 are located here: https://telefonicaid.github.io/fiware-orion/api/v2/stable/

Note

We use the reference implementation for development. Therefore, some other brokers may show slightly different behavior!

delete_entities(entities: List[ContextEntity]) → None[source]

Remove a list of entities from the context broker. This methode is more efficient than to call delete_entity() for each entity

Parameters:: entities – List[ContextEntity]: List of entities to be deleted
Raises:: Exception, if one of the entities is not in the ContextBroker –
Returns:: None

delete_entity(entity_id: str, entity_type: str = None, delete_devices: bool = False, iota_client: IoTAClient = None, iota_url: AnyHttpUrl = Url('http://134.130.166.184:4041/')) → None[source]

Remove a entity from the context broker. No payload is required or received.

Parameters:

entity_id – Id of the entity to be deleted
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
delete_devices – If True, also delete all devices that reference this entity (entity_id as entity_name)
iota_client – Corresponding IoTA-Client used to access IoTA-Agent
iota_url – URL of the corresponding IoT-Agent. This will autogenerate an IoTA-Client, mirroring the information of the ContextBrokerClient, e.g. FiwareHeader, and other headers

Returns:

None

delete_entity_attribute(entity_id: str, attr_name: str, entity_type: str | None = None) → None[source]

Removes a specified attribute from an entity.

Parameters:

entity_id – Id of the entity.
attr_name – Name of the attribute to be retrieved.
entity_type – Entity type, to avoid ambiguity in case there are
id. (several entities with the same entity) –

Raises:

Error –

delete_registration(registration_id: str) → None[source]: Deletes a subscription from a Context Broker :param registration_id: id of the subscription

delete_subscription(subscription_id: str) → None[source]: Deletes a subscription from a Context Broker :param subscription_id: id of the subscription

does_entity_exist(entity_id: str, entity_type: str) → bool[source]

Test if an entity with given id and type is present in the CB

Parameters:

entity_id – Entity id
entity_type – Entity type

Returns:

bool; True if entity exists

Raises:

RequestException, if any error occurs (e.g – No Connection),
except that the entity is not found –

get_attribute(entity_id: str, attr_name: str, entity_type: str | None = None, metadata: str | None = None, response_format='') → ContextAttribute[source]

Retrieves a specified attribute from an entity.

Parameters:

entity_id – Id of the entity. Example: Bcn_Welt
attr_name – Name of the attribute to be retrieved.
entity_type (Optional) – Type of the entity to retrieve
metadata (Optional) – A list of metadata names to include in the response. See “Filtering out attributes and metadata” section for more detail.

Returns:

The content of the retrieved attribute as ContextAttribute

Raises:

Error –

get_attribute_value(entity_id: str, attr_name: str, entity_type: str | None = None) → Any[source]

This operation returns the value property with the value of the attribute.

Parameters:

entity_id – Id of the entity. Example: Bcn_Welt
attr_name – Name of the attribute to be retrieved. Example: temperature.
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.

Returns:

This operation must return one entity element only, but there may be more than one entity with the same ID (e.g. entities with same ID but different types). In such case, an error message is returned, with the HTTP status code set to 409 Conflict.

Parameters:

entity_id (String) – Id of the entity to be retrieved
entity_type (String) – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
attrs (List of Strings) – List of attribute names whose data must be included in the response. The attributes are retrieved in the order specified by this parameter. See “Filtering out attributes and metadata” section for more detail. If this parameter is not included, the attributes are retrieved in arbitrary order, and all the attributes of the entity are included in the response. Example: temperature, humidity.
metadata (List of Strings) – A list of metadata names to include in the response. See “Filtering out attributes and metadata” section for more detail. Example: accuracy.
response_format (AttrsFormat, str) – Representation format of response

Returns:

ContextEntity

get_entity_attributes(entity_id: str, entity_type: str | None = None, attrs: List[str] | None = None, metadata: List[str] | None = None, response_format: AttrsFormat | str = AttrsFormat.NORMALIZED) → Dict[str, ContextAttribute][source]

This request is similar to retrieving the whole entity, however this one omits the id and type fields. Just like the general request of getting an entire entity, this operation must return only one entity element. If more than one entity with the same ID is found (e.g. entities with same ID but different type), an error message is returned, with the HTTP status code set to 409 Conflict.

Parameters:

entity_id (String) – Id of the entity to be retrieved
entity_type (String) – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
attrs (List of Strings) – List of attribute names whose data must be included in the response. The attributes are retrieved in the order specified by this parameter. See “Filtering out attributes and metadata” section for more detail. If this parameter is not included, the attributes are retrieved in arbitrary order, and all the attributes of the entity are included in the response. Example: temperature, humidity.
metadata (List of Strings) – A list of metadata names to include in the response. See “Filtering out attributes and metadata” section for more detail. Example: accuracy.
response_format (AttrsFormat, str) – Representation format of response

Returns:

Dict

Retrieves a list of context entities that match different criteria by id, type, pattern matching (either id or type) and/or those which match a query or geographical query (see Simple Query Language and Geographical Queries). A given entity has to match all the criteria to be retrieved (i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible (i.e. mutually exclusive) with their corresponding exact matching parameters, i.e. idPattern with id and typePattern with type.

Parameters:

entity_ids – A comma-separated list of elements. Retrieve entities whose ID matches one of the elements in the list. Incompatible with idPattern,e.g. Boe_Idarium
entity_types – comma-separated list of elements. Retrieve entities whose type matches one of the elements in the list. Incompatible with typePattern. Example: Room.
id_pattern – A correctly formatted regular expression. Retrieve entities whose ID matches the regular expression. Incompatible with id, e.g. ngsi-ld.* or sensor.*
type_pattern – A correctly formatted regular expression. Retrieve entities whose type matches the regular expression. Incompatible with type, e.g. room.*
q (SimpleQuery) – A query expression, composed of a list of statements separated by ;, i.e., q=statement1;statement2;statement3. See Simple Query Language specification. Example: temperature>40.
mq (SimpleQuery) – A query expression for attribute metadata, composed of a list of statements separated by ;, i.e., mq=statement1;statement2;statement3. See Simple Query Language specification. Example: temperature.accuracy<0.9.
georel – Spatial relationship between matching entities and a reference shape. See Geographical Queries. Example: ‘near’.
geometry – Geographical area to which the query is restricted. See Geographical Queries. Example: point.
coords – List of latitude-longitude pairs of coordinates separated by ‘;’. See Geographical Queries. Example: 41.390205, 2.154007;48.8566,2.3522.
limit – Limits the number of entities to be retrieved Example: 20
attrs – 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. See “Filtering out attributes and metadata” section for more detail. Example: seatNumber.
metadata – A list of metadata names to include in the response. See “Filtering out attributes and metadata” section for more detail. Example: accuracy.
order_by – Criteria for ordering results. See “Ordering Results” section for details. Example: temperature,!speed.
response_format (AttrsFormat, str) – Response Format. Note: That if ‘keyValues’ or ‘values’ are used the response model will change to List[ContextEntityKeyValues] and to List[Dict[str, Any]], respectively.

Returns:

get_entity_type(entity_type: str) → Dict[str, Any][source]

Parameters:: entity_type – Entity Type. Example: Room

Returns:

get_entity_types(*, limit: int | None = None, offset: int | None = None, options: str | None = None) → List[Dict[str, Any]][source]

Parameters:

limit – Limit the number of types to be retrieved.
offset – Skip a number of records.
options – Options dictionary. Allowed: count, values

Returns:

get_registration(registration_id: str) → Registration[source]

Retrieves a registration from context broker by id

Parameters:: registration_id – id of the registration
Returns:: Registration

get_registration_list(*, limit: int | None = None) → List[Registration][source]

Lists all the context provider registrations present in the system.

Parameters:: limit – Limit the number of registrations to be retrieved

Returns:

get_resources() → Dict[source]

Gets reo

Returns:: Dict

get_statistics() → Dict[source]: Gets statistics of context broker :returns: Dictionary with response

get_subscription(subscription_id: str) → Subscription[source]

Retrieves a subscription from :param subscription_id: id of the subscription

Returns:

get_subscription_list(limit: int = inf) → List[Subscription][source]

Returns a list of all the subscriptions present in the system. :param limit: Limit the number of subscriptions to be retrieved

Returns:: list of subscriptions

get_version() → Dict[source]: Gets version of IoT Agent :returns: Dictionary with response

notify(message: Message) → None[source]

This operation is intended to consume a notification payload so that all the entity data included by such notification is persisted, overwriting if necessary. This operation is useful when one NGSIv2 endpoint is subscribed to another NGSIv2 endpoint (federation scenarios). The request payload must be an NGSIv2 notification payload. The behaviour must be exactly the same as ‘update’ with ‘action_type’ equal to append.

Parameters:: message – Notification message
Returns:: None

override_entity(entity: ContextEntity | ContextEntityKeyValues, **kwargs)[source]

The request payload is an object representing the attributes to override the existing entity.

Note

If you want to manipulate you should rather use patch_entity.

Parameters:: entity (ContextEntity or ContextEntityKeyValues) –
Returns:: None

patch_entity(entity: ContextEntity, old_entity: ContextEntity | None = None, override_attr_metadata: bool = True) → None[source]

Takes a given entity and updates the state in the CB to match it. It is an extended equivalent to the HTTP method PATCH, which applies partial modifications to a resource.

Parameters:

entity – Entity to update
old_entity – OPTIONAL, if given only the differences between the old_entity and entity are updated in the CB. Other changes made to the entity in CB, can be kept. If type or id was changed, the old_entity will be deleted.
override_attr_metadata – Whether to override or append the attributes metadata. True for overwrite or False for update/append

Returns:

None

post_command(*, entity_id: str, command: Command | NamedCommand | Dict, entity_type: str | None = None, command_name: str | None = None) → None[source]

Post a command to a context entity this corresponds to ‘PATCH’ of the specified command attribute.

Parameters:

entity_id – Entity identifier
command – Command
entity_type – Entity type
command_name – Name of the command in the entity

Returns:

None

post_entity(entity: ContextEntity | ContextEntityKeyValues, update: bool = False, patch: bool = False, override_attr_metadata: bool = True, key_values: bool = False)[source]

Function registers an Object with the NGSI Context Broker, if it already exists it can be automatically updated (overwritten) if the update bool is True. First a post request with the entity is tried, if the response code is 422 the entity is uncrossable, as it already exists there are two options, either overwrite it, if the attribute have changed (e.g. at least one new/new values) (update = True) or leave it the way it is (update=False) If you only want to manipulate the entities values, you need to set patch argument.

Parameters:

entity (ContextEntity/ContextEntityKeyValues) – Context Entity Object
update (bool) – If the response.status_code is 422, whether the override and existing entity
patch (bool) – If the response.status_code is 422, whether to manipulate the existing entity. Omitted if update True.
override_attr_metadata – Only applies for patch equal to True. Whether to override or append the attribute’s metadata. True for overwrite or False for update/append
key_values (bool) – By default False. If set to True, “options=keyValues” will be included in params of post request. The payload uses the keyValues simplified entity representation, i.e. ContextEntityKeyValues.

post_registration(registration: Registration)[source]

Creates a new context provider registration. This is typically used for binding context sources as providers of certain data. The registration is represented by cb.models.Registration

Parameters:: registration (Registration) –

Returns:

post_subscription(subscription: Subscription, update: bool = False, skip_initial_notification: bool = False) → str[source]

Creates a new subscription. The subscription is represented by a Subscription object defined in filip.cb.models.

If the subscription already exists, the adding is prevented and the id of the existing subscription is returned.

A subscription is deemed as already existing if there exists a subscription with the exact same subject and notification fields. All optional fields are not considered.

Parameters:

subscription – Subscription
update – True - If the subscription already exists, update it False- If the subscription already exists, throw warning
skip_initial_notification – True - Initial Notifications will be sent to recipient containing the whole data. This is deprecated and removed from version 3.0 of the context broker. False - skip the initial notification

Returns:

Id of the (created) subscription

Return type:

str

query(*, query: Query, limit: int | None = None, order_by: str | None = None, response_format: AttrsFormat | str = AttrsFormat.NORMALIZED) → List[Any][source]

Generate api query :param query: :type query: Query :param limit: :type limit: PositiveInt :param order_by: :type order_by: str :param response_format: :type response_format: AttrsFormat, str

Returns:: The response payload is an Array containing one object per matching entity, or an empty array [] if no entities are found. The entities follow the JSON entity representation format (described in the section “JSON Entity Representation”).

replace_entity_attributes(entity_id: str, attrs: List[NamedContextAttribute | Dict[str, ContextAttribute]] | Dict, entity_type: str | None = None, forcedUpdate: bool = False, key_values: bool = False)[source]

The attributes previously existing in the entity are removed and replaced by the ones in the request. This corresponds to a ‘PUT’ request.

Parameters:

entity_id – Entity id to be updated
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
attrs – List of attributes to add to the entity or dict of attributes in case of key_values=True.
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.
key_values (bool) – By default False. If set to True, “options=keyValues” will be included in params of the request. The payload uses the keyValues simplified entity representation, i.e. ContextEntityKeyValues.

Returns:

None

update(*, entities: List[ContextEntity | ContextEntityKeyValues], action_type: ActionType | str, update_format: str | None = None, forcedUpdate: bool = False, override_metadata: bool = False) → None[source]

This operation allows to create, update and/or delete several entities in a single batch operation.

This operation is split in as many individual operations as entities in the entities vector, so the actionType is executed for each one of them. Depending on the actionType, a mapping with regular non-batch operations can be done:

append: maps to POST /v2/entities (if the entity does not already exist) or POST /v2/entities/<id>/attrs (if the entity already exists).

appendStrict: maps to POST /v2/entities (if the entity does not already exist) or POST /v2/entities/<id>/attrs?options=append (if the entity already exists).

update: maps to PATCH /v2/entities/<id>/attrs.

delete: maps to DELETE /v2/entities/<id>/attrs/<attrName> on every: attribute included in the entity or to DELETE /v2/entities/<id> if no attribute were included in the entity.

replace: maps to PUT /v2/entities/<id>/attrs.

Parameters:

entities – “an array of entities, each entity specified using the ” “JSON entity representation format “
action_type (Update) – “actionType, to specify the kind of update action to do: either append, appendStrict, update, delete, or replace. “
update_format (str) – Optional ‘keyValues’
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.
override_metadata – Bool, replace the existing metadata with the one provided in the request

Returns:

update_attribute_value(*, entity_id: str, attr_name: str, value: Any, entity_type: str | None = None, forcedUpdate: bool = False)[source]

Updates the value of a specified attribute of an entity

Parameters:

value – update value
entity_id – Id of the entity. Example: Bcn_Welt
attr_name – Name of the attribute to be retrieved. Example: temperature.
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.

Returns:

update_entity(entity: ContextEntity | ContextEntityKeyValues | dict, append_strict: bool = False, key_values: bool = False)[source]

The request payload is an object representing the attributes to append or update.

Note

Update means overwriting the existing entity. If you want to manipulate you should rather use patch_entity.

Parameters:

entity (ContextEntity) –
append_strict – If False the entity attributes are updated (if they previously exist) or appended (if they don’t previously exist) with the ones in the payload. If True all the attributes in the payload not previously existing in the entity are appended. In addition to that, in case some of the attributes in the payload already exist in the entity, an error is returned. More precisely this means a strict append procedure.
key_values – By default False. If set to True, the payload uses the keyValues simplified entity representation, i.e. ContextEntityKeyValues.

Returns:

None

update_entity_attribute(entity_id: str, attr: ContextAttribute | NamedContextAttribute, *, entity_type: str | None = None, attr_name: str | None = None, override_metadata: bool = True, forcedUpdate: bool = False)[source]

Updates a specified attribute from an entity.

Parameters:

attr – context attribute to update
entity_id – Id of the entity. Example: Bcn_Welt
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.
attr_name – Name of the attribute to be updated.
override_metadata – Bool, if set to True (default) the metadata will be overwritten. This is for backwards compatibility reasons. If False the metadata values will be either updated if already existing or append if not. See also: https://fiware-orion.readthedocs.io/en/master/user/metadata.html

update_entity_properties(entity: ContextEntity, append_strict: bool = False)[source]

The request payload is an object representing the attributes, of any type but Relationship, to append or update.

Note

Update means overwriting the existing entity. If you want to manipulate you should rather use patch_entity.

Parameters:

entity (ContextEntity) –
append_strict – If False the entity attributes are updated (if they previously exist) or appended (if they don’t previously exist) with the ones in the payload. If True all the attributes in the payload not previously existing in the entity are appended. In addition to that, in case some of the attributes in the payload already exist in the entity, an error is returned. More precisely this means a strict append procedure.

Returns:

None

update_entity_relationships(entity: ContextEntity, append_strict: bool = False)[source]

The request payload is an object representing only the attributes, of type Relationship, to append or update.

Note

Update means overwriting the existing entity. If you want to manipulate you should rather use patch_entity.

Parameters:

entity (ContextEntity) –
append_strict – If False the entity attributes are updated (if they previously exist) or appended (if they don’t previously exist) with the ones in the payload. If True all the attributes in the payload not previously existing in the entity are appended. In addition to that, in case some of the attributes in the payload already exist in the entity, an error is returned. More precisely this means a strict append procedure.

Returns:

None

update_existing_entity_attributes(entity_id: str, attrs: List[NamedContextAttribute] | Dict[str, ContextAttribute] | Dict[str, Any], entity_type: str | None = None, forcedUpdate: bool = False, override_metadata: bool = False, key_values: bool = False)[source]

The entity attributes are updated with the ones in the payload. In addition to that, if one or more attributes in the payload doesn’t exist in the entity, an error is returned. This corresponds to a ‘PATCH’ request.

Parameters:

entity_id – Entity id to be updated
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
attrs – List of attributes to update or to append
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.
override_metadata – Bool,replace the existing metadata with the one provided in the request
key_values – By default False. If set to True, the payload uses the keyValues simplified entity representation, i.e. ContextEntityKeyValues.

Returns:

None

update_or_append_entity_attributes(entity_id: str, attrs: List[NamedContextAttribute] | Dict[str, ContextAttribute] | Dict[str, Any], entity_type: str | None = None, append_strict: bool = False, forcedUpdate: bool = False, key_values: bool = False)[source]

The request payload is an object representing the attributes to append or update. This corresponds to a ‘POST’ request if append is set to ‘False’

Note

Be careful not to update attributes that are provided via context registration, e.g. commands. Commands are removed before sending the request. To avoid breaking things.

Parameters:

entity_id – Entity id to be updated
entity_type – Entity type, to avoid ambiguity in case there are several entities with the same entity id.
attrs – List of attributes to update or to append
append_strict – If False the entity attributes are updated (if they previously exist) or appended (if they don’t previously exist) with the ones in the payload. If True all the attributes in the payload not previously existing in the entity are appended. In addition to that, in case some of the attributes in the payload already exist in the entity, an error is returned. More precisely this means a strict append procedure.
forcedUpdate – Update operation have to trigger any matching subscription, no matter if there is an actual attribute update or no instead of the default behavior, which is to updated only if attribute is effectively updated.
key_values – By default False. If set to True, the payload uses the keyValues simplified entity representation, i.e. ContextEntityKeyValues.

Returns:

None

update_registration(registration: Registration)[source]

Only the fields included in the request are updated in the registration.

Parameters:: registration – Registration to update

Returns:

update_subscription(subscription: Subscription, skip_initial_notification: bool = False)[source]

Only the fields included in the request are updated in the subscription.

Parameters:

subscription – Subscription to update
skip_initial_notification – True - Initial Notifications will be sent to recipient containing the whole data. This is deprecated and removed from version 3.0 of the context broker. False - skip the initial notification

Returns:

None

filip.clients.ngsi_v2.client module

Module for FIWARE api client

Bases: BaseHttpClient

Master client. This client contains all implemented sub clients based on the principal of composition. Hence, each sub client is accessible from this client, but they share a general config and if provided a session.

property cert: Return session certificate

property config: Return current config

property secrets: Returns secrets

pydantic model filip.clients.ngsi_v2.client.HttpClientConfig[source]

Bases: BaseModel

Config class for http client

Fields:

auth (Dict | None)
cb_url (pydantic_core._pydantic_core.Url | None)
iota_url (pydantic_core._pydantic_core.Url | None)
ql_url (pydantic_core._pydantic_core.Url | None)

field auth: Dict | None = None

field cb_url: Url | None = Url('http://134.130.166.184:1026/')

field iota_url: Url | None = Url('http://134.130.166.184:4041/')

field ql_url: Url | None = Url('http://134.130.166.184:8668/')

filip.clients.ngsi_v2.iota module

IoT-Agent Module for API Client

class filip.clients.ngsi_v2.iota.IoTAClient(url: str | None = None, *, session: Session | None = None, fiware_header: FiwareHeader | None = None, **kwargs)[source]

Bases: BaseHttpClient

Client for FIWARE IoT-Agents. The implementation follows the API specifications from here: https://iotagent-node-lib.readthedocs.io/en/latest/

Parameters:

url – Url of IoT-Agent
session (requests.Session) –
fiware_header (FiwareHeader) – fiware service and fiware service path
**kwargs (Optional) – Optional arguments that request takes.

change_loglevel_of_agent(level: str)[source]

Change current loglevel of agent

Parameters:: level –

Returns:

delete_device(*, device_id: str, cb_url: AnyHttpUrl = Url('http://134.130.166.184:1026/'), delete_entity: bool = False, force_entity_deletion: bool = False, cb_client: ContextBrokerClient = None) → None[source]

Remove a device from the device registry. No payload is required or received.

Parameters:

device_id – str, ID of Device
delete_entity –

False -> Only delete the device entry,
the automatically created and linked context-entity will continue to exist in Fiware

True -> Also delete the automatically
created and linked context-entity If multiple devices are linked to this entity, this operation is not executed and an exception is raised
force_entity_deletion – bool, if delete_entity is true and multiple devices are linked to the linked entity, delete it and do not raise an error
cb_client (ContextBrokerClient) – Corresponding ContextBrokerClient object for entity manipulation
cb_url (AnyHttpUrl) – Url of the ContextBroker where the entity is found. This will autogenerate an CB-Client, mirroring the information of the IoTA-Client, e.g. FiwareHeader, and other headers (not recommended!)

Returns:

None

delete_group(*, resource: str, apikey: str)[source]

Deletes a service group in in the IoT-Agent

Parameters:

resource –
apikey –

Returns:

does_device_exists(device_id: str) → bool[source]

Test if a device with the given id exists in Fiware :param device_id: :type device_id: str

Returns:: bool

get_device(*, device_id: str) → Device[source]

Returns all the information about a particular device.

Parameters:: device_id –
Raises:: requests.RequestException, if device does not exist –
Returns:: Device

Returns a list of all the devices in the device registry with all its data. The IoTAgent now only supports “limit” and “offset” as request parameters.

Parameters:

limit – if present, limits the number of devices returned in the list. Must be a number between 1 and 1000.
offset – if present, skip that number of devices from the original query.
device_ids – List of device_ids. If given, only devices with matching ids will be returned
entity_names – The entity_ids of the devices. If given, only the devices with the specified entity_id will be returned
entity_types – The entity_type of the device. If given, only the devices with the specified entity_type will be returned

Returns:

List of matching devices

get_group(*, resource: str, apikey: str) → ServiceGroup[source]

Retrieves service_group groups from the database based on resource and apikey :param resource: :param apikey:

Returns:

get_group_list() → List[ServiceGroup][source]

Retrieves service_group groups from the database. If the servicepath header has the wildcard expression, /*, all the subservices for the service_group are returned. The specific subservice parameters are returned in any other case.

Returns:

get_loglevel_of_agent()[source]: Get current loglevel of agent Returns:

get_version() → Dict[source]

Gets version of IoT Agent

Returns:: Dictionary with response

patch_device(device: Device, patch_entity: bool = True, cb_client: ContextBrokerClient = None, cb_url: AnyHttpUrl = Url('http://134.130.166.184:1026/')) → None[source]

Updates a device state in Fiware, if the device does not exists it is created, else its values are updated. If the device settings (endpoint,..) were changed the device and entity are deleted and re-added.

If patch_entity is true the corresponding entity in the ContextBroker is also correctly updated. Else only new attributes are added there.

Parameters:

device (Device) – Device to be posted to /updated in Fiware
patch_entity (bool) – If true the corresponding entity is completely synced
cb_client (ContextBrokerClient) – Corresponding ContextBrokerClient object for entity manipulation
cb_url (AnyHttpUrl) – Url of the ContextBroker where the entity is found. This will autogenerate an CB-Client, mirroring the information of the IoTA-Client, e.g. FiwareHeader, and other headers (not recommended!)

Returns:

None

post_device(*, device: Device, update: bool = False) → None[source]

Post a device configuration to the IoT-Agent

Parameters:

device – IoT device configuration to send
update – update device if configuration already exists

Returns:

None

post_devices(*, devices: Device | List[Device], update: bool = False) → None[source]

Post a device from the device registry. No payload is required or received. If a device already exists in can be updated with update = True :param devices: :type devices: list of Devices :param update: Whether if the device is already existent it :type update: bool :param should be updated:

Returns:: None

post_group(service_group: ServiceGroup, update: bool = False)[source]

Single service registration but using the bulk operation in background

Parameters:

service_group (ServiceGroup) – Service that will be posted to the
API (agent's) –
update (bool) –

Returns:

None

post_groups(service_groups: ServiceGroup | List[ServiceGroup], update: bool = False)[source]

Creates a set of service groups for the given service and service_path. The service_group and subservice information will taken from the headers, overwriting any preexisting values.

Parameters:

service_groups (list of ServiceGroup) – Service groups that will be
API (posted to the agent's) –
update (bool) – If service group already exists try to update its

Returns:

None

update_device(*, device: Device, add: bool = True) → None[source]

Updates a device from the device registry. Adds, removes attributes from the device entry and changes attributes values. It does not change device settings (endpoint,..) and only adds attributes to the corresponding entity, their it does not change any attribute value and does not delete removed attributes

Parameters:

device –
add (bool) – If device not found add it

Returns:

None

update_devices(*, devices: Device | List[Device], add: False) → None[source]

Bulk operation for device update. :param devices: :param add:

Returns:

update_group(*, service_group: ServiceGroup, fields: Set[str] | List[str] | None = None, add: bool = True)[source]

Modifies the information for a service group configuration, identified by the resource and apikey query parameters. Takes a service group body as the payload. The body does not have to be complete: for incomplete bodies, just the existing attributes will be updated

Parameters:

service_group (ServiceGroup) – Service to update.
fields – Fields of the service_group to update. If ‘None’ all allowed
updated (fields will be) –
add –

Returns:

None

update_groups(*, service_groups: ServiceGroup | List[ServiceGroup], add: False, fields: Set[str] | List[str] = None) → None[source]

Bulk operation for service group update. :param fields: :param service_groups: :param add:

Returns:

filip.clients.ngsi_v2.quantumleap module

TimeSeries Module for QuantumLeap API Client

class filip.clients.ngsi_v2.quantumleap.QuantumLeapClient(url: str | None = None, *, session: Session | None = None, fiware_header: FiwareHeader | None = None, **kwargs)[source]

Bases: BaseHttpClient

Implements functions to use the FIWARE’s QuantumLeap, which subscribes to an Orion Context Broker and stores the subscription data in a time series database (CrateDB). Further Information: https://smartsdk.github.io/ngsi-timeseries-api/#quantumleap https://app.swaggerhub.com/apis/heikkilv/quantumleap-api/

Parameters:

url – url of the quantumleap service
session (Optional) –
fiware_header –
**kwargs –

delete_entity(entity_id: str, entity_type: str | None = None) → str[source]

Given an entity (with type and id), delete all its historical records.

Parameters:

entity_id (String) – Entity id is required.
entity_type (Optional[String]) – Entity type if entity_id alone can not uniquely define the entity.

Raises:

RequestException, if entity was not found –
Exception, if deleting was not successful –

Returns:

The entity_id of entity that is deleted.

delete_entity_type(entity_type: str) → str[source]

Given an entity type, delete all the historical records of all entities of such type. :param entity_type: Type of entities data to be deleted. :type entity_type: String

Returns:: Entity type of the entities deleted.

Get list of all available entities and their context information about EntityType and last update date.

Parameters:

entity_type (str) – Comma-separated list of entity types whose data are to be included in the response. Use only one (no comma) when required. If used to resolve ambiguity for the given entityId, make sure the given entityId exists for this entityType.
id_pattern (str) – The pattern covering the entity ids for which to subscribe. The pattern follow regular expressions (POSIX Extendede) e.g. “.*”, “Room.*”. Detail information: https://en.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions
from_date (str) – The starting date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34)
to_date (str) – The final date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34).
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.

Returns:

List of TimeSeriesHeader

History of an attribute of a given entity instance For example, query max water level of the central tank throughout the last year. Queries can get more sophisticated with the use of filters and query attributes.

Parameters:

entity_id (String) – Entity id is required.
attr_name (String) – The attribute name is required.
entity_type (String) – Comma-separated list of entity types whose data are to be included in the response.
aggr_method (String) – The function to apply to the raw data filtered. count, sum, avg, min, max
aggr_period (String) – year, month, day, hour, minute, second
from_date (String) – Starting date and time inclusive.
to_date (String) – Final date and time inclusive.
last_n (int) – Request only the last N values.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.
georel (String) – Geographical pattern
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Required if georel is specified. e.g. 40.714,-74.006
options (String) – Key value pair options.

Returns:

Response Model

History of an attribute of N entities of the same type. For example, query the pressure measurements of this month in all the weather stations. Note in the response, the index and values arrays are parallel. Also, when using aggrMethod, the aggregation is done by-entity instance. In this case, the index array is just the fromDate and toDate values user specified in the request (if any).

Parameters:

entity_type (String) – Entity type is required.
attr_name (String) – The attribute name is required.
entity_id (String) – Comma-separated list of entity ids whose data are to be included in the response.
aggr_method (String) – The function to apply to the raw data filtered. count, sum, avg, min, max
aggr_period (String) – year, month, day, hour, minute, second
aggr_scope (str) – Optional. (This parameter is not yet supported). When the query results cover historical data for multiple entities instances, you can define the aggregation method to be applied for each entity instance [entity] or across them [global]
from_date (String) – Starting date and time inclusive.
to_date (String) – Final date and time inclusive.
last_n (int) – Request only the last N values.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.
georel (String) – Geographical pattern
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Required if georel is specified. e.g. 40.714,-74.006
options (String) – Key value pair options.

Returns:

Response Model

History of an attribute (values only) of a given entity instance Similar to the previous, but focusing on the values regardless of the metadata.

Parameters:

entity_id (String) – Entity id is required.
attr_name (String) – The attribute name is required.
entity_type (String) – Comma-separated list of entity types whose data are to be included in the response.
aggr_method (String) – The function to apply to the raw data filtered. count, sum, avg, min, max
aggr_period (String) – year, month, day, hour, minute, second
from_date (String) – Starting date and time inclusive.
to_date (String) – Final date and time inclusive.
last_n (int) – Request only the last N values.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.
georel (String) – Geographical pattern
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Required if georel is specified. e.g. 40.714,-74.006
options (String) – Key value pair options.

Returns:

Response Model

History of an attribute (values only) of N entities of the same type. For example, query the average pressure (values only, no metadata) of this month in all the weather stations.

Parameters:

aggr_scope (String) –
entity_type (String) – Entity type is required.
attr_name (String) – The attribute name is required.
entity_id (String) – Comma-separated list of entity ids whose data are to be included in the response.
aggr_method (String) – The function to apply to the raw data filtered. count, sum, avg, min, max
aggr_period (String) – year, month, day, hour, minute, second
aggr_scope –
from_date (String) – Starting date and time inclusive.
to_date (String) – Final date and time inclusive.
last_n (int) – Request only the last N values.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.
georel (String) – Geographical pattern
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Required if georel is specified. e.g. 40.714,-74.006
options (String) – Key value pair options.

Returns:

Response Model

get_entity_by_attr_name(*, attr_name: str, entity_type: str | None = None, from_date: str | None = None, to_date: str | None = None, limit: int = 10000, offset: int | None = None) → List[TimeSeries][source]

Get list of all entities containing this attribute name, as well as getting the index and values of this attribute in every corresponding entity.

Parameters:

attr_name (str) – The attribute name in interest.
entity_type (str) – Comma-separated list of entity types whose data are to be included in the response. Use only one (no comma) when required. If used to resolve ambiguity for the given entityId, make sure the given entityId exists for this entityType.
from_date (str) – The starting date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34)
to_date (str) – The final date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34).
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.

Returns:

List of TimeSeries

get_entity_by_attrs(*, entity_type: str | None = None, from_date: str | None = None, to_date: str | None = None, limit: int = 10000, offset: int | None = None) → List[TimeSeries][source]

Get list of timeseries data grouped by each existing attribute name. The timeseries data include all entities corresponding to each attribute name as well as the index and values of this attribute in this entity.

Parameters:

entity_type (str) – Comma-separated list of entity types whose data are to be included in the response. Use only one (no comma) when required. If used to resolve ambiguity for the given entityId, make sure the given entityId exists for this entityType.
from_date (str) – The starting date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34)
to_date (str) – The final date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34).
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.

Returns:

List of TimeSeriesEntities

History of N attributes of a given entity instance For example, query max water level of the central tank throughout the last year. Queries can get more sophisticated with the use of filters and query attributes.

Parameters:

entity_id (String) – Entity id is required.
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 not specified, all attributes are included in the response in arbitrary order.
entity_type (String) – Comma-separated list of entity types whose data are to be included in the response.
aggr_method (String) –
The function to apply to the raw data filtered by the query parameters. If not given, the returned data are the same raw inserted data.

Allowed values: count, sum, avg, min, max
aggr_period (String) –
If not defined, the aggregation will apply to all the values contained in the search result. If defined, the aggregation function will instead be applied N times, once for each period, and all those results will be considered for the response. For example, a query asking for the average temperature of an attribute will typically return 1 value. However, with an aggregationPeriod of day, you get the daily average of the temperature instead (more than one value assuming you had measurements across many days within the scope of your search result). aggrPeriod must be accompanied by an aggrMethod, and the aggrMethod will be applied to all the numeric attributes specified in attrs; the rest of the non-numerical attrs will be ignored. By default, the response is grouped by entity_id. See aggrScope to create aggregation across entities:

Allowed values: year, month, day, hour, minute, second
from_date (String) – The starting date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34)
to_date (String) – The final date and time (inclusive) from which the context information is queried. Must be in ISO8601 format (e.g., 2018-01-05T15:44:34)
last_n (int) – Used to request only the last N values that satisfy the request conditions.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset to apply to the response results.
georel (String) – It specifies a spatial relationship between matching entities and a reference shape (geometry). This parameter is used to perform geographical queries with the same semantics as in the FIWARE-NGSI v2 Specification. Full details can be found in the Geographical Queries section of the specification: https://fiware.github.io/specifications/ngsiv2/stable/.
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Optional but required if georel is specified. This parameter defines the reference shape (geometry) in terms of WGS 84 coordinates and has the same semantics as in the FIWARE-NGSI v2 Specification, except we only accept coordinates in decimal degrees—e.g. 40.714,-74.006 is okay, but not 40 42’ 51’’,74 0’ 21’’. Full details can be found in the Geographical Queries section of the specification: https://fiware.github.io/specifications/ngsiv2/stable/.
options (String) – Key value pair options.

Returns:

TimeSeries

get_entity_by_type(entity_type: str, *, attrs: str | None = None, entity_id: str | None = None, id_pattern: str | None = None, aggr_method: str | AggrMethod | None = None, aggr_period: str | AggrPeriod | None = None, from_date: str | None = None, to_date: str | None = None, last_n: int | None = None, limit: int = 10000, offset: int | None = None, georel: str | None = None, geometry: str | None = None, coords: str | None = None, options: str | None = None, aggr_scope: str | AggrScope | None = None) → List[TimeSeries][source]: History of N attributes of N entities of the same type. For example, query the average pressure, temperature and humidity of this month in all the weather stations.

History of N attributes (values only) of a given entity instance For example, query the average pressure, temperature and humidity ( values only, no metadata) of this month in the weather station WS1.

Parameters:

entity_id (String) – Entity id is required.
attrs (String) – Comma-separated list of attribute names
entity_type (String) – Comma-separated list of entity types whose data are to be included in the response.
aggr_method (String) – The function to apply to the raw data filtered. count, sum, avg, min, max
aggr_period (String) – year, month, day, hour, minute, second
from_date (String) – Starting date and time inclusive.
to_date (String) – Final date and time inclusive.
last_n (int) – Request only the last N values.
limit (int) – Maximum number of results to be retrieved. Default value : 10000
offset (int) – Offset for the results.
georel (String) – Geographical pattern
geometry (String) – Required if georel is specified. point, line, polygon, box
coords (String) – Required if georel is specified. e.g. 40.714,-74.006
options (String) – Key value pair options.

Returns:

Response Model

get_entity_values_by_type(entity_type: str, *, attrs: str | None = None, entity_id: str | None = None, id_pattern: str | None = None, aggr_method: str | AggrMethod | None = None, aggr_period: str | AggrPeriod | None = None, from_date: str | None = None, to_date: str | None = None, last_n: int | None = None, limit: int = 10000, offset: int | None = None, georel: str | None = None, geometry: str | None = None, coords: str | None = None, options: str | None = None, aggr_scope: str | AggrScope | None = None) → List[TimeSeries][source]: History of N attributes (values only) of N entities of the same type. For example, query the average pressure, temperature and humidity ( values only, no metadata) of this month in all the weather stations.

get_health() → Dict[source]

This endpoint is intended for administrators of QuantumLeap. Using the information returned by this endpoint they can diagnose problems in the service or its dependencies. This information is also useful for cloud tools such as orchestrators and load balancers with rules based on health-checks. Due to the lack of a standardized response format, we base the implementation on the draft of https://inadarei.github.io/rfc-healthcheck/

Returns:: Dictionary with response

get_version() → Dict[source]

Gets version of QuantumLeap-Service.

Returns:: Dictionary with response

post_config()[source]: (To Be Implemented) Customize your persistence configuration to better suit your needs.

post_notification(notification: Message)[source]

Notify QuantumLeap the arrival of a new NGSI notification.

Parameters:: notification – Notification Message Object

Subscribe QL to process Orion notifications of certain type. This endpoint simplifies the creation of the subscription in orion that will generate the notifications to be consumed by QuantumLeap in order to save historical records. If you want an advanced specification of the notifications, you can always create the subscription in orion at your will. This endpoint just aims to simplify the common use case.

Parameters:

cb_url – url of the context broker
ql_url – The url where Orion can reach QuantumLeap. Do not include specific paths.
entity_type (String) – The type of entities for which to create a subscription, so as to persist historical data of entities of this type.
entity_id (String) – Id of the entity to track. If specified, it takes precedence over the idPattern parameter.
id_pattern (String) – The pattern covering the entity ids for which to subscribe. If not specified, QL will track all entities of the specified type.
attributes (String) – Comma-separated list of attribute names to track.
observed_attributes (String) – Comma-separated list of attribute names to track.
notified_attributes (String) – Comma-separated list of attribute names to be used to restrict the data of which QL will keep a history.
throttling (int) – Minimal period of time in seconds which must elapse between two consecutive notifications.
time_index_attribute (String) – The name of a custom attribute to be used as a
index. (time) –

transform_attr_response_model(attr_response)[source]