View a markdown version of this page

Implementar la AWS.DiscoverDevices operación - Integraciones gestionadas para AWS IoT Device Management
Marca y modeloConstruir un CapabilityReport

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Implementar la AWS.DiscoverDevices operación

La detección de dispositivos alinea la lista de dispositivos físicos propiedad del usuario final con las representaciones digitales de esos dispositivos de usuario final mantenidas en Managed Integrations for. AWS IoT Device Management Lo realiza un AWS cliente en los dispositivos que son propiedad del usuario final. En el caso de OAuth 2.0, esto ocurre una vez finalizada la vinculación de la cuenta. En el caso de la autorización general, esto puede ocurrir después de crear la asociación de cuentas.

La detección de dispositivos es un proceso asíncrono en el que Managed Integrations for AWS IoT Device Management llama a un conector para iniciar la solicitud de detección de dispositivos. Un conector C2C devuelve una lista de los dispositivos de los usuarios finales detectados de forma asíncrona con un identificador de referencia (denominado «) generado por Managed Integrations para. deviceDiscoveryId AWS IoT Device Management

Flujo de trabajo de AWS.DiscoverDevices

El siguiente diagrama ilustra el flujo de trabajo de descubrimiento de dispositivos entre el usuario final y las integraciones gestionadas para: AWS IoT Device Management

AWS.DiscoverDevices flujo de trabajo
Pasos del flujo de trabajo

  1. El cliente inicia el descubrimiento del dispositivo: el cliente inicia el proceso de descubrimiento del dispositivo en nombre del usuario final.

  2. Las integraciones gestionadas generan un identificador de referencia; las integraciones gestionadas AWS IoT Device Management generan un identificador de referencia utilizado deviceDiscoveryId para la solicitud de descubrimiento del dispositivo generada por el cliente. AWS

  3. Solicitud de descubrimiento de dispositivos enviada: Managed Integrations for AWS IoT Device Management envía una solicitud de descubrimiento de dispositivos al conector C2C mediante la interfaz de AWS.DiscoverDevices operación, incluida la información de autorización (token de acceso o AWS Secrets Manager referencia de OAuth), así como la. deviceDiscoveryId

  4. El conector almacena el dispositivoDiscoveryId: el conector se almacena deviceDiscoveryId para incluirlo en el evento. DEVICE_DISCOVERY Este evento también contendrá una lista de los dispositivos de los usuarios finales descubiertos y debe enviarse a Managed Integrations o a AWS IoT Device Management través de la SendConnectorEvent API como DEVICE_DISCOVERY evento.

  5. El conector llama al servidor de recursos: su conector C2C llamará al servidor de recursos para buscar todos los dispositivos propiedad del usuario final.

  6. El conector responde con ACK: su conector C2C Lambda responde a la invocación de Lambda invokeFunction () y la respuesta ACK devuelve a Managed Integrations AWS IoT Device Management para, que actúa como respuesta inicial para la operación. AWS.DiscoverDevices Managed Integrations for AWS IoT Device Management notifica al cliente con un ACK el proceso de descubrimiento de dispositivos que ha iniciado.

  7. El servidor de recursos devuelve la lista de dispositivos: el servidor de recursos le envía una lista de los dispositivos que son propiedad del usuario final y están operados por él.

  8. Convertir el formato del dispositivo: el conector convierte cada dispositivo del usuario final en las integraciones gestionadas según el formato de dispositivo AWS IoT Device Management requeridoConnectorDeviceId, ConnectorDeviceName incluido un informe de capacidad para cada dispositivo.

  9. Proporcione UserId: el conector C2C también proporciona información sobre el UserId propietario del dispositivo descubierto. Se puede recuperar del servidor de recursos como parte de la lista de dispositivos o mediante una llamada independiente, según la implementación del servidor de recursos.

  10. Llame a la SendConnectorEvent API: a continuación, su conector C2C llamará a las integraciones gestionadas para la AWS IoT Device Management API, a través de SigV4SendConnectorEvent, utilizando Cuenta de AWS credenciales y con el parámetro de operación establecido como «DEVICE_DISCOVERY». Cada dispositivo de la lista de dispositivos para los que se envía a Managed Integrations se AWS IoT Device Management representará mediante parámetros específicos del dispositivo, como, y a. connectorDeviceId connectorDeviceName capabilityReport

    • En función de la respuesta del servidor de recursos, debe notificar a Managed Integrations en consecuencia. AWS IoT Device Management

    • Por ejemplo, si el servidor de recursos tiene una respuesta paginada a la lista de dispositivos detectados para un usuario final, para cada encuesta puede enviar un evento DEVICE_DISCOVERY operativo individual, con un statusCode parámetro de. 3xx Si el descubrimiento del dispositivo aún está en proceso, repita los pasos 5, 6 y 7.

  11. Managed Integrations notifica al cliente: Managed Integrations for AWS IoT Device Management envía una notificación al cliente sobre el descubrimiento de los dispositivos del usuario final.

  12. Notificación de finalización: si su conector C2C envía un evento de DEVICE_DISCOVERY operación con el statusCode parámetro actualizado con un valor de 200, Managed Integrations for AWS IoT Device Management notificará al cliente la finalización del flujo de trabajo de descubrimiento del dispositivo.

importante

Si lo desea, los pasos 7 a 11 pueden realizarse antes del paso 6. Por ejemplo, si su plataforma de terceros tiene una API para enumerar los dispositivos de un usuario final, el evento DEVICE_DISCOVERY se puede enviar SendConnectorEvent antes de que el conector C2C Lambda responda con el ACK típico.

Requisitos del conector C2C para el descubrimiento de dispositivos

En la siguiente lista se describen los requisitos del conector C2C para facilitar la detección correcta del dispositivo:

  • El conector C2C Lambda puede procesar un mensaje de solicitud de descubrimiento de dispositivos de Managed Integrations y gestionar AWS IoT Device Management la operación. AWS.DiscoverDevices

  • Su conector C2C puede llamar a las integraciones gestionadas para las AWS IoT Device Management API a través de SiGv4 utilizando las credenciales utilizadas para registrar el Cuenta de AWS conector.

Proceso de descubrimiento de dispositivos

Paso 1: Las integraciones gestionadas activan el descubrimiento de dispositivos

Envía una solicitud POST a DiscoverDevices con una de las siguientes cargas útiles de JSON, según el tipo de autorización:

Solicitud de OAuth 2.0:

/DiscoverDevices
{
   "header": {
        "auth": {                 
            "token": "ashriu32yr97feqy7afsaf",  
            "type": "OAuth2.0"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}
nota

El connectorDeviceIdList parámetro es un filtro opcional que te permite especificar una lista de identificadores de dispositivos que deseas descubrir. Si está vacío ([]), se detectarán todos los dispositivos asociados a la cuenta. Cuando se rellene con identificadores de dispositivos específicos, solo esos dispositivos se incluirán en la respuesta de detección.

Solicitud de autorización general:

/DiscoverDevices
{
   "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}
nota

El connectorDeviceIdList parámetro es un filtro opcional que le permite especificar una lista de identificadores de dispositivos que desea descubrir. Si está vacío ([]), se detectarán todos los dispositivos asociados a la cuenta. Cuando se rellene con identificadores de dispositivos específicos, solo esos dispositivos se incluirán en la respuesta de detección.

Solicitud de autorización general:

/DiscoverDevices
{
   "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}
nota

El connectorDeviceIdList parámetro es un filtro opcional que le permite especificar una lista de identificadores de dispositivos que desea descubrir. Si está vacío ([]), se detectarán todos los dispositivos asociados a la cuenta. Cuando se rellene con identificadores de dispositivos específicos, solo esos dispositivos se incluirán en la respuesta de detección.

Paso 2: El conector reconoce el descubrimiento

El conector envía un acuse de recibo con la siguiente respuesta JSON:

{
     "header": {
          "responseCode":200
     },
     "payload": {
          "responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`"
     }
}

Paso 3: El conector envía el evento de detección del dispositivo

Envíe una solicitud POST a /connector-event/{your_connector_id} con la siguiente carga útil JSON:

AWS API - /SendConnectorEvent
URI – POST /connector-event/{your_connector_id}
{
   "UserId": "6109342",
   "Operation": "DEVICE_DISCOVERY",
   "OperationVersion": "1.0",
   "StatusCode": 200,
   "DeviceDiscoveryId": "12345678",
   "ConnectorId": "Your_connector_Id",
   "Message": "Device discovery for discovery-job-id '12345678' successful",
   "Devices": [
        {
            "ConnectorDeviceId": "Your_Device_Id_1",
            "ConnectorDeviceName": "Your-Device-Name",
            "CapabilityReport": {
 	      		"nodeId":"1",
 			"version":"1.0.0",
  			"endpoints":[{
 				"id":"1",
 				"deviceTypes":["Camera"],
 				"clusters":[{
 					"id":"0x0006",
 					"revision":1,
 					"attributes":[{
 						"id":"0x0000",
 					}],
 					"commands":["0x00","0x01"],
 					"events":["0x00"]
 				}]
 			}]
 		}
        }
    ]
}

Complete la marca y el modelo de los dispositivos descubiertos

Su conector C2C puede incluir opcionalmente un DeviceMetadata objeto para cada dispositivo en DEVICE_DISCOVERY caso de indicar la marca y el modelo del dispositivo. A continuación, estos valores se devuelven en las ListManagedThingsrespuestas ListDiscoveredDevicesy.

Incluya un DeviceMetadata objeto en cada entrada y mapa del dispositivo:

  • DeviceMetadata.Brand(Cadena) → Brand

  • DeviceMetadata.Model(Cadena) → Model

En el siguiente ejemplo, se muestra una entrada de dispositivo que DeviceMetadata incluye:

{
    "ConnectorDeviceId": "Your_Device_Id_1",
    "ConnectorDeviceName": "Your-Device-Name",
    "CapabilityReport": { ... },
    "DeviceMetadata": {
        "Brand": "ExampleBrand",
        "Model": "ExampleModel-X1"
    }
}

Ambas teclas son cadenas que distinguen entre mayúsculas y minúsculas. Si omiteDeviceMetadata, omite una clave individual o proporciona un valor que no sea una cadena, el campo correspondiente no estará disponible cuando se recupere el dispositivo.

Construya una para el evento CapabilityReport DISCOVER_DEVICES

Como se ve en la estructura de eventos definida anteriormente, cada dispositivo registrado en un evento DISCOVER_DEVICES, que sirva como respuesta a una AWS.DiscoverDevices operación, necesitará describir las capacidades del dispositivo correspondiente. CapbilityReport A `CapabilityReport` indica las integraciones gestionadas de las capacidades de los dispositivos AWS IoT Device Management en un formato compatible con Matter.

Los campos obligatorios están en CapabilityReport

  • nodeId, String: identificador del nodo del dispositivo que contiene lo siguiente endpoints

  • version, String: versión de este nodo de dispositivo, establecida por el desarrollador del conector

  • endpoints, Lista<Cluster>: Lista de AWS implementaciones del modelo de datos de materia compatibles con este punto final del dispositivo.

    • id, String: identificador de punto final establecido por el desarrollador del conector

    • deviceTypes, Lista<String>: lista de los tipos de dispositivos que captura este terminal, es decir, «Cámara».

    • clusters, Lista<Cluster>: Lista de AWS implementaciones del modelo de datos de materia compatible con este punto final.

      • id, String: identificador de clúster según lo define el estándar Matter.

      • revision, Entero: número de revisión del clúster tal como se define en el estándar Matter.

      • attributes, Mapa<String, Object>: mapa de los identificadores de atributos y sus correspondientes valores de estado actual del dispositivo, con los identificadores y los valores válidos definidos por el estándar de la materia.

        • id, String: ID de atributo tal como se define en AWS las implementaciones del modelo de datos de materia.

        • value, Objeto: el valor actual del atributo definido por el ID del atributo. El tipo de «valor» puede cambiar en función del atributo. El value campo es opcional para cada atributo y solo debe incluirse si el conector lambda puede determinar el estado actual durante el descubrimiento.

      • commands, Lista<String>: lista de identificadores de comandos compatibles con este clúster, tal como se define en el estándar Matter.

      • events, List<String>: la lista de identificadores de eventos es compatible con este clúster, tal como se define en el estándar Matter.

Para ver la lista actual de capacidades compatibles y sus correspondientes AWS implementaciones del modelo de datos Matter, consulte la última versión de la documentación del modelo de datos.