filip.clients.ngsi_ld package

This package will contain HTTP clients for FIWARE’s NGSI-LD APIs

Submodules

filip.clients.ngsi_ld.cb module

Context Broker Module for API Client

class filip.clients.ngsi_ld.cb.ContextBrokerLDClient(url: str | None = None, *, session: Session | None = None, fiware_header: FiwareLDHeader | None = None, **kwargs)

Bases: BaseHttpClient

Implementation of NGSI-LD 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 LD are located here: https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.04.01_60/gs_cim009v010401p.pdf

GeometryShape

alias of Literal[‘Point’, ‘MultiPoint’, ‘LineString’, ‘MultiLineString’, ‘Polygon’, ‘MultiPolygon’]

append_entity_attributes(entity: ContextLDEntity, options: str | None = None)

Append new Entity attributes to an existing Entity within an NGSI-LD system :param entity: Entity to append attributes to. :type entity: ContextLDEntity :param options: Options for the request. The only available value is

‘noOverwrite’. If set, it will raise 400, if all attributes exist already.

delete_attribute(entity_id: str, attribute_id: str)

Deletes an attribute from an entity. :param entity_id: ID of the entity. :param attribute_id: Name of the attribute to delete.

Returns:

delete_entity_by_id(entity_id: str, entity_type: str | None = None)

Deletes an entity by its id. For deleting mulitple entities at once, entity_batch_operation() is more efficient. :param entity_id: ID of entity to delete. :param entity_type: Type of entity to delete.

delete_subscription(subscription_id: str) → None

Deletes a subscription from a Context Broker :param subscription_id: id of the subscription

entity_batch_operation(*, entities: List[ContextLDEntity], action_type: ActionTypeLD | str, options: Literal['noOverwrite', 'replace', 'update'] | None = None) → None

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. “

• options (str) – Optional ‘noOverwrite’ ‘replace’ ‘update’

Returns:

get_entity(entity_id: str, entity_type: str | None = None, attrs: List[str] | None = None, options: str | None = None, geometryProperty: str | None = None) → ContextLDEntity | ContextLDEntityKeyValues | Dict[str, Any]

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.

• options (String) – keyValues (simplified representation of entity) or sysAttrs (include generated attrs createdAt and modifiedAt)

• geometryProperty (String) – Name of a GeoProperty. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the “geometry” element. By default, it shall be ‘location’.

Returns:

ContextEntity

get_entity_list(entity_id: str | None = None, id_pattern: str | None = '.*', entity_type: str | None = None, attrs: List[str] | None = None, q: str | None = None, georel: str | None = None, geometry: Literal['Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon'] | None = None, coordinates: str | None = None, geoproperty: str | None = None, limit: int | None = None, options: str | None = None) → List[ContextLDEntity | ContextLDEntityKeyValues]

This operation retrieves a list of entities based on different query options. By default, the operation retrieves all the entities in the context broker. :param entity_id: Id of the entity to be retrieved :param id_pattern: Regular expression to match the entity id :param entity_type: Entity type, to avoid ambiguity in case there are several

entities with the same entity id.

Parameters:

• attrs – List of attribute names whose data must be included in the response.

• q – Query expression, composed of attribute names, operators and values.

• georel – Geospatial relationship between the query geometry and the entities.

• geometry – Type of geometry for the query. The possible values are Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon.

• coordinates – Coordinates of the query geometry. The coordinates must be expressed as a string of comma-separated values.

• geoproperty – Name of a GeoProperty. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the “geometry” element.

• limit – Maximum number of entities to retrieve.

• options –

  Further options for the query. The available options are:

  • keyValues (simplified representation of entity)

  • sysAttrs (including createdAt and modifiedAt, etc.)

  • count (include number of all matched entities in response header)

get_statistics() → Dict

Gets statistics of context broker :returns: Dictionary with response

get_subscription(subscription_id: str) → SubscriptionLD

Retrieves a subscription from the context broker. :param subscription_id: id of the subscription

Returns:

get_subscription_list(limit: int = inf) → List[SubscriptionLD]

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

Gets version of Orion-LD context broker :returns: Dictionary with response

handle_multi_status_response(res: Response)

Handles the response of a batch_operation. If the response contains errors, they are logged. If the response contains only errors, a RuntimeError is raised. :param res:

Returns:

log_multi_errors(errors: List[Dict]) → None

override_entities(entities: List[ContextLDEntity])

Function to create or override existing entites with the NGSI-LD Context Broker. The batch operation with Upsert will be used.

post_entity(entity: ContextLDEntity, append: bool = False, update: bool = False)

Function registers an Object with the NGSI-LD Context Broker, if it already exists it can be automatically updated if the update flag 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)

post_subscription(subscription: SubscriptionLD, update: bool = False) → str

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

Returns:

Id of the (created) subscription

Return type:

str

replace_existing_attributes_of_entity(entity: ContextLDEntity, append: bool = False)

The attributes previously existing in the entity are removed and replaced by the ones in the request.

Parameters:

• entity (ContextEntity) –

• append (bool) –

• options –

Returns:

update_entity_attribute(entity_id: str, attr: ContextProperty | ContextRelationship | NamedContextProperty | NamedContextRelationship, attr_name: str | None = None)

Updates a specified attribute from an entity. :param attr: context attribute to update :param entity_id: Id of the entity. Example: Bcn_Welt :param entity_type: Entity type, to avoid ambiguity in case there are :param several entities with the same entity id.:

update_subscription(subscription: SubscriptionLD) → None

Only the fields included in the request are updated in the subscription. :param subscription: Subscription to update

Returns: