Gestión de relaciones topológicas - IoT Platform - Centro de documentación de Alibaba Cloud

Después de registrar un subdispositivo en IoT Platform, el gateway debe reportar la relación topológica entre el subdispositivo y el gateway para conectar el subdispositivo a IoT Platform.

Cuando un subdispositivo se conecta a IoT Platform, la plataforma verifica su identidad y la relación topológica entre el subdispositivo y el gateway. Si la verificación es exitosa, IoT Platform establece una conexión lógica con el subdispositivo y la asocia con la conexión física del gateway. El protocolo de comunicación entre el subdispositivo e IoT Platform es el mismo que se utiliza entre un dispositivo conectado directamente e IoT Platform. Este protocolo no requiere información del gateway.

Si se elimina la relación topológica, el subdispositivo no puede conectarse a IoT Platform mediante el gateway. Si intenta conectar el subdispositivo a IoT Platform, pueden presentarse los siguientes errores: 1. La relación topológica no existe. 2. La verificación terminó con errores.

Agregar relaciones topológicas para subdispositivos

Utilice un topic para enviar una solicitud que agregue una relación topológica entre un gateway y un subdispositivo. Si la relación topológica se agrega correctamente, se devuelve la información del subdispositivo.

Importante

Se pueden agregar hasta 30 subdispositivos de forma simultánea.

A continuación se muestran los topics que se utilizan cuando un subdispositivo envía solicitudes a IoT Platform y la plataforma envía respuestas al subdispositivo:

Tema de solicitud:/sys/${productKey}/${deviceName}/thing/topo/add
Tema de respuesta:/sys/${productKey}/${deviceName}/thing/topo/add_reply

Ejemplo de solicitud en formato Alink JSON:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554",
      "sign": "xxxxxx",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "xxxxxx"
    }
  ],
  "method": "thing.topo.add"
}

Ejemplo de respuesta en formato Alink JSON:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
sys	Object	Parámetros de funciones extendidas. Nota Si utiliza un SDK del lado del dispositivo sin configurar las funciones extendidas, este parámetro se omite y se aplican los valores predeterminados.
ack	Integer	Indica si la nube devuelve una respuesta. Es un campo dentro de sys. 1: Devuelve una respuesta. 0: No se devuelve ninguna respuesta. Importante Thing Specification Language model usage examples. Si no se configura, este parámetro se omite y se devuelve una respuesta de forma predeterminada.
params	List	Los parámetros de la solicitud.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.
sign	String	La firma. Método de firma: Ordene alfabéticamente todos los parámetros enviados al servidor, excepto sign y signMethod. Luego, concatene los parámetros y sus valores en orden secuencial, sin utilizar símbolos de concatenación. Calcule la firma con el algoritmo especificado en el parámetro signMethod y el valor del parámetro DeviceSecret. Ejemplo: `sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)`
signmethod	String	El algoritmo de firma. Los algoritmos compatibles son HMACSHA1, HMACSHA256, HMACMD5 y SHA256.
timestamp	String	La marca de tiempo.
clientId	String	Opcional. El identificador local del dispositivo. Puede establecer este parámetro con un valor que combine ProductKey y DeviceName mediante la siguiente sintaxis: productKey&deviceName.
method	String	El método de la solicitud. Establezca el valor en `thing.topo.add`.

Parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para un dispositivo.
code	Integer	El código de estado. El valor 200 indica que la solicitud fue exitosa.
data	Object	La información del subdispositivo devuelta cuando la solicitud es exitosa. Para obtener más información sobre los parámetros, consulte la siguiente tabla.

Tabla 1. data
Parámetro	Tipo	Descripción
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Mensajes de error

Código de estado HTTP	Mensaje de error	Descripción
460	request parameter error	Se devuelve este mensaje porque los parámetros de la solicitud no son válidos.
6402	topo relation cannot add by self	Se devuelve este mensaje porque un dispositivo no se puede agregar como subdispositivo de sí mismo.
401	request auth error	Se devuelve este mensaje porque la verificación de la firma terminó con errores.

Eliminar relaciones topológicas de subdispositivos

Utilice un topic para enviar una solicitud que elimine una relación topológica entre un gateway y un subdispositivo. Si la relación topológica se quita correctamente, se devuelve la información del subdispositivo.

Importante

Se pueden eliminar hasta 30 subdispositivos de forma simultánea.

A continuación se muestran los topics que se utilizan cuando un subdispositivo envía solicitudes a IoT Platform y la plataforma envía respuestas al subdispositivo:

Tema de solicitud:/sys/${productKey}/${deviceName}/thing/topo/delete
Tema de respuesta:/sys/${productKey}/${deviceName}/thing/topo/delete_reply.

Ejemplo de solicitud en formato Alink JSON:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.delete"
}

Ejemplo de respuesta en formato Alink JSON:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
sys	Object	Parámetros de funciones extendidas. Nota Si utiliza un SDK del lado del dispositivo sin configurar las funciones extendidas, este parámetro se omite y se aplican los valores predeterminados.
ack	Integer	Indica si la nube devuelve una respuesta. Es un campo dentro de sys. 1: Devuelve una respuesta. 0: No se devuelve ninguna respuesta. Importante Thing Specification Language model usage examples. Si no se configura, este parámetro se omite y se devuelve una respuesta de forma predeterminada.
params	List	Los parámetros de la solicitud.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.
method	String	El método de la solicitud. Establezca el valor en `thing.topo.delete`.

Parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para un dispositivo.
code	Integer	El código de estado. El valor 200 indica que la solicitud fue exitosa.
data	Object	La información del subdispositivo devuelta cuando la solicitud es exitosa. Para obtener más información sobre los parámetros, consulte la siguiente tabla.

Tabla 2. data
Parámetro	Tipo	Descripción
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Mensajes de error

Código de estado HTTP	Mensaje de error	Descripción
460	request parameter error	Se devuelve este mensaje porque los parámetros de la solicitud no son válidos.
6100	device not found	Se devuelve este mensaje porque el dispositivo no existe.

Consultar relaciones topológicas de subdispositivos

A continuación se muestran los topics que se utilizan cuando un subdispositivo envía solicitudes a IoT Platform y la plataforma envía respuestas al subdispositivo:

Tema de solicitud:/sys/${productKey}/${deviceName}/thing/topo/get
Tema de respuesta:/sys/${productKey}/${deviceName}/thing/topo/get_reply

Utilice un topic para enviar una solicitud que consulte la relación topológica entre un gateway y un subdispositivo.

Ejemplo de solicitud en formato Alink JSON:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
}

Ejemplo de respuesta en formato Alink JSON:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
sys	Object	Parámetros de funciones extendidas. Nota Si utiliza un SDK del lado del dispositivo sin configurar las funciones extendidas, este parámetro se omite y se aplican los valores predeterminados.
ack	Integer	Indica si la nube devuelve una respuesta. Es un campo dentro de sys. 1: Devuelve una respuesta. 0: No se devuelve ninguna respuesta. Importante Thing Specification Language model usage examples. Si no se configura, este parámetro se omite y se devuelve una respuesta de forma predeterminada.
params	Object	Los parámetros de la solicitud. Puede dejarlos vacíos.
method	String	El método de la solicitud. Establezca el valor en `thing.topo.get`.

Parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para un dispositivo.
code	Integer	El código de estado. El valor 200 indica que la solicitud fue exitosa.
data	Object	Los datos de respuesta cuando la solicitud es exitosa.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Mensajes de error

Código de estado HTTP	Mensaje de error	Descripción
460	request parameter error	Se devuelve este mensaje porque los parámetros de la solicitud no son válidos.

Enviar subdispositivos recién descubiertos

A continuación se muestran los topics que se utilizan cuando un subdispositivo envía solicitudes a IoT Platform y la plataforma envía respuestas al subdispositivo:

Tema de solicitud:/sys/${productKey}/${deviceName}/thing/list/found
Tema de respuesta:/sys/${productKey}/${deviceName}/thing/list/found_reply

En ciertos escenarios, un gateway detecta nuevos subdispositivos. Cuando esto ocurre, el gateway reporta la información de estos dispositivos a IoT Platform. La plataforma reenvía dicha información a aplicaciones de terceros, las cuales eligen los subdispositivos que se conectarán al gateway.

Ejemplo de solicitud en formato Alink JSON:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.list.found"
}

Ejemplo de respuesta en formato Alink JSON:

{
  "id": "123",
  "code": 200,
  "data":{}
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
sys	Object	Parámetros de funciones extendidas. Nota Si utiliza un SDK del lado del dispositivo sin configurar las funciones extendidas, este parámetro se omite y se aplican los valores predeterminados.
ack	Integer	Indica si la nube devuelve una respuesta. Es un campo dentro de sys. 1: Devuelve una respuesta. 0: No se devuelve ninguna respuesta. Importante Thing Specification Language model usage examples. Si no se configura, este parámetro se omite y se devuelve una respuesta de forma predeterminada.
params	Object	Los parámetros de la solicitud. Puede dejarlos vacíos.
method	String	El método de la solicitud. Establezca el valor en `thing.list.found`.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para un dispositivo.
code	Integer	El código de estado. El valor 200 indica que la solicitud fue exitosa.
data	Object	Los datos de respuesta cuando la solicitud es exitosa.

Mensajes de error

Código de estado HTTP	Mensaje de error	Descripción
460	request parameter error	Se devuelve este mensaje porque los parámetros de la solicitud no son válidos.
6250	product not found	Se devuelve este mensaje porque el producto al que pertenece el subdispositivo no existe.
6280	devicename not meet specs	Se devuelve este mensaje porque el DeviceName del subdispositivo reportado por el gateway no es válido.

Notificar a los gateways que agreguen relaciones topológicas para subdispositivos

A continuación se muestra el topic que se utiliza cuando IoT Platform envía solicitudes a un subdispositivo y este responde a la plataforma:

Tema de solicitud:/sys/${productKey}/${deviceName}/thing/topo/add/notify
Tema de respuesta:/sys/${productKey}/${deviceName}/thing/topo/add/notify_reply

IoT Platform utiliza un topic para indicar a un gateway que agregue una relación topológica para un subdispositivo. Esto aplica después de que el gateway detecta nuevos subdispositivos y reporta su información a IoT Platform. Para recibir la respuesta del gateway, la plataforma se suscribe al siguiente topic de reenvío de datos: /${productKey}/${deviceName}/thing/downlink/reply/message.

Ejemplo de solicitud en formato Alink JSON:

{
  "id": "123",
  "version": "1.0",
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.add.notify"
}

Ejemplo de respuesta en formato Alink JSON:

{
  "id": "123",
  "code": 200,
  "data": {}
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje generado por IoT Platform. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
params	Object	Los parámetros de la solicitud. Puede dejarlos vacíos.
method	String	El método de la solicitud. Establezca el valor en `thing.topo.add.notify`.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Parámetros de respuesta

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para un dispositivo.
code	Integer	El código de estado. El valor 200 indica que la solicitud fue exitosa.
data	Object	Los datos de respuesta cuando la solicitud es exitosa.

Notificar a los gateways los cambios en las relaciones topológicas

IoT Platform notifica a los gateways cuando cambian las relaciones topológicas.

Los gateways deben suscribirse al siguiente topic: /sys/${productKey}/${deviceName}/thing/topo/change

Operación	Comportamiento	Método de notificación
Agregar subdispositivos a los gateways.	Agrega las relaciones topológicas entre los gateways y los subdispositivos.	Notifica a los gateways.
Eliminar subdispositivos.	Elimina las relaciones topológicas entre los subdispositivos y los gateways.
Deshabilitar subdispositivos.	Deshabilita los subdispositivos y sus relaciones topológicas con los gateways.
Habilitar subdispositivos.	Habilita los subdispositivos y restablece sus relaciones topológicas con los gateways.

Ejemplo de solicitud en formato Alink JSON:

{
    "id":"123",
    "version":"1.0",
    "params":{
        "status":0, // 0-add 1-remove 2-resume disabling 8-disable
        "subList":[{
            "productKey":"a1hRrzD****",
            "deviceName":"abcd"
        }]
    }, 
  "method":"thing.topo.change"  
}

Parámetros de solicitud

Parámetro	Tipo	Descripción
id	String	El identificador del mensaje generado por IoT Platform. Valores válidos: de 0 a 4294967295. Cada identificador de mensaje debe ser único para el dispositivo.
version	String	El número de versión del protocolo. Establezca el valor en 1.0.
method	String	El método de la solicitud. Establezca el valor en `thing.topo.change`.
params	Object	Los parámetros de la solicitud, que incluyen status y subList. El parámetro status define el estado de la relación topológica, mientras que subList especifica la lista de subdispositivos.
status	Integer	El estado de la relación topológica. 0: La relación topológica se agregó. 1: La relación topológica se eliminó. 2: La relación topológica se habilitó. 8: La relación topológica se deshabilitó.
deviceName	String	El DeviceName del subdispositivo.
productKey	String	El ProductKey del producto al que pertenece el subdispositivo.

Ejemplo de respuesta en formato Alink JSON:

{
    "id":"123",
    "code":200,
    "message":"success",
    "data":{}
}