... | @@ -3,21 +3,18 @@ El **caso de uso 13** está dedicado a la información relativa a la protección |
... | @@ -3,21 +3,18 @@ El **caso de uso 13** está dedicado a la información relativa a la protección |
|
Dentro de la plataforma DGT 3.0 se implementa:
|
|
Dentro de la plataforma DGT 3.0 se implementa:
|
|
|
|
|
|
- Una interfaz que permite el envío por parte de los suministradores de la información en tiempo real de sus usuarios que se encuentran montando en bicicleta por carreteras nacionales
|
|
- Una interfaz que permite el envío por parte de los suministradores de la información en tiempo real de sus usuarios que se encuentran montando en bicicleta por carreteras nacionales
|
|
|
|
- Publicación de la información validada para que cualquier tercero autorizado por DGT pueda consumir la ubicación en tiempo real de los ciclistas para informar a los usuarios de sus aplicaciones / vehículos
|
|
- Publicación de la información validada a través de la interfaz de bandeja de salida para que cualquier tercero autorizado por DGT pueda consumir la ubicación en tiempo real de los ciclistas para informar a los usuarios de sus aplicaciones / vehículos
|
|
|
|
|
|
|
|
- La implementación de una lógica de validación de la información recibida para evitar problemas derivados de la inexactitud del GPS de los dispositivos a la hora de enviar su posición y recepción incorrecta de los datos
|
|
- La implementación de una lógica de validación de la información recibida para evitar problemas derivados de la inexactitud del GPS de los dispositivos a la hora de enviar su posición y recepción incorrecta de los datos
|
|
|
|
|
|
La plataforma cuenta con dos funcionalidades diferenciadas para la **publicación (envío)** y para la **suscripción (recepción)** de información. La primera es a través de una API REST y la segunda a través de un servicio MQTT en tiempo real.
|
|
La plataforma cuenta con dos funcionalidades diferenciadas para la **publicación (envío)** y para la **suscripción (recepción)** de información. La primera es a través de una API REST ~~y la segunda a través de un servicio MQTT en tiempo real~~.
|
|
|
|
|
|
Tanto la funcionalidad de publicación como de suscripción requieren de certificados de acceso distintos que deben ser solicitados y suministrados por DGT 3.0. Estos certificados, de no haber sido solicitados ya, se deberán solicitar a *[soporte@cmobility30.es](mailto:soporte@cmobility30.es)*.
|
|
Tanto la funcionalidad de publicación como de suscripción requieren de certificados de acceso distintos que deben ser solicitados y suministrados por DGT 3.0. Estos certificados, de no haber sido solicitados ya, se deberán solicitar a [_soporte@cmobility30.es_](mailto:soporte@cmobility30.es).
|
|
|
|
|
|
A continuación se muestran las URLs con las que se accede a cada funcionalidad:
|
|
A continuación se muestran las URLs con las que se accede a cada funcionalidad:
|
|
|
|
| Modo | URL | Descripción |
|
|
| Modo | URL | Descripción |
|
|
|------|-----|-------------|
|
|
| ----------- | -------------------------------------- | ------------------------------------------------------------------- |
|
|
| Publicación | <https://pre.cmobility30.es/use-case-13> | Endpoint del entorno de integración de clientes para la publicación |
|
|
| Publicación | https://pre.cmobility30.es/use-case-13 | Endpoint del entorno de integración de clientes para la publicación |
|
|
| Suscripción | <mqtt://mqtt.pre.cmobility30.es:8883> | Endpoint del entorno de integración para la suscripción |
|
|
| Suscripción | mqtt://mqtt.pre.cmobility30.es:8883 | Endpoint del entorno de integración para la suscripción |
|
|
|
|
|
|
|
|
A continuación se describen las dos funcionalidades.
|
|
A continuación se describen las dos funcionalidades.
|
|
|
|
|
... | @@ -37,128 +34,89 @@ Este caso de uso dispone de una API REST para la publicación (envío) de los da |
... | @@ -37,128 +34,89 @@ Este caso de uso dispone de una API REST para la publicación (envío) de los da |
|
|
|
|
|
> [Evento](publicacion/Evento)
|
|
> [Evento](publicacion/Evento)
|
|
|
|
|
|
## Suscripción
|
|
## ~~Suscripción~~
|
|
|
|
|
|
Este caso de uso también dispone de un servicio de suscripción (recepción) de datos por parte de las empresas que así lo deseen mediante el protocolo MQTT. A continuación se pueden encontrar los detalles de esta:
|
|
~~Este caso de uso también dispone de un servicio de suscripción (recepción) de datos por parte de las empresas que así lo deseen mediante el protocolo MQTT. A continuación se pueden encontrar los detalles de esta:~~
|
|
|
|
|
|
**MQTT (MQ Telemetry Transport)** es un protocolo de mensajería que se usa como un método simple y liviano para transferir datos hacia/desde dispositivos de baja potencia.
|
|
**~~MQTT (MQ Telemetry Transport)~~** ~~es un protocolo de mensajería que se usa como un método simple y liviano para transferir datos hacia/desde dispositivos de baja potencia.~~
|
|
|
|
|
|
El protocolo admite un único patrón de mensajería, el patrón **Publicar-Suscribir**: cada mensaje es publicado en un tópico al que se debe suscribir para recibir la información.
|
|
~~El protocolo admite un único patrón de mensajería, el patrón **Publicar-Suscribir**: cada mensaje es publicado en un tópico al que se debe suscribir para recibir la información.~~
|
|
|
|
|
|
La suscripción al servicio de este caso de uso deberá ser mediante el tópico:
|
|
~~La suscripción al servicio de este caso de uso deberá ser mediante el tópico:~~
|
|
|
|
|
|
> usecase13/events
|
|
> ~~usecase13/events~~
|
|
|
|
|
|
En el tópico se publican los eventos en formato JSON. Aquí se puede ver un ejemplo:
|
|
~~En el tópico se publican los eventos en formato JSON. Aquí se puede ver un ejemplo:~~
|
|
|
|
|
|
```json
|
|
```json
|
|
{
|
|
|
|
"actionId": "CLI_235",
|
|
|
|
"beaconId": "cff92179-dc0a-47da-bd9e-5e9c5b14d251",
|
|
|
|
"beaconTypeId": 1,
|
|
|
|
"timestamp": "2021-06-02T14:40:20.347Z",
|
|
|
|
"deviceTypeId": 2,
|
|
|
|
"speed": 8,
|
|
|
|
"provinceId": 47,
|
|
|
|
"road": "A-601",
|
|
|
|
"pk": 7.01,
|
|
|
|
"direction": "UP",
|
|
|
|
"lonStart": -4.693653,
|
|
|
|
"latStart": 41.594408,
|
|
|
|
"lonEnd": -4.693653,
|
|
|
|
"latEnd": 41.594408
|
|
|
|
}
|
|
|
|
```
|
|
```
|
|
|
|
|
|
- actionId (texto): Identificador único del evento
|
|
- ~~actionId (texto): Identificador único del evento~~
|
|
|
|
- ~~beaconId (texto): identificador único de la baliza (por ejemplo, la MAC)~~
|
|
- beaconId (texto): identificador único de la baliza (por ejemplo, la MAC)
|
|
- ~~beaconTypeId (número entero): identificador del tipo de baliza. 1 = Individual, 2 = Group~~
|
|
|
|
- ~~timestamp (fecha UTC): fecha y hora en formato UTC del momento en el que el evento se ha generado. Es necesario que sea de un máximo de 15 segundos de antigüedad con respecto a la hora UTC. La fecha debe finalizar con el caracter 'Z' que marca que está en UTC~~
|
|
- beaconTypeId (número entero): identificador del tipo de baliza. 1 = Group, 2 = Individual
|
|
- ~~deviceTypeId (número entero): identificador del tipo de dispositivo desde el que se envía la información. 1 = Baliza, 2 = App~~
|
|
|
|
- ~~speed (número decimal): velocidad en kilómetros por hora a la que se encuentra el elemento en el momento que envía el evento~~
|
|
- timestamp (fecha UTC): fecha y hora en formato UTC del momento en el que el evento se ha generado. Es necesario que sea de un máximo de 15 segundos de antigüedad con respecto a la hora UTC. La fecha debe finalizar con el caracter 'Z' que marca que está en UTC
|
|
- ~~provinceId (número entero): identificador de la provincia donde se genera el evento según el~~ [~~INE~~](https://www.ine.es/daco/daco42/codmun/cod_provincia_estandar.htm)
|
|
|
|
- ~~road (número entero): nombre oficial de la carretera donde se genera el evento~~
|
|
- deviceTypeId (número entero): identificador del tipo de dispositivo desde el que se envía la información. 1 = Baliza, 2 = App
|
|
- ~~pk (número entero): punto kilométrico donde se genera el evento~~
|
|
|
|
- ~~direction (texto): dirección de la carretera donde se genera el evento. UP = Sentido ascendente, DOWN = Sentido descendente, UNKNOWN = Desconocido~~
|
|
- speed (número decimal): velocidad en kilómetros por hora a la que se encuentra el elemento en el momento que envía el evento
|
|
- ~~lonStart (número decimal): longitud de coordenadas de tipo WGS 84 donde se ha generado el evento~~
|
|
|
|
- ~~latStart (número decimal): latitud de coordenadas de tipo WGS 84 donde se ha generado el evento~~
|
|
- provinceId (número entero): identificador de la provincia donde se genera el evento según el [INE](https://www.ine.es/daco/daco42/codmun/cod_provincia_estandar.htm)
|
|
- ~~lonEnd (número decimal): longitud de coordenadas de tipo WGS 84 donde finaliza el evento~~
|
|
|
|
- ~~latEnd (número decimal): latitud de coordenadas de tipo WGS 84 donde finaliza el evento~~
|
|
- road (número entero): nombre oficial de la carretera donde se genera el evento
|
|
|
|
|
|
~~Ver más información y un ejemplo de conexión~~ [~~aquí~~](https://gitlab.cs.cmobility30.es/dgt3.0_esp/general/-/wikis/MQTT)~~.~~
|
|
- pk (número entero): punto kilométrico donde se genera el evento
|
|
|
|
|
|
**~~Nota: ~~**_~~La información que se está publicando en el entorno de desarrollo es una simulación con información no real que va cambiando a lo largo del día, de forma que se pueda probar la interface de consumo.~~_
|
|
- direction (texto): dirección de la carretera donde se genera el evento. UP = Sentido ascendente, DOWN = Sentido descendente, UNKNOWN = Desconocido
|
|
|
|
|
|
|
|
- lonStart (número decimal): longitud de coordenadas de tipo WGS 84 donde se ha generado el evento
|
|
|
|
|
|
|
|
- latStart (número decimal): latitud de coordenadas de tipo WGS 84 donde se ha generado el evento
|
|
|
|
|
|
|
|
- lonEnd (número decimal): longitud de coordenadas de tipo WGS 84 donde finaliza el evento
|
|
|
|
|
|
|
|
- latEnd (número decimal): latitud de coordenadas de tipo WGS 84 donde finaliza el evento
|
|
|
|
|
|
|
|
Ver más información y un ejemplo de conexión [aquí](https://gitlab.cs.cmobility30.es/dgt3.0_esp/general/-/wikis/MQTT).
|
|
|
|
|
|
|
|
**Nota:** *La información que se está publicando en el entorno de desarrollo es una simulación con información no real que va cambiando a lo largo del día, de forma que se pueda probar la interface de consumo.*
|
|
|
|
|
|
|
|
## Errores
|
|
## Errores
|
|
|
|
|
|
Como se ha indicado anteriormente, todas las respuestas HTTP que no sean **200 – OK**, se pueden considerar **inválidas**. El formato de la respuesta de error es como el siguiente ejemplo:
|
|
Como se ha indicado anteriormente, todas las respuestas HTTP que no sean **200 – OK**, se pueden considerar **inválidas**. El formato de la respuesta de error es como el siguiente ejemplo:
|
|
|
|
|
|
```json
|
|
```json
|
|
{
|
|
|
|
"status": 401,
|
|
|
|
"code": 1,
|
|
|
|
"message": "User not found or valid"
|
|
|
|
}
|
|
|
|
```
|
|
```
|
|
|
|
|
|
*Esto no aplica para el **Caso de Uso 9 - Grúas**. La información relativa a los errores en ese caso se puede encontrar aquí.
|
|
\*Esto no aplica para el **Caso de Uso 9 - Grúas**. La información relativa a los errores en ese caso se puede encontrar aquí.
|
|
|
|
|
|
Estos errores tendrán tres categorías principales:
|
|
Estos errores tendrán tres categorías principales:
|
|
|
|
|
|
#### Error de Autentificación
|
|
#### Error de Autentificación
|
|
|
|
|
|
- HTTP Status: **401 - Unauthorized**
|
|
- HTTP Status: **401 - Unauthorized**
|
|
|
|
| Code | Message |
|
|
| Code | Message |
|
|
|------|---------|
|
|
| ---- | ----------------------- |
|
|
| 1 | User not found or valid |
|
|
| 1 | User not found or valid |
|
|
|
|
|
|
|
|
#### Error de Cliente
|
|
#### Error de Cliente
|
|
|
|
|
|
- HTTP Status: **400 - Bad Request**
|
|
- HTTP Status: **400 - Bad Request**
|
|
|
|
| Code | Message |
|
|
| Code | Message |
|
|
|------|---------|
|
|
| ---- | ------------------------------------------------------------------- |
|
|
| 0 | Authenticate |
|
|
| 0 | Authenticate |
|
|
| 2 | Entity ID not found |
|
|
| 2 | Entity ID not found |
|
|
| 3 | Missing required property |
|
|
| 3 | Missing required property |
|
|
| 4 | The entity received cannot be proccessed |
|
|
| 4 | The entity received cannot be proccessed |
|
|
| 5 | Incorrect token received |
|
|
| 5 | Incorrect token received |
|
|
| 6 | Expired token received |
|
|
| 6 | Expired token received |
|
|
| 7 | There is an error with the token provided. Please request a new one |
|
|
| 7 | There is an error with the token provided. Please request a new one |
|
|
| 8 | No token received |
|
|
| 8 | No token received |
|
|
| 9 | Required request body is missing |
|
|
| 9 | Required request body is missing |
|
|
| 10 | Event is marked as expired by timestamp |
|
|
| 10 | Event is marked as expired by timestamp |
|
|
| 11 | Missing request header |
|
|
| 11 | Missing request header |
|
|
| 12 | Permission denied. Role assigned to user missing |
|
|
| 12 | Permission denied. Role assigned to user missing |
|
|
|
|
|
|
|
|
En el caso de obtener un *error 3 - Missing required property* la respuesta obtenida tendrá un valor en el *message* que nos indicará los campos que faltan por enviar:
|
|
En el caso de obtener un _error 3 - Missing required property_ la respuesta obtenida tendrá un valor en el _message_ que nos indicará los campos que faltan por enviar:
|
|
|
|
|
|
```json
|
|
```json
|
|
{
|
|
|
|
"status": 400,
|
|
|
|
"code": 3,
|
|
|
|
"message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
|
|
|
|
}
|
|
|
|
```
|
|
```
|
|
|
|
|
|
#### Error de Servidor
|
|
#### Error de Servidor
|
|
|
|
|
|
- HTTP Status: **500 - Internal Server Error**
|
|
- HTTP Status: **500 - Internal Server Error**
|
|
|
|
| Code | Message |
|
|
| Code | Message |
|
|
|------|---------|
|
|
| ---- | -------------- |
|
|
| 13 | Internal error |
|
|
| 13 | Internal error | |
|
|
|
\ No newline at end of file |
|
|