NGSI Go tutorial for NGSI-LD

NGSI-LD CRUD operation

Print host information

ngsi broker get --host orion-ld

brokerHost http://orion-ld:1026
ngsiType ld

List Context

ngsi context list --name tutorial

http://atcontext:8000/ngsi-ld.json

Version

ngsi version -h orion-ld

Create Operations

Create a New Data Entity

This example adds a new TemperatureSensor entity to the context.

1 Request:

ngsi create entity --link tutorial \
--data '{
      "id": "urn:ngsi-ld:TemperatureSensor:001",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 25,
            "unitCode": "CEL"
      }
}'

2 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001

Create New Attributes

This example adds a new batteryLevel Property and a controlledAsset Relationship to the existing TemperatureSensor entity with id=urn:ngsi-ld:TemperatureSensor:001.

3 Request:

ngsi append attrs --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 \
--data '{
       "batteryLevel": {
            "type": "Property",
            "value": 0.9,
            "unitCode": "C62"
      },
      "controlledAsset": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:Building:barn002"
      }
}'

4 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001

5 Request:

ngsi create entities --link tutorial \
--data '[
    {
      "id": "urn:ngsi-ld:TemperatureSensor:002",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 20,
            "unitCode": "CEL"
      }
    },
    {
      "id": "urn:ngsi-ld:TemperatureSensor:003",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 2,
            "unitCode": "CEL"
      }
    },
     {
      "id": "urn:ngsi-ld:TemperatureSensor:004",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 100,
            "unitCode": "CEL"
      }
    }
]'

Batch Create/Overwrite New Data Entities

This example uses the convenience batch processing endpoint to add or amend two TemperatureSensor entities in the context.

if an entity already exists, the request will update that entity's attributes.
if an entity does not exist, a new entity will be created.

6 Request:

ngsi upsert entities --link tutorial \
--data '[
    {
      "id": "urn:ngsi-ld:TemperatureSensor:002",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 21,
            "unitCode": "CEL"
      }
    },
    {
      "id": "urn:ngsi-ld:TemperatureSensor:003",
      "type": "TemperatureSensor",
      "category": {
            "type": "Property",
            "value": "sensor"
      },
      "temperature": {
            "type": "Property",
            "value": 27,
            "unitCode": "CEL"
      }
    }
]'

Read Operations

The /ngsi-ld/v1/entities endpoint is used for listing entities
The /ngsi-ld/v1/entities/<entity> endpoint is used for retrieving the details of a single entity.

For read operations the @context must be supplied in a Link header.

Filtering

The options parameter (combined with the attrs parameter) can be used to filter the returned fields
The q parameter can be used to filter the returned entities

Read a Data Entity (verbose)

This example reads the full context from an existing TemperatureSensor entity with a known id.

7 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --sysAttrs

Read an Attribute from a Data Entity

This example reads the value of a single attribute (temperature) from an existing TemperatureSensor entity with a known id.

8 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --attrs temperature

Read a Data Entity (key-value pairs)

This example reads the key-value pairs from the context of an existing TemperatureSensor entities with a known id.

9 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --keyValues

Read Multiple attributes values from a Data Entity

This example reads the value of two attributes (category and temperature) from the context of an existing TemperatureSensor entity with a known id.

10 Request:

ngsi get entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --keyValues --attrs category,temperature

List all Data Entities (verbose)

This example lists the full context of all TemperatureSensor entities.

11 Request:

ngsi list entities --link tutorial --type TemperatureSensor

List all Data Entities (key-value pairs)

This example lists the temperature attribute of all TemperatureSensor entities.

12 Request:

ngsi list entities -link tutorial --type TemperatureSensor --attrs temperature --keyValues

Filter Data Entities by ID

This example lists selected data from two TemperatureSensor entities chosen by id. Note that every id must be unique, so type is not required for this request. To filter by id add the entries in a comma delimited list.

13 Request:

ngsi list entities --link tutorial --id urn:ngsi-ld:TemperatureSensor:001,urn:ngsi-ld:TemperatureSensor:002 --attrs temperature --keyValues

Update Operations

Overwrite operations are mapped to HTTP PATCH:

The /ngsi-ld/v1/entities/<entity-id>/attrs/<attribute> endpoint is used to update an attribute
The /ngsi-ld/v1/entities/<entity-id>/attrs endpoint is used to update multiple attributes

Overwrite the value of an Attribute value

This example updates the value of the category attribute of the Entity with id=urn:ngsi-ld:TemperatureSensor:001

14 Request:

ngsi update attr --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --attr category \
--data '{
    "value": ["sensor", "actuator"],
    "type": "Property"
}'

Overwrite Multiple Attributes of a Data Entity

This example simultaneously updates the values of both the category and controlledAsset attributes of the Entity with id=urn:ngsi-ld:TemperatureSensor:001.

15 Request:

ngsi update attrs --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 \
--data '{
      "category": {
            "value": [
                  "sensor",
                  "actuator"
            ],
            "type": "Property"
      },
      "controlledAsset": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:Building:barn001"
      }
}'

Batch Update Attributes of Multiple Data Entities

This example uses the convenience batch processing endpoint to update existing sensors.

16 Request:

ngsi upsert entities --link tutorial --update \
--data '[
  {
    "id": "urn:ngsi-ld:TemperatureSensor:003",
    "type": "TemperatureSensor",
    "category": {
      "type": "Property",
      "value": [
        "actuator",
        "sensor"
      ]
    }
  },
  {
    "id": "urn:ngsi-ld:TemperatureSensor:004",
    "type": "TemperatureSensor",
    "category": {
      "type": "Property",
      "value": [
        "actuator",
        "sensor"
      ]
    }
  }
]'

Batch Replace Entity Data

This example uses the convenience batch processing endpoint to replace entity data of existing sensors.

17 Request:

ngsi update entities --link tutorial --replace \
--data '[
  {
    "id": "urn:ngsi-ld:TemperatureSensor:003",
    "type": "TemperatureSensor",
    "category": {
      "type": "Property",
      "value": [
        "actuator",
        "sensor"
      ]
    }
  },
  {
    "id": "urn:ngsi-ld:TemperatureSensor:004",
    "type": "TemperatureSensor",
    "temperature": {
      "type": "Property",
      "value": [
        "actuator",
        "sensor"
      ]
    }
  }
]'

Delete Operations

Delete Operations map to HTTP DELETE.

The /ngsi-ld/v1/entities/<entity-id> endpoint can be used to delete an entity
The /ngsi-ld/v1/entities/<entity-id>/attrs/<attribute> endpoint can be used to delete an attribute

The response will be 204 - No Content if the operation is successful or 404 - Not Found if the operation fails.

Data Relationships

If there are entities within the context which relate to one another, you must be careful when deleting an entity. You will need to check that no references are left dangling once the entity has been deleted.

Organizing a cascade of deletions is beyond the scope of this tutorial, but it would be possible using a batch delete request.

Delete an Entity

This example deletes the entity with id=urn:ngsi-ld:TemperatureSensor:004 from the context.

18 Request:

ngsi delete entity --link tutorial --id urn:ngsi-ld:TemperatureSensor:004

Delete an Attribute from an Entity

This example removes the batteryLevel attribute from the entity with id=urn:ngsi-ld:TemperatureSensor:001.

19 Request:

ngsi delete attr --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --attr batteryLevel

Batch Delete Multiple Entities

This example uses the convenience batch processing endpoint to delete some TemperatureSensor entities.

20 Request:

ngsi delete attr --link tutorial --id urn:ngsi-ld:TemperatureSensor:001 --attr batteryLevel
ngsi delete entities --link tutorial \
--data '[
  "urn:ngsi-ld:TemperatureSensor:002",
  "urn:ngsi-ld:TemperatureSensor:003"
]'

Batch Delete Multiple Attributes from an Entity

This example uses the PATCH /ngsi-ld/v1/entities/<entity-id>/attrs endpoint to delete some attributes from a TemperatureSensor entity.

21 Request:

ngsi update attrs --link tutorial --id urn:ngsi-ld:TemperatureSensor:001
--data '{
      "category": {
            "value": null,
            "type": "Property"
      },
      "controlledAsset": {
            "type": "Relationship",
            "object": null
      }
}'

Find existing data relationships

This example returns a header indicating whether any linked data relationships remain against the entity urn:ngsi-ld:Building:barn002

22 Request:

ngsi list entities --link tutorial --type TemperatureSensor --query controlledAsset==\"urn:ngsi-ld:Building:barn002\" --count