Este tutorial es una introducci贸n al despliegue de un Context Broker en un entorno local y el uso de la plataforma Thinking Cities de Telef贸nica como plataforma comercial FIWARE.
Antes de poder seguir con este curso, es necesario cumplir con varias condiciones, tenienodo que tener instalados diversos programas.
Postman es un cliente de peticiones HTTP, que nos permitir谩 interactuar con la API NGSI de una forma gr谩fica, sencilla e intuitiva. Para obtener m谩s informaci贸n sobre como instalar y configurar Postman, as铆 como para descargar la colecci贸n de peticiones y el fichero de variables de entorno, haz click aqu铆. Tambi茅n puedes descargar los ficheros a continuaci贸n:
Existen varios m茅todos para poder ejecutar docker en su equipo. Si usted est谩 utilizando una distribuci贸n Linux, seguramente pueda instalar sin ning煤n tipo de problema Docker de forma Nativa.
A continuaci贸n se enlazan las gu铆as de instalaci贸n de docker para los distintos sistemas operativos:
-
Linux. Dependiendo de la distribuci贸n tienen gu铆as distintas:
-
Windows: https://docs.docker.com/docker-for-windows/install/
Adem谩s de Docker, tambi茅n ser谩 necesario disponer instalado de Docker-Compose. Tanto en Windows como en MacOS, Docker-Compose se instala con la instalaci贸n de Docker Desktop. Para linux podemos seguir las instrucciones reflejadas en la gu铆a.
Para que el tutorial sea lo m谩s homog茅neo posible, vamos a instalar docker y docker-compose sobre una m谩quina virutal. As铆, la ejecuci贸n de este tutorial ser谩 totalmente independiente del sistema operativo (huesped) y de la m谩quina en la que se corre.
Es necesario de disponer de un software de virtualizaci贸n para correr una m谩quina virtual dentro del sistema operativo. En este caso se recomienda usar Virtualbox puesto que es Open Source. Se puede descargar desde aqu铆.
En este caso queremos que la propia m谩quina virtual tenga una IP propia, por lo que en configuraci贸nes de red vamos a elegir la opci贸n de Adaptador de puente
o Bridge
Dado que Centos no se conecta de forma autom谩tica a la red, vamos a ejecutar el cliente DHCP para que la m谩quina obtenga IP.
dhclient
A continuaci贸n vamos a comprobar la IP que tiene la m谩quina virtual para poder conectarnos por SSH.
ip addr
La respuesta al comando debe ser algo similar a la siguiente imagen
De ella podemos deducir que la IP de la m谩quina es, para este ejemplo, 192.168.1.141
. Una vez conocemos la IP de la m谩quina, abrimos una sesi贸n SSH, para ello, en Windows podemos usar S铆mbolo de Sistema o PowerShell. Tanto en Linux como en MacOS, podemos usar la consola de comandos.
ssh user@domain
Donde user
ser谩 el usuario con el que hemos creado la cuenta al hacer la instalaci贸n del sistema operativo y domain
la IP que hemos obtenido en el paso anterio.
Una vez tengamos acceso, aprovechamos para instalar wget, que ser谩 utilizado m谩s adelante para descargar el fichero docker-compose.yml, de la siguiente manera
yum install wget
Es necesario disponer de Docker y Docker compose dado que vamos a lanzar los servicios contenedorizados. Una vez podemos acceder a la m谩quina debemos seguir los siguientes pasos:
Primero instalamos docker
yum install docker
Lanzamos los servicios de sistema
systemctl enable docker
systemctl start docker
Comprobamos que Docker funciona correctamente
docker info
Descargamos Docker-Compose y le damos permisos de ejecuci贸n:
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
Antes de nada debemos descargarnos el fichero docker compose con el que vamos a desplegar el context broker
wget https://raw.githubusercontent.com/telefonicaid/fiware-orion/master/docker/docker-compose.yml
El fichero que acabamos de descargar es el siguiente:
mongo:
image: mongo:3.6
command: --nojournal
orion:
image: fiware/orion
links:
- mongo
ports:
- "1026:1026"
command: -dbhost mongo
En el podemos ver los 2 contenedores que se van a desplegar, por un lado Orion, y por otro MongoDB, que es la base de datos que emplea el Orion Context Broker para la persistencia de los datos.
Para lanzar los contenedores solo tenemos que ejecutar el siguiente comando, siempre y cuando estemos en el mismo directorio que el fichero docker-compose.yml que queremos lanzar
docker-compose up
Alternativamente, para lanzarlo en segundo plano, su puede usar:
docker-compose up -d
Desde el navegador Acceder a http://{{IP_VM}}:1026/version
Desde el terminal, en la propia m谩quina virtual, podemos comprobarlo de la siguiente manera:
curl -X GET 'http://localhost:1026/version'
Vamos a emplear la API NGSI V2 para hacer las peticiones. La documentaci贸n de referencia la podemos encontrar aqu铆 o aqu铆
Vamos a crear nuestra primera entidad en el context broker. Esta entidad ser谩 de tipo coche o Car
, con el identificador entity-id:001
y con 3 atributos:
brand
de tipo texto, con valorSeat
model
de tipo texto, con valorLeon
name
de tipo texto, con valorVeh铆culo de antonio
Para ello ejecutamos el siguiente comando:
curl -iX POST 'http://localhost:1026/v2/entities' \
-H 'Content-Type: application/json' \
-d '
{
"id": "entity-id:001",
"type": "Car",
"brand": {
"type": "Text",
"value": "Seat"
},
"model": {
"type": "Text",
"value": "Leon"
},
"name": {
"type": "Text",
"value": "Veh铆culo de Antonio"
}
}'
El terminal nos devolvera la siguiente respuesta en la que podemos apreciar que la petici贸n se ha ejecutado correctamente, devolviendonos un c贸digo de respuesta 201
HTTP/1.1 201 Created
Connection: Keep-Alive
Content-Length: 0
Location: /v2/entities/entity-id:001?type=Car
Fiware-Correlator: 4905034e-7f3b-11ea-b71c-0242ac120003
Date: Wed, 15 Apr 2020 17:05:19 GMT
Para a帽adir un atributo a la entidad debemos hacer un POST
a /v2/entities/{{entity-id}}
donde {{entity-id}}
es el identificador de la entidad que queremos modificar, en este caso, entity-id:001
. El nuevo atributo a a帽adir se pasa en el cuerpo de la petici贸n, en este caso se a帽ade un nuevo atributo location
. En caso de que el atributo ya exista, con esta petici贸n lo va a sobreescribir.
curl -iX POST 'http://localhost:1026/v2/entities/entity-id:001/attrs' \
-H 'Content-Type: application/json' \
-d '
{
"location": {
"type": "geo:json",
"value": {
"type": "Point",
"coordinates": [13.3986, 52.5547]
}
}
}'
La respuesta del servidor debe ser un c贸digo 204
HTTP/1.1 204 No Content
Connection: Keep-Alive
Content-Length: 0
Fiware-Correlator: 633ffc30-8a28-11ea-9e6a-0242ac120003
Date: Wed, 29 Apr 2020 14:47:45 GMT
Para leer todas las entidades debemos hacer una petici贸n GET a /v2/entities como se muestra a continuaci贸n:
curl -iX GET 'http://localhost:1026/v2/entities'
La respuesta nos devolver谩 un c贸digo 200 y un array JSON con las entidades disponibles en el Context Broker, tal y como se puede ver a continuaci贸n.
HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 313
Content-Type: application/json
Fiware-Correlator: 7ab153e8-7f3b-11ea-80ad-0242ac120003
Date: Wed, 15 Apr 2020 17:06:42 GMT
[{"id":"entity-id:001","type":"Car","brand":{"type":"Text","value":"Seat","metadata":{}},"model":{"type":"Text","value":"Leon","metadata":{}},"name":{"type":"Text","value":"Veh铆culo de Antonio","metadata":{}},"location":{"type":"geo:json","value":{"type":"Point","coordinates":[13.3986,52.5547]},"metadata":{}}}]
Si damos formato a los datos de la respuesta de la petici贸n, para que sea m谩s sencillo de leer, podemos ver que es la entidad que hemos creado anteriormente, junto a las modificaciones que hemos hecho sobre ella.
[
{
"id": "entity-id:001",
"type": "Car",
"brand": {
"type": "Text",
"value": "Seat",
"metadata": {}
},
"model": {
"type": "Text",
"value": "Leon",
"metadata": {}
},
"name": {
"type": "Text",
"value": "Veh铆culo de Antonio",
"metadata": {}
},
"location": {
"type": "geo:json",
"value": {
"type": "Point",
"coordinates": [
13.3986,
52.5547
]
},
"metadata": {}
}
}
]
Para borrar una etidad s贸lamente hay que hacer una petici贸n DELETE a /v2/entities/{{entity-id}}
curl -iX DELETE 'http://localhost:1026/v2/entities/entity-id:001'
En este caso, el servidor nos debe devolver un c贸digo 204
HTTP/1.1 204 No Content
Connection: Keep-Alive
Content-Length: 0
Fiware-Correlator: 5842c690-8a29-11ea-a7ab-0242ac120003
Date: Wed, 29 Apr 2020 14:54:36 GMT