View a markdown version of this page

Usa un connettore C2C () Cloud-to-Cloud - Integrazioni gestite per AWS IoT Device Management

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Usa un connettore C2C () Cloud-to-Cloud

Un connettore C2C gestisce la traduzione dei messaggi di richiesta e risposta e consente la comunicazione tra le integrazioni gestite e il cloud di un fornitore terzo. Facilita il controllo unificato su diversi tipi di dispositivi, piattaforme e protocolli, consentendo l'onboarding e la gestione di dispositivi di terze parti.

La procedura seguente elenca i passaggi per utilizzare il connettore C2C.

Passaggi per utilizzare il connettore C2C:

  1. CreateCloudConnector

    Configura un connettore per abilitare la comunicazione bidirezionale tra le integrazioni gestite e i cloud di fornitori di terze parti.

    Durante la configurazione del connettore, fornisci i seguenti dettagli:

    • Nome: scegli un nome descrittivo per il connettore.

    • Descrizione: Fornisci un breve riepilogo dello scopo e delle funzionalità del connettore.

    • AWS Lambda ARN: specifica l'Amazon Resource Name (ARN) della AWS Lambda funzione che alimenterà il connettore.

    Crea e distribuisci una AWS Lambda funzione che comunica con le API di fornitori terzi per creare un connettore. Successivamente, richiama l'CreateCloudConnectorAPI all'interno delle integrazioni gestite e fornisci la AWS Lambda funzione ARN per la registrazione. Assicurati che la AWS Lambda funzione sia implementata nello stesso AWS account in cui crei il connettore nelle integrazioni gestite. Ti verrà assegnato un ID connettore univoco per identificare l'integrazione.

    Esempio di richiesta e risposta 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"
}

    Flusso di creazione:

    Fase di creazione del connettore cloud
    Nota

    Utilizza le ListCloudConnectorsAPI GetCloudConnectorUpdateCloudConnector, DeleteCloudConnector, e secondo necessità per questa procedura.

  2. CreateConnectorDestination

    Configura Destinations per fornire le impostazioni e le credenziali di autorizzazione necessarie ai connettori per stabilire connessioni sicure con i cloud di fornitori di terze parti. Usa Destinations per registrare le tue credenziali di autorizzazione di terze parti con integrazioni gestite.

    Ora sono supportati due tipi di autorizzazione:

    • OAuth 2.0 - Per piattaforme che utilizzano l'autorizzazione OAuth (URL di autorizzazione, URL del token, credenziali del client)

    • GeneralAuthorization- Per piattaforme che utilizzano chiavi API, token bearer o qualsiasi meccanismo di autorizzazione diverso da OAuth

    Prerequisiti

    Prima di creare un, devi: ConnectorDestination

    • Chiama l'CreateCloudConnectorAPI per creare un connettore. L'ID restituito dalla funzione viene utilizzato nella chiamata CreateConnectorDestinationAPI API.

    • Per l'autorizzazione OAuth:

      • Recupera il file tokenUrl per la piattaforma di terze parti (per scambiare un AuthCode con un AccessToken)

      • Recupera il file authUrl per la piattaforma di terze parti (per l'autorizzazione dell'utente finale)

      • Memorizza il e in clientId clientSecret AWS Secrets Manager

    • Per GeneralAuthorization:

      • Archivia i tuoi materiali di autorizzazione (chiavi API, token al portatore, ecc.) in AWS Secrets Manager

      • Ogni materiale di autorizzazione necessita di un nome e di un riferimento a Secrets Manager

    Richiesta CreateConnectorDestination API di esempio (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"
}

    Richiesta CreateConnectorDestination API di esempio ()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"
}

    Principali differenze per GeneralAuthorization:

    • Nessun AuthType campo richiesto

    • Nessun SecretsManager campo di primo livello richiesto

    • Utilizza l'array AuthConfig.GeneralAuthorization.AuthMaterials

    • Ogni materiale di autenticazione ha un nome e il proprio riferimento Secrets Manager

    • Supporta più materiali di autenticazione per casi d'uso futuri

    Attualmente supporta ConnectorDestination anche OAuth e GeneralAuthorization insieme nel nostro. ConnectorDestination

    Flusso di creazione di destinazioni cloud:

    CreateConnectorDestination Fase di richiamo dell'API
    Nota

    Utilizzate le ListConnectorDestinationsAPI GetConnectorDestinationUpdateConnectorDestinationDeleteConnectorDestination,, e secondo necessità per questa procedura.

  3. CreateAccountAssociation

    Le associazioni rappresentano le relazioni tra gli account cloud di terze parti degli utenti finali e una destinazione del connettore. Dopo aver creato un'associazione e aver collegato gli utenti finali alle integrazioni gestite, i loro dispositivi sono accessibili tramite un ID di associazione univoco. Questa integrazione abilita tre funzioni chiave: scoperta dei dispositivi, invio di comandi e ricezione di eventi.

    Prerequisiti

    Prima di creare un AccountAssociation, è necessario completare quanto segue:

    Richiesta CreateAccountAssociation API di esempio (OAuth):

    Request:

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

{
    "Id":"string"
}

    Richiesta CreateAccountAssociation API di esempio ()GeneralAuthorization:

    Request:

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

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

    Principali differenze per GeneralAuthorization:

    • Include il GeneralAuthorization.AuthMaterialName campo

    • Fa riferimento a uno dei materiali di autenticazione definiti nel ConnectorDestination

    • Nessun URL di autorizzazione OAuth nella risposta

    Nota

    Utilizza le ListAccountAssociationsAPI GetAccountAssociationUpdateAccountAssociation, DeleteAccountAssociation, e secondo necessità per questa procedura.

    An AccountAssociationha uno stato su cui viene richiesta una richiesta e delle API. GetAccountAssociationListAccountAssociations Queste API mostrano lo stato dell'Associazione. L'StartAccountAssociationRefreshAPI consente l'aggiornamento di uno AccountAssociationstato alla scadenza del relativo token di aggiornamento.

  4. Individuazione dei dispositivi

    Ogni elemento gestito è collegato a dettagli specifici del dispositivo, come il numero di serie e un modello di dati. Il modello di dati descrive la funzionalità del dispositivo, indicando se si tratta di una lampadina, un interruttore, un termostato o un altro tipo di dispositivo. Esistono due flussi di lavoro per scoprire dispositivi di terze parti e creare ManagedThings: il flusso di scoperta tradizionale e il flusso di scoperta preintegrato.

    1. Opzione 1: Device Discovery Flow tradizionale

      Utilizza questo flusso di lavoro quando non conosci in anticipo gli ID dei dispositivi del connettore. Questo flusso rileva tutti i dispositivi associati a un account e consente di selezionare i dispositivi da integrare.

      1. Chiama StartDeviceDiscoveryl'API per avviare il processo di individuazione dei dispositivi.

        Esempio di richiesta e risposta StartDeviceDiscovery API:

        Request:

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

Response:

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

      2. Richiama GetDeviceDiscoveryl'API per verificare lo stato del processo di scoperta.

      3. Invoca ListDiscoveredDevicesl'API per elencare i dispositivi rilevati.

        Esempio di richiesta e risposta 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. Richiama l'CreateManagedThingAPI per selezionare i dispositivi dall'elenco di rilevamento da importare nelle integrazioni gestite.

        Esempio di richiesta e risposta CreateManagedThing 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 GetManagedThingl'API per visualizzare questa nuova creazionemanagedThing. Lo stato saràUNASSOCIATED.

      6. Invoca RegisterAccountAssociationl'API per associarlo managedThing a uno specificoaccountAssociation. Al termine di un'RegisterAccountAssociationAPI di successo, lo ACTIVATED stato managedThing cambia.

        Esempio di richiesta e risposta RegisterAccountAssociation API:

        Request:

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

Response:

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

    2. Opzione 2: Pre-onboarded Device Discovery Flow

      Utilizza questo flusso di lavoro quando conosci già gli ID dei dispositivi del connettore prima dell'onboarding. Questo flusso è utile per i dispositivi preconfigurati o quando si desidera integrare in modo selettivo dispositivi specifici da un set più ampio. Questo approccio riduce il numero di chiamate API necessarie per registrare e attivare completamente i dispositivi.

      Importante

      Per utilizzare il flusso di cloud discovery preinstallato, è necessario conoscere il connectorDeviceId (identificatore del dispositivo del connettore) prima di iniziare il processo di onboarding del dispositivo. Questo identificatore viene ottenuto dalla piattaforma del fornitore terzo o durante il provisioning del dispositivo.

      1. Richiama l'CreateManagedThingAPI con PRE_ONBOARDED_CLOUD il tipo di materiale di autenticazione. Questo crea un ManagedThing in PRE_ASSOCIATED uno stato con più associazioni di account.

        Esempio di richiesta e risposta 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

        Il AuthenticationMaterial formato per i dispositivi preintegrati consente di specificare uno o più ID di associazione di account. CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:...

      2. (Facoltativo) Richiama l'GetManagedThingAPI per verificare che ManagedThing sia attivo. PRE_ASSOCIATED

      3. Chiama StartDeviceDiscoveryl'API con il connectorDeviceIdList parametro per scoprire solo i dispositivi preinstallati.

        Esempio di richiesta StartDeviceDiscovery API con connettore: 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
}

        Quando viene utilizzatoconnectorDeviceIdList, il processo di rilevamento restituisce solo i dispositivi che corrispondono agli ID dei dispositivi del connettore specificati. Il connettore invierà un DEVICE_DISCOVERY evento tramite SendConnectorEventle informazioni sul dispositivo rilevato.

      4. Una volta completata con successo la scoperta, Managed Integrations registra automaticamente i ManagedThings preinstallati nelle associazioni di account associate. ManagedThing passa dallo stato allo stato. PRE_ASSOCIATED ACTIVATED

        Nota

        Se la registrazione automatica fallisce e ManagedThing rimane DISCOVERED attivo, puoi richiamare manualmente l'RegisterAccountAssociationAPI come riserva per completare il processo di registrazione.

      5. (Facoltativo) Invoke GetManagedThingAPI per verificare che ManagedThing sia ora in stato. ACTIVATED

  5. Invia un comando al dispositivo di terze parti

    Per controllare un dispositivo appena installato, utilizza l'SendManagedThingCommandAPI, con l'Association ID creato in precedenza e un'azione di controllo basata sulla funzionalità supportata dal dispositivo. Il connettore utilizza le credenziali memorizzate dal processo di collegamento dell'account per autenticarsi con il cloud di terze parti e richiamare la chiamata API pertinente per l'operazione.

    Nota

    Infatti GeneralAuthorization, il connettore recupera il materiale di autorizzazione (chiave API, token bearer, ecc.) da Secrets Manager utilizzando il nome del materiale di autorizzazione specificato in. AccountAssociation

    Esempio di richiesta e risposta 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"
}

    Invia il comando al flusso di dispositivi di terze parti:

    Invia comando a un dispositivo di terze parti

  6. Connector invia eventi alle integrazioni gestite

    L'SendConnectorEventAPI acquisisce quattro tipi di eventi dal connettore alle integrazioni gestite, rappresentati dai seguenti valori enum per il parametro Operation Type:

    • DEVICE_COMMAND_RESPONSE: la risposta asincrona che il connettore invia in risposta a un comando.

    • DEVICE_DISCOVERY: in risposta a un processo di rilevamento dei dispositivi, il connettore invia l'elenco dei dispositivi rilevati alle integrazioni gestite, utilizza l'API. SendConnectorEvent

    • DEVICE_EVENT: invia gli eventi del dispositivo ricevuti.

    • DEVICE_COMMAND_REQUEST: richieste di comando avviate dal dispositivo. Ad esempio, i flussi di lavoro WebRTC.

    Il connettore può anche inoltrare gli eventi del dispositivo utilizzando l'SendConnectorEventAPI, con un parametro opzionale. userId

    Nota

    Per GeneralAuthorization: quando si utilizza GeneralAuthorization, per ogni ARN e versione di Secrets, l'UserID deve essere univoco.

    • Per gli eventi relativi ai dispositivi con un: userId

      Esempio di richiesta e risposta SendConnectorEvent API:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    • Per gli eventi relativi ai dispositivi senzauserId:

      Esempio di richiesta e risposta SendConnectorEvent API:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    Per rimuovere il collegamento tra una determinata associazione managedThing e un'associazione di account, utilizza il meccanismo di annullamento della registrazione:

    Esempio di richiesta e risposta DeregisterAccountAssociation API:

    Request:

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

Response:

HTTP/1.1 200 // Empty body

    Invia flusso di eventi:

    Invia flusso di eventi

  7. Aggiorna lo stato del connettore su «In elenco» per renderlo visibile agli altri clienti delle integrazioni gestite

    Per impostazione predefinita, i connettori sono privati e visibili solo all' AWS account che li ha creati. Puoi scegliere di rendere visibile un connettore agli altri clienti di Managed Integrations.

    Per condividere il connettore con altri utenti, utilizza l'opzione Rendi visibile nella Console di gestione AWS pagina dei dettagli del connettore per inviare il tuo ID del connettore AWS per la revisione. Una volta approvato, il connettore è disponibile per tutti gli utenti delle integrazioni gestite all'interno dello stesso Regione AWS dispositivo. Inoltre, puoi limitare l'accesso a ID AWS account specifici modificando la politica di accesso sulla funzione associata AWS Lambda al connettore. Per garantire che il connettore sia utilizzabile da altri clienti, gestisci le autorizzazioni di accesso IAM sulla tua funzione Lambda da AWS altri account al tuo connettore visibile.

    Consulta i Servizio AWS termini e le politiche della tua organizzazione che regolano la condivisione dei connettori e le autorizzazioni di accesso prima di rendere i connettori visibili agli altri clienti delle integrazioni gestite.