The following have been taken from the Scorpio and Orion-LD tutorials, after doing everything as described by the tutorials and after reading the next page
Swagger Interface- interacting with the broker made easy
feel free to also try using the swagger interface to play around with the various commands.
<aside> ⚠️ VERY IMPORTANT TO WATCH OUT FOR:
</aside>
<aside> 💡 The first tutorial presented here, used scorpio as the ngsi-ld broker and not Orion-LD. Nothing changes really since the use the same API, but the default port for Scorpio is 9090 and the default port for Orion-LD is 1026, since it is assumed that following this notion guide, Orion-LD has been installed please look out for the port used while communicating with the broker. The same goes of course if you have changed the port to anything else from the default. I have changed the port from 9090 to 1026 but I might have missed something.
</aside>
1. INTRODUCTION
****This walkthrough adopts a practical approach that we hope will help our readers to get familiar with NGSI-LD in general and the Scorpio Broker in particular - and have some fun in the process :). The walkthrough is based on the NGSI-LD Specification, that can be found in here [https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.02.02_60/gs_CIM009v010202p.pdf]. –> will become gs_CIM009v010301p.pdf soon … You should also have a look at the NGSI-LD implementation notes. –> once they are available To get familiar with NGSI-LD, you may also have a look at the NGSI-LD Primer [https://www.etsi.org/deliver/etsi_gr/CIM/001_099/008/01.01.01_60/gr_CIM008v010101p.pdf] that is targeted at developers. The main section is about context management. It describes the basic context broker functionality for context management (information about entities, such as the temperature of a car). Context source management (information not about the entities themselves, but about the sources that can provide the information in a distributed system setup) is also described as part of this document. It is recommended to get familiar with the theoretical concepts on which the NGSI-LD model is based before starting. E.g. entities, properties, relationships etc. Have a look at the FIWARE documentation about this, e.g. this public presentation. [… find suitable presentation]
1.1. STARTING THE BROKER FOR THE TUTORIALS
****You should already have an ngsi-ld broker up and running, if not please follow this notion guide by its default order
1.2. ISSUING COMMANDS TO THE BROKER
****To issue requests to the broker, you can use the curl command line tool. curl is chosen because it is almost ubiquitous in any GNU/Linux system and simplifies including examples in this document that can easily be copied and pasted. Of course, it is not mandatory to use it, you can use any REST client tool instead (e.g. RESTClient). Indeed, in a real case, you will probably interact with the Broker using a programming language library implementing the REST client part of your application. The basic patterns for all the curl examples in this document are the following: For POST: curl localhost:1026/ngsi-ld/v1/<ngsi-ld-resource-path> -s -S [headers]’ -d @- <<EOF [payload] EOF For PUT: curl localhost:1026/ngsi-ld/v1/<ngsi-ld-resource-path> -s -S [headers] -X PUT -d @- <<EOF [payload] EOF For PATCH: curl localhost:1026/ngsi-ld/v1/<ngsi-ld-resource-path> -s -S [headers] -X PATCH -d @- <<EOF [payload] EOF For GET: curl localhost:1026/ngsi-ld/v1/<ngsi-ld-resource-path> -s -S [headers] For DELETE: curl localhost:1026/ngsi-ld/v1/<ngsi-ld-resource-path> -s -S [headers] -X DELETE Regarding [headers] you have to include the following ones: Accept header to specify the payload format in which you want to receive the response. You should explicitly specify JSON or JSON-LD. curl … -H ‘Accept: application/json’ … or curl … -H ‘Accept: application/ld-json’ depending on whether you want to receive the JSON-LD @context in a link header or in the body of the response (JSON-LD and the use of @context is described in the following section). If using payload in the request (i.e. POST, PUT or PATCH), you have to supply the Context-Type HTTP header to specify the format (JSON or JSON-LD). curl … -H ‘Content-Type: application/json’ … or -H ‘Content-Type: application/ld+json’ In case the JSON-LD @context is not provided as part of the request body, it has to be provided as a link header, e.g. curl … -H ‘Link: <https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld>; rel=”http://www.w3.org/ns/json-ld#context”; type=”application/ld+json” where the @context has to be retrievable from the first URI, i.e. in this example: https://uri.etsi.org/ngsi-ld/primer/store-context.jsonld Some additional remarks: Most of the time we are using multi-line shell commands to provide the input to curl, using EOF to mark the beginning and the end of the multi-line block (here-documents). In some cases (GET and DELETE) we omit -d @- as no payload is used. In the examples, it is assumed that the broker is listening on port 1026. Adjust this in the curl command line if you are using a different port. **** In order to pretty-print JSON in responses, you can use Python with msjon.tool (examples along with tutorial are using this style): (curl … | python -mjson.tool) <<EOF … EOF Check that curl is installed in your system using:
**which curl
1.3. NGSI-LD DATA IN 3 SENTENCES** NGSI-LD is based on JSON-LD. Your toplevel entries are NGSI-LD Entities. Entities can have Properties and Relationships and Properties and Relationships can themselves also have Properties and Relationships (meta information). All keys in the JSON-LD document must be URIs, but there is a way to shorten it. 1.4. @CONTEXT NGSI-LD builds upon JSON-LD. Coming from JSON-LD there is the concecpt of a mandatory @context entry which is used to ‘translate’ between expanded full URIs and a compacted short form of the URI. e.g. “Property”: “https://uri.etsi.org/ngsi-ld/Property”. @context entries can also be linked in via a URL in a JSON array. You can also mix this up, so this is perfectly fine.
**{
"@context": [{
"myshortname": "urn:mylongname"
},
"<https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld>"
]
}**
****NGSI-LD has a core context made available at https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld. Even though it is highly recommended to always provide a full entry of all used @context entries, NGSI-LD brokers will inject the core context on any entry where it is missing.
1.5. APPLICATION/JSON AND APPLICATION/LD+JSON You can provide and receive data in two different ways. The main difference between application/json and application/ld+json is where you provide or receive the mandatory @context entry. If you set the accept header or the content-type header to application/ld+json the @context entry is embedded in the JSON document as a root level entry. If it is set to application/json the @context has to be provided in a link in the header entry Link like this. <https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld>; rel=”http://www.w3.org/ns/json-ld#context”; type=”application/ld+json”
1.6. CONTEXT MANAGEMENT To show the use of @context, most examples in this tutorial will be done as application/ld+json having the @context entries in the body of the payload. At the end of this section, you will have the basic knowledge to create applications (both context producers and consumers) using the Broker with context management operations.
2. ENTITY CREATION Assuming a fresh start we have an empty Broker. First, we are going to create house2:smartrooms:room1. Let’s assume that at entity creation time, temperature is 23 ?C and it is part of smartcity:houses:house2.
**curl localhost:1026/ngsi-ld/v1/entities -s -S -H 'Content-Type: application/ld+json' -d @- <<EOF
{
"id": "house2:smartrooms:room1",
"type": "Room",
"temperature": {
"value": 23,
"unitCode": "CEL",
"type": "Property",
"providedBy": {
"type": "Relationship",
"object": "smartbuilding:house2:sensor0815"
}
},
"isPartOf": {
"type": "Relationship",
"object": "smartcity:houses:house2"
},
"@context": [{"Room": "urn:mytypes:room", "temperature": "myuniqueuri:temperature", "isPartOf": "myuniqueuri:isPartOf"},"<https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld>"]
}
EOF**