View a markdown version of this page

Utilice un conector C2C (Cloud-to-Cloud) - Integraciones gestionadas para AWS IoT Device Management

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.

Utilice un conector C2C (Cloud-to-Cloud)

Un conector C2C gestiona la traducción de los mensajes de solicitud y respuesta y permite la comunicación entre las integraciones gestionadas y la nube de un proveedor externo. Facilita el control unificado de diferentes tipos de dispositivos, plataformas y protocolos, lo que permite incorporar y gestionar dispositivos de terceros.

En el siguiente procedimiento se enumeran los pasos para utilizar el conector C2C.

Pasos para utilizar el conector C2C:

  1. CreateCloudConnector

    Configure un conector para permitir la comunicación bidireccional entre sus integraciones gestionadas y las nubes de proveedores externos.

    Al configurar el conector, proporcione los siguientes detalles:

    • Nombre: elija un nombre descriptivo para el conector.

    • Descripción: proporcione un breve resumen del propósito y las capacidades del conector.

    • AWS Lambda ARN: especifique el nombre de recurso de Amazon (ARN) de la AWS Lambda función que alimentará el conector.

    Cree e implemente una AWS Lambda función que se comunique con las API de otros proveedores para crear un conector. A continuación, llame a la CreateCloudConnectorAPI dentro de las integraciones gestionadas y proporcione la AWS Lambda función ARN para el registro. Asegúrese de que la AWS Lambda función esté implementada en la misma AWS cuenta en la que creó el conector en las integraciones administradas. Se le asignará un ID de conector único para identificar la integración.

    Ejemplo de solicitud y respuesta de la CreateCloudConnector API:

    Request:

{
    "Name": "CreateCloudConnector",
    "Description": "Testing for C2C",
    "EndpointType": "LAMBDA",
    "EndpointConfig": {
        "lambda": {
            "arn": "arn:aws:lambda:us-east-1:xxxxxx:function:TestingConnector"
        }
    },
    "ClientToken": "abc"
}

Response:

{
    "Id": "string"
}

    Flujo de creación:

    Fase de creación del conector a la nube
    nota

    Utilice las ListCloudConnectorsAPI GetCloudConnectorUpdateCloudConnector, DeleteCloudConnector, y según sea necesario para este procedimiento.

  2. CreateConnectorDestination

    Configure los destinos para proporcionar los ajustes y las credenciales de autorización que los conectores necesitan para establecer conexiones seguras con nubes de proveedores externos. Usa Destinations para registrar tus credenciales de autorización de terceros en las integraciones gestionadas.

    Ahora se admiten dos tipos de autorización:

    • OAuth 2.0: para plataformas que utilizan la autorización de OAuth (URL de autorización, URL del token, credenciales de cliente)

    • GeneralAuthorization- Para plataformas que utilizan claves de API, tokens portadores o cualquier mecanismo de autorización que no sea de OAuth

    Requisitos previos

    Antes de crear una ConnectorDestination, debes:

    • Llame a la CreateCloudConnectorAPI para crear un conector. El ID que devuelve la función se utiliza en la llamada a la CreateConnectorDestinationAPI de la API.

    • Para la autorización de OAuth:

      • Recupera el código de autenticación tokenUrl para una plataforma de terceros (para cambiar un AuthCode por un AccessToken)

      • Recupera el de la plataforma de terceros (authUrlpara la autorización del usuario final)

      • Guarde la arena clientId en clientSecret AWS Secrets Manager

    • Para GeneralAuthorization:

      • Guarde sus materiales de autorización (claves de API, fichas portadoras, etc.) en AWS Secrets Manager

      • Cada material de autorización necesita un nombre y una referencia de Secrets Manager

    Ejemplo de solicitud CreateConnectorDestination de API (OAuth):

    Request:

{
    "Name": "CreateConnectorDestination",
    "Description": "CreateConnectorDestination",
    "AuthType": "OAUTH",
    "AuthConfig": {
        "oAuth": {
            "authUrl": "https://xxxx.com/oauth2/authorize",
            "tokenUrl": "https://xxxx/oauth2/token",
            "scope": "testScope",
            "tokenEndpointAuthenticationScheme": "HTTP_BASIC",
            "oAuthCompleteRedirectUrl": "about:blank",
            "proactiveRefreshTokenRenewal": {
                "enabled": false,
                "DaysBeforeRenewal": 30
            }
        }
    },
    "CloudConnectorId": "<connectorId>",
    "SecretsManager": {
        "arn": "arn:aws:secretsmanager:*****:secret:*******",
        "versionId": "********"
    },
    "ClientToken": "***"
}

Response:

{
    "Id":"string"
}

    Ejemplo de solicitud CreateConnectorDestination de API ()GeneralAuthorization:

    Request:

{
    "Name": "CreateConnectorDestination",
    "Description": "GeneralAuthorization test destination",
    "AuthConfig": {
        "GeneralAuthorization": {
            "AuthMaterials": [
                {
                    "AuthMaterialName": "AuthKey1",
                    "SecretsManager": {
                        "arn": "arn:aws:secretsmanager:*****:secret:*******",
                        "versionId": "********"
                    }
                }
            ]
        }
    },
    "CloudConnectorId": "<connectorId>",
    "ClientToken": "***"
}

Response:

{
    "Id": "string"
}

    Diferencias clave para GeneralAuthorization:

    • No se requiere ningún AuthType campo

    • No se requiere ningún SecretsManager campo de nivel superior

    • Utiliza una matriz AuthConfig.GeneralAuthorization.AuthMaterials

    • Cada material de autenticación tiene un nombre y su propia referencia a Secrets Manager.

    • Soporta múltiples materiales de autenticación para futuros casos de uso

    Actualmente, ConnectorDestination también es compatible con OAuth y, GeneralAuthorization juntos, en nuestro. ConnectorDestination

    Flujo de creación de destinos en la nube:

    CreateConnectorDestination Fase de invocación de la API
    nota

    Utilice las ListConnectorDestinationsAPI GetConnectorDestinationUpdateConnectorDestination, DeleteConnectorDestination, y según sea necesario para este procedimiento.

  3. CreateAccountAssociation

    Las asociaciones representan las relaciones entre las cuentas en la nube de terceros de los usuarios finales y el destino de un conector. Tras crear una asociación y vincular a los usuarios finales a las integraciones gestionadas, se puede acceder a sus dispositivos a través de un identificador de asociación único. Esta integración permite tres funciones clave: detectar dispositivos, enviar comandos y recibir eventos.

    Requisitos previos

    Antes de crear una AccountAssociation, debe completar lo siguiente:

    Ejemplo de solicitud CreateAccountAssociation de API (OAuth):

    Request:

{
    "Name": "CreateAccountAssociation",
    "Description": "CreateAccountAssociation",
    "ConnectorDestinationId": "<destinationId>",
    "ClientToken": "***"
}
        
Response:

{
    "Id":"string"
}

    Ejemplo de solicitud CreateAccountAssociation de API ()GeneralAuthorization:

    Request:

{
    "Name": "CreateAccountAssociation",
    "Description": "GeneralAuthorization test account association",
    "GeneralAuthorization": {
        "AuthMaterialName": "AuthKey1"
    },
    "ConnectorDestinationId": "<destinationId>",
    "ClientToken": "***"
}
        
Response:

{
    "AccountAssociationId": "string",
    "Arn": "string",
    "AssociationState": "ASSOCIATION_SUCCEEDED"
}

    Diferencias clave para GeneralAuthorization:

    • Incluye un GeneralAuthorization.AuthMaterialName campo

    • Hace referencia a uno de los materiales de autenticación definidos en el ConnectorDestination

    • No hay una URL de autorización de OAuth en la respuesta

    nota

    Utilice las ListAccountAssociationsAPI GetAccountAssociation, UpdateAccountAssociationDeleteAccountAssociation, y según sea necesario para este procedimiento.

    An AccountAssociationtiene un estado desde el que se consulta GetAccountAssociationy ListAccountAssociationslas API. Estas API muestran el estado de la Asociación. La StartAccountAssociationRefreshAPI permite actualizar un AccountAssociationestado cuando su token de actualización caduca.

  4. Descubrimiento de dispositivos

    Cada elemento gestionado está vinculado a detalles específicos del dispositivo, como su número de serie y un modelo de datos. El modelo de datos describe la funcionalidad del dispositivo e indica si se trata de una bombilla, un interruptor, un termostato u otro tipo de dispositivo. Existen dos flujos de trabajo para descubrir dispositivos de terceros y crear ManagedThings: el flujo de descubrimiento tradicional y el flujo de descubrimiento preincorporado.

    1. Opción 1: flujo de descubrimiento de dispositivos tradicional

      Utilice este flujo de trabajo cuando no conozca de antemano los ID de los dispositivos conectores. Este flujo descubre todos los dispositivos asociados a una cuenta y te permite seleccionar los dispositivos que deseas incorporar.

      1. Llama a la StartDeviceDiscoveryAPI para iniciar el proceso de descubrimiento de dispositivos.

        Ejemplo de solicitud y respuesta de la StartDeviceDiscovery API:

        Request:

{
    "DiscoveryType": "CLOUD",
    "AccountAssociationId": "*****",
    "ClientToken": "abc"
}

Response:

{
    "Id": "string",
    "StartedAt": number
}

      2. Invoca la GetDeviceDiscoveryAPI para comprobar el estado del proceso de descubrimiento.

      3. Invoque la ListDiscoveredDevicesAPI para enumerar los dispositivos descubiertos.

        Ejemplo de solicitud y respuesta de la ListDiscoveredDevices API:

        Request:

//Empty body

Response:

{
    "Items": [
    {
      "Brand": "string",
      "ConnectorDeviceId": "string",
      "ConnectorDeviceName": "string",
      "DeviceTypes": [ "string" ],
      "DiscoveredAt": number,
      "ManagedThingId": "string",
      "Model": "string",
      "Modification": "string"
    }
],
    "NextToken": "string"
}

      4. Invoca la CreateManagedThingAPI para seleccionar los dispositivos de la lista de detección que se van a importar a las integraciones gestionadas.

        Ejemplo de solicitud y CreateManagedThing respuesta de API:

        Request:
              
{
    "Role": "DEVICE",
    "AuthenticationMaterial": "CLOUD:<deviceDiscoveryId>:<connectorDeviceId>",
    "AuthenticationMaterialType": "DISCOVERED_DEVICE",
    "Name": "sample-device-name",
    "ClientToken": "xxx"
}

Response:

{
   "Arn": "string", // This is the ARN of the managedThing
   "CreatedAt": number,
   "Id": "string" 
}

      5. Invoca la GetManagedThingAPI para ver lo que acabas de crearmanagedThing. El estado será. UNASSOCIATED

      6. Invoca RegisterAccountAssociationla API para asociarla managedThing a una específicaaccountAssociation. Al final de una RegisterAccountAssociationAPI correcta, el ACTIVATED estado managedThing cambia.

        Ejemplo de solicitud y respuesta de la RegisterAccountAssociation API:

        Request:

{
    "AccountAssociationId": "string",
    "DeviceDiscoveryId": "string",
    "ManagedThingId": "string"
}

Response:

{
    "AccountAssociationId": "string",
    "DeviceDiscoveryId": "string",
    "ManagedThingId": "string"
}

    2. Opción 2: Flujo de descubrimiento de Pre-onboarded dispositivos

      Utilice este flujo de trabajo cuando ya conozca los ID de los dispositivos conectores antes de incorporarlos. Este flujo resulta útil para dispositivos aprovisionados previamente o cuando se desea incorporar de forma selectiva dispositivos específicos de un conjunto más grande. Este enfoque reduce la cantidad de llamadas a la API necesarias para registrar y activar completamente los dispositivos.

      importante

      Para utilizar el flujo de descubrimiento en la nube preincorporado, debe conocer el connectorDeviceId (identificador del dispositivo conector) antes de iniciar el proceso de incorporación del dispositivo. Este identificador se obtiene de la plataforma del proveedor externo o durante el aprovisionamiento del dispositivo.

      1. Invoque la CreateManagedThingAPI con el tipo de material PRE_ONBOARDED_CLOUD de autenticación. Esto crea un ManagedThing en PRE_ASSOCIATED estado con múltiples asociaciones de cuentas.

        Ejemplo de solicitud y respuesta de CreateManagedThing API ()Pre-onboarded:

        Request:
              
{
    "Role": "DEVICE",
    "AuthenticationMaterial": "CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>",
    "AuthenticationMaterialType": "PRE_ONBOARDED_CLOUD",
    "Name": "pre-onboarded-device-name",
    "ClientToken": "xxx"
}

Response:

{
   "Arn": "string", // This is the ARN of the managedThing
   "CreatedAt": number,
   "Id": "string" 
}
        nota

        El AuthenticationMaterial formato de los dispositivos preintegrados permite especificar uno o más identificadores de asociación de cuentas. CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:...

      2. (Opcional) Invoca la GetManagedThingAPI para comprobar que ManagedThing está en buen estado. PRE_ASSOCIATED

      3. Llama a la StartDeviceDiscoveryAPI con el connectorDeviceIdList parámetro para descubrir solo los dispositivos preintegrados.

        Ejemplo de solicitud de StartDeviceDiscovery API con conector: DeviceIdList

        Request:

{
    "DiscoveryType": "CLOUD",
    "AccountAssociationId": "*****",
    "ConnectorDeviceIdList": [
        "connector-device-id-1",
        "connector-device-id-2",
        "connector-device-id-3"
    ],
    "ClientToken": "abc"
}

Response:

{
    "Id": "string",
    "StartedAt": number
}

        Cuando se usaconnectorDeviceIdList, el proceso de descubrimiento devuelve solo los dispositivos que coinciden con los ID de dispositivo del conector especificados. El conector enviará un DEVICE_DISCOVERY evento SendConnectorEventcon la información del dispositivo descubierto.

      4. Una vez que el descubrimiento se complete correctamente, las integraciones gestionadas registran automáticamente los ManagedThings preintegrados en sus asociaciones de cuentas asociadas. ManagedThing pasa de un estado a otro. PRE_ASSOCIATED ACTIVATED

        nota

        Si el registro automático falla y ManagedThing permanece en DISCOVERED estado, puedes invocar manualmente la RegisterAccountAssociationAPI como alternativa para completar el proceso de registro.

      5. (Opcional) Invoca la GetManagedThingAPI para comprobar que el ManagedThing está ahora en estado. ACTIVATED

  5. Envía un comando al dispositivo de terceros

    Para controlar un dispositivo recién incorporado, usa la SendManagedThingCommandAPI, con el ID de asociación creado anteriormente y una acción de control basada en la capacidad compatible con el dispositivo. El conector utiliza las credenciales almacenadas en el proceso de vinculación de cuentas para autenticarse en la nube de terceros e invocar la llamada a la API correspondiente para la operación.

    nota

    Para GeneralAuthorization ello, el conector recupera el material de autorización (clave de API, token de portador, etc.) de Secrets Manager utilizando el nombre del material de autorización especificado en. AccountAssociation

    Ejemplo de solicitud y respuesta de la SendManagedThingCommand API:

    Request:

{
    "AccountAssociationId": "string",
    "ConnectorAssociationId": "string",
    "Endpoints": [ 
       { 
          "capabilities": [ 
             { 
                "actions": [ 
                   { 
                      "actionTraceId": "string",
                      "name": "string",
                      "parameters": JSON value,
                      "ref": "string"
                   }
                ],
                "id": "string",
                "name": "string",
                "version": "string"
             }
          ],
          "endpointId": "string"
       }
    ]
}
        
Response:
        
{
   "TraceId": "string"
}

    Envía el comando al flujo de dispositivos de terceros:

    Enviar el comando a un dispositivo de terceros

  6. El conector envía los eventos a las integraciones gestionadas

    La SendConnectorEventAPI captura cuatro tipos de eventos desde el conector hasta las integraciones gestionadas, representados por los siguientes valores de enumeración para el parámetro Operation Type:

    • DEVICE_COMMAND_RESPONSE: la respuesta asíncrona que envía el conector en respuesta a un comando.

    • DEVICE_DISCOVERY: en respuesta a un proceso de descubrimiento de dispositivos, el conector envía la lista de dispositivos detectados a las integraciones gestionadas y utiliza la API. SendConnectorEvent

    • DEVICE_EVENT: envía los eventos del dispositivo recibidos.

    • DEVICE_COMMAND_REQUEST: Solicitudes de comando iniciadas desde el dispositivo. Por ejemplo, los flujos de trabajo de WebRTC.

    El conector también puede reenviar eventos del dispositivo mediante la SendConnectorEventAPI, con un parámetro opcionaluserId.

    nota

    Para GeneralAuthorization: Al usar GeneralAuthorization, para cada ARN y versión de Secrets, el USeriD debe ser único.

    • Para eventos de dispositivos con: userId

      Ejemplo de solicitud y respuesta de SendConnectorEvent API:

      Request:

{
    "UserId": "*****",
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "****",
    "ConnectorDeviceId": "***",
    "TraceId": "***",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            .....
            }
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}

    • Para eventos de dispositivos sinuserId:

      Ejemplo de solicitud y respuesta de SendConnectorEvent API:

      Request:

{
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "*****",
    "ConnectorDeviceId": "****",
    "TraceId": "****",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            ....
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}

    Para eliminar el vínculo entre una asociación de cuentas concreta managedThing y una asociación de cuentas, utiliza el mecanismo de anulación del registro:

    Ejemplo de solicitud y respuesta de la DeregisterAccountAssociation API:

    Request:

{
    "AccountAssociationId": "****",
    "ManagedThingId": "****"
}

Response:

HTTP/1.1 200 // Empty body

    Enviar flujo de eventos:

    Enviar flujo de eventos

  7. Actualice el estado del conector a «Listado» para que otros clientes de integraciones gestionadas lo vean

    De forma predeterminada, los conectores son privados y solo los puede ver la AWS cuenta que los creó. Puede optar por hacer que un conector sea visible para otros clientes de integraciones gestionadas.

    Para compartir su conector con otros usuarios, utilice la opción Hacer visible en la Consola de administración de AWS página de detalles del conector para enviar su ID de conector AWS para su revisión. Una vez aprobado, el conector estará disponible para todos los usuarios de integraciones gestionadas al mismo tiempo Región de AWS. Además, puede restringir el acceso a identificadores de AWS cuenta específicos modificando la política de acceso de la AWS Lambda función asociada al conector. Para garantizar que otros clientes puedan utilizar su conector, gestione los permisos de acceso de IAM en su función Lambda desde AWS otras cuentas hasta su conector visible.

    Revise los Servicio de AWS términos y las políticas de su organización que rigen los permisos de acceso y uso compartido de conectores antes de hacer que los conectores estén visibles para otros clientes de integraciones gestionadas.