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à.
# Cloud-to-Cloud Connettori (C2C)
Un cloud-to-cloud connettore consente di creare e facilitare la comunicazione bidirezionale tra dispositivi di terze parti e. AWS
**Topics**
+ [Cos'è un connettore cloud-to-cloud (C2C)?](#concepts-what-is-c2c-connector)
+ [Cos'è il catalogo dei connettori C2C?](#concepts-connector-catalog)
+ [AWS Lambda funziona come connettori C2C](#lambda-connector)
+ [Workflow del connettore per le integrazioni gestite](#c2c-workflow)
+ [Linee guida per l'utilizzo di un connettore C2C () cloud-to-cloud](#c2c-cloud-connector-disclaimer)
+ [Crea un connettore C2C (Cloud-to-Cloud)](concepts-building-connector.md)
+ [Usa un connettore C2C (Cloud-to-Cloud)](use-c2c-create-cloud-connector.md)
## Cos'è un connettore cloud-to-cloud (C2C)?
Un cloud-to-cloud connettore è un pacchetto software predefinito che lo collega in modo sicuro Cloud AWS all'endpoint di un provider cloud di terze parti. Utilizzando il connettore C2C, i fornitori di soluzioni possono sfruttare le integrazioni gestite per AWS IoT Device Management per controllare i dispositivi collegati a cloud di terze parti.
Le integrazioni gestite includono un catalogo di connettori in cui AWS i clienti possono visualizzare e selezionare i connettori con cui desiderano integrarsi. Per ulteriori informazioni, consulta [Cos'è il catalogo dei connettori C2C?](#concepts-connector-catalog)
Le integrazioni gestite richiedono che ogni connettore sia implementato come funzione. AWS Lambda
## Cos'è il catalogo dei connettori C2C?
Il catalogo di integrazioni gestite per AWS IoT Device Management connector è una raccolta di connettori C2C che facilitano la comunicazione bidirezionale tra le integrazioni gestite per AWS IoT Device Management e un provider cloud di terze parti. È possibile visualizzare i connettori in o in. Console di gestione AWS AWS CLI
**Per utilizzare la console per visualizzare il catalogo dei connettori di integrazioni gestite**
1. Apri la console di [integrazioni gestite](https://console.aws.amazon.com/iot/home#/managed-integrations/intro)
1. Nel riquadro di navigazione a sinistra, scegli Integrazioni **gestite**
1. **Nel riquadro di navigazione a sinistra della console delle integrazioni gestite, scegli Catalogo.**
## AWS Lambda funziona come connettori C2C
Ogni funzione Lambda del connettore C2C traduce e trasporta comandi ed eventi tra le integrazioni gestite e le azioni corrispondenti su piattaforme di terze parti. Per ulteriori informazioni su Lambda, consulta [What](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) is. AWS Lambda
Ad esempio, supponiamo che un utente finale possieda una lampadina intelligente prodotta da un OEM terzo. Con un connettore C2C, un utente finale può emettere un comando per accendere o spegnere questa luce tramite una piattaforma di integrazioni gestita. Questo comando verrà quindi inoltrato alla funzione Lambda ospitata nel connettore, che tradurrà la richiesta in una chiamata API verso la piattaforma di terze parti per accendere o spegnere il dispositivo.
La funzione Lambda è richiesta quando si chiama l'`CreateCloudConnector`API. Il codice distribuito nella funzione Lambda deve implementare tutte le interfacce e le funzionalità menzionate in. [Crea un connettore C2C (Cloud-to-Cloud)](concepts-building-connector.md)
## Workflow del connettore per le integrazioni gestite
Gli sviluppatori devono registrare i connettori C2C con integrazioni gestite per. AWS IoT Device Management Questo processo di registrazione crea una risorsa di connettori logici a cui i clienti possono accedere per utilizzare il connettore.
**Nota**
Un connettore C2C è un insieme di metadati creati all'interno di integrazioni gestite per AWS IoT Device Management per descrivere il connettore.
Il diagramma seguente illustra il ruolo di un connettore C2C nell'invio di un comando dall'applicazione mobile a un dispositivo connesso al cloud. Il connettore C2C funge da livello di traduzione tra le integrazioni gestite per AWS IoT Device Management e una piattaforma cloud di terze parti.
![\[Workflow del connettore\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/app-to-oem-device-workflow.png)
## Linee guida per l'utilizzo di un connettore C2C () cloud-to-cloud
Qualsiasi connettore C2C che crei è un tuo contenuto e qualsiasi connettore C2C creato da un altro cliente a cui accedi è contenuto di terze parti. AWS non crea o gestisce alcun connettore C2C come parte di integrazioni gestite.
Puoi condividere i tuoi connettori C2C con altri clienti di integrazioni gestite. In tal caso, autorizzi in AWS qualità di fornitore di servizi a elencare tali connettori C2C e le relative informazioni di contatto sulla AWS console e comprendi che altri clienti potrebbero contattarti. AWS Sei l'unico responsabile della concessione ai clienti dell'accesso ai tuoi connettori C2C e di tutte le condizioni che regolano l'accesso di un altro AWS cliente ai tuoi connettori C2C.
# Crea un connettore C2C (Cloud-to-Cloud)
Le seguenti sezioni illustrano i passaggi per creare un connettore C2C (Cloud-to-Cloud) per integrazioni gestite per AWS IoT Device Management.
**Topics**
+ [Prerequisiti](#c2c-connector-prerequisites)
+ [Requisiti del connettore C2C](#c2c-connector-requirements)
+ [OAuth Requisiti 2.0 per il collegamento degli account](concepts-account-linking.md)
+ [Implementa le operazioni di interfaccia del connettore C2C](connector-operations-overview.md)
+ [Invoca il tuo connettore C2C](allow-iot-smart-home.md)
+ [Aggiungi le autorizzazioni al tuo ruolo IAM](adding-permissions-to-iam-role.md)
+ [Testa manualmente il tuo connettore C2C](manually-testing-connector.md)
## Prerequisiti
Prima di creare un connettore C2C (Cloud-to-Cloud), è necessario quanto segue:
+ E Account AWS per ospitare il connettore C2C e registrarlo tramite integrazioni gestite. [Per ulteriori informazioni, consulta Creare un. Account AWS](https://docs.aws.amazon.com//accounts/latest/reference/manage-acct-creating.html)
+ Quando crei il connettore, hai bisogno di determinate autorizzazioni IAM. Per utilizzare nuovamente il plugin
+ Assicurati che i provider cloud di terze parti a cui è destinato il connettore supportino l'autorizzazione OAuth 2.0. Per ulteriori informazioni, consulta [OAuth Requisiti 2.0 per il collegamento degli account](concepts-account-linking.md).
Inoltre, per testare il connettore, lo sviluppatore del connettore deve disporre di quanto segue:
+ Un ID client dal cloud di terze parti da associare al connettore C2C
+ Un client segreto proveniente dal cloud di terze parti da associare al connettore C2C
+ Un URL di OAuth autorizzazione 2.0
+ Un URL con token OAuth 2.0
+ Qualsiasi chiave API richiesta dall'API di terze parti
+ Qualsiasi chiave API richiesta dalla registrazione o dall'elenco di autorizzazioni API di terze parti per l'URL di OAuth callback ospitato da. AWS Alcune terze parti consentono esplicitamente di inserire un URL di OAuth reindirizzamento nell'elenco, mentre altre dispongono di un flusso di lavoro in cui gli utenti possono accedere e registrare l'URL. OAuth Rivolgiti alla terza parte specifica per capire cosa è necessario per consentire l'inserimento nell'elenco degli endpoint di reindirizzamento delle integrazioni gestite OAuth
### Autorizzazioni richieste
Quando crei il connettore, hai bisogno di determinate autorizzazioni IAM. Oltre alle `iotmanagedintegrations:` autorizzazioni per le azioni, sono necessarie le seguenti autorizzazioni:
+ [CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html), [CreateConnectorDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html), e [GetAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetAccountAssociation.html), richiede [StartAccountAssociationRefresh](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartAccountAssociationRefresh.html)`secretsmanager:GetSecretValue`
+ [CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html) richiede `lambda:Invoke`
Per ulteriori informazioni su `iotmanagedintegrations:` autorizzazioni e azioni, consulta [Azioni definite dalle integrazioni AWS gestite](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiotmanagedintegrations.html#awsiotmanagedintegrations-actions-as-permissions)
## Requisiti del connettore C2C
Il [connettore C2C](concepts-c2c-connector.md#concepts-what-is-c2c-connector) che sviluppi facilita la comunicazione bidirezionale tra le integrazioni gestite per AWS IoT Device Management e un cloud di fornitori terzi. Il connettore deve implementare interfacce per integrazioni gestite per AWS IoT Device Management per eseguire azioni per conto degli utenti finali. Queste interfacce forniscono la funzionalità per scoprire i dispositivi degli utenti finali, avviare i comandi dei dispositivi inviati da integrazioni gestite per AWS IoT Device Management e identificare gli utenti sulla base di un token di accesso. Per supportare le operazioni del dispositivo, il connettore deve gestire la traduzione dei messaggi di richiesta e risposta tra le integrazioni gestite per AWS IoT Device Management e la relativa piattaforma di terze parti.
**Di seguito sono riportati i requisiti per il connettore C2C:**
+ Il server di autorizzazione di terze parti deve essere conforme agli standard OAuth 2.0 e alle configurazioni elencate in. [OAuth requisiti di configurazione](concepts-account-linking.md#oauth-config-requirements)
+ Sarà necessario un connettore C2C per interpretare gli identificatori delle AWS implementazioni del Matter Data Model e deve emettere le risposte e gli eventi conformi alle implementazioni del Matter Data Model. AWS Per ulteriori informazioni, consulta [AWS implementazione del modello di dati Matter](matter-data-model.md)
+ Un connettore C2C deve essere in grado di chiamare le integrazioni gestite per AWS IoT Device Management APIs con autenticazione. `SigV4` Per gli eventi asincroni inviati con l' SendConnectorEvent API, le stesse Account AWS credenziali utilizzate per registrare il connettore devono essere utilizzate per firmare la richiesta correlata. SendConnectorEvent
+ Il connettore deve implementare le operazioni`AWS.ActivateUser`,`AWS.DiscoverDevices`, `AWS.SendCommand` e. `AWS.DeactivateUser`
+ Quando il connettore C2C riceve eventi di terze parti relativi alle risposte ai comandi del dispositivo o all'individuazione del dispositivo, deve inoltrarli alle integrazioni gestite con l'API. `SendConnectorEvent` Per ulteriori informazioni su questi eventi e sull'`SendConnectorEvent`API, consulta. [SendConnectorEvent](https://amazonaws.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)
**Nota**
L'`SendConnectorEvent`API fa parte dell'SDK per le integrazioni gestite e viene utilizzata al posto della creazione e della firma manuali delle richieste.
# OAuth Requisiti 2.0 per il collegamento degli account
Ogni connettore C2C si basa su un server di autorizzazione OAuth 2.0 per autenticare gli utenti finali. Tramite questo server, gli utenti finali collegano i propri account di terze parti alla piattaforma del dispositivo del cliente. Il collegamento dell'account è il primo passaggio richiesto da un utente finale per utilizzare i dispositivi supportati dal connettore C2C. Per ulteriori informazioni sui diversi ruoli nel collegamento degli account e OAuth nella versione 2.0, consulta. [Ruoli di collegamento degli account](roles-account-linking.md)
Sebbene il connettore C2C non richieda l'implementazione di una logica aziendale specifica per supportare il flusso di autorizzazione, il server di autorizzazione OAuth2 .0 associato al connettore C2C deve soddisfare i. [OAuth requisiti di configurazione](#oauth-config-requirements)
**Nota**
Le integrazioni gestite supportano AWS IoT Device Management solo la OAuth versione 2.0 con un flusso di codice di autorizzazione. Per ulteriori informazioni, consulta [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1).
Il collegamento degli account è un processo che consente alle integrazioni gestite e al connettore di accedere ai dispositivi dell'utente finale utilizzando un token di accesso. Questo token fornisce integrazioni gestite per AWS IoT Device Management con l'autorizzazione dell'utente finale, in modo che il connettore possa interagire con i dati dell'utente finale tramite chiamate API. Per ulteriori informazioni, consulta [Flusso di lavoro per il collegamento degli account](account-linking-flow.md).
Ti consigliamo di non registrare questi token sensibili in nessun registro. Se tuttavia sono archiviati nei log, ti consigliamo di utilizzare le politiche di protezione dei dati di CloudWatch Logs per mascherare i token contenuti nei log. Per ulteriori informazioni, consulta [Incremento della protezione dei dati di log sensibili con il mascheramento](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html).
Le integrazioni gestite per AWS IoT Device Management non ottengono direttamente un token di accesso, ma lo fanno tramite l'Authorization Code Grant Type. Innanzitutto, le integrazioni gestite per AWS IoT Device Management devono ottenere un codice di autorizzazione. Quindi scambia il codice con un token di accesso e un token di aggiornamento. Il token di aggiornamento viene utilizzato per richiedere un nuovo token di accesso alla scadenza del vecchio token di accesso. Se sia il token di accesso che il token di aggiornamento sono scaduti, è necessario eseguire nuovamente il flusso di collegamento degli account. È possibile farlo con l'operazione API. `StartAccountAssociationRefresh`
**Importante**
Il token di accesso emesso deve essere definito per utente, ma non per OAuth client. Il token non deve fornire l'accesso a tutti i dispositivi di tutti gli utenti del client.
Il server di autorizzazione deve eseguire una delle seguenti operazioni:
Emetti token di accesso che contengono un ID estraibile dell'utente finale (proprietario della risorsa), come un token JWT.
Restituisci l'ID dell'utente finale per ogni token di accesso emesso.
## OAuth requisiti di configurazione
La tabella seguente illustra i parametri richiesti dal server di OAuth autorizzazione per le integrazioni gestite per AWS IoT Device Management per eseguire il collegamento degli [account](account-linking-flow.md):
**OAuth Parametri del server**
| | | |
| --- |--- |--- |
| Campo | Campo obbligatorio | Commento |
| `clientId` | Sì | Un identificatore pubblico per l'applicazione. Viene utilizzato per avviare flussi di autenticazione e può essere condiviso pubblicamente. |
| `clientSecret` | Sì | Una chiave segreta utilizzata per autenticare l'applicazione con il server di autorizzazione, soprattutto quando si scambia un codice di autorizzazione con un token di accesso. Deve essere mantenuta riservata e non condivisa pubblicamente. |
| `authorizationType` | Sì | Il tipo di autorizzazione supportato da questa configurazione di autorizzazione. Attualmente, "OAuth 2.0" è l'unico valore supportato. |
| `authUrl` | Sì | L'URL di autorizzazione per il provider cloud di terze parti. |
| `tokenUrl` | Sì | L'URL del token per il provider di servizi cloud di terze parti. |
| `tokenEndpointAuthenticationScheme` | Sì | Schema di autenticazione di «HTTP\$1BASIC» o «REQUEST\$1BODY\$1CREDENTIALS». HTTP\$1BASIC segnala che le credenziali del client sono incluse nell'intestazione di autorizzazione, mentre il ladder segnala che sono incluse nel corpo della richiesta. |
Il OAuth server utilizzato deve essere configurato in modo che i valori delle stringhe dei token di accesso siano codificati in Base64 con il set di caratteri UTF-8.
# Ruoli di collegamento degli account
Per creare un connettore C2C, avrai bisogno di un server di autorizzazione OAuth 2.0 e di un collegamento all'account. Per ulteriori informazioni, consulta [Flusso di lavoro per il collegamento degli account](account-linking-flow.md).
OAuth 2.0 definisce i seguenti quattro ruoli nell'implementazione del collegamento degli account:
1. Server di autorizzazione
1. Proprietario della risorsa (utente finale)
1. Server di risorse
1. Client
Di seguito vengono definiti ciascuno di questi OAuth ruoli:
**Server di autorizzazione**
Il server di autorizzazione è il server che identifica e autentica l'identità di un utente finale in un cloud di terze parti. I token di accesso forniti da questo server possono collegare l'account della piattaforma cliente dell'utente AWS finale e l'account della piattaforma di terze parti. Questo processo è denominato collegamento dell'account.
Il server di autorizzazione supporta il collegamento degli account fornendo quanto segue:
+ Visualizza una pagina di accesso per consentire all'utente finale di accedere al sistema. Questo viene in genere definito endpoint di autorizzazione.
+ Autentica l'utente finale nel sistema.
+ Genera un codice di autorizzazione che identifica l'utente finale.
+ Trasmette il codice di autorizzazione alle integrazioni gestite per AWS IoT Device Management.
+ Accetta il codice di autorizzazione dalle integrazioni gestite per AWS IoT Device Management e restituisce un token di accesso che le integrazioni gestite per AWS IoT Device Management possono utilizzare per accedere ai dati dell'utente finale nel tuo sistema. Questa operazione viene in genere completata tramite un URI separato, chiamato URI token o endpoint.
Il server di autorizzazione deve supportare il flusso del codice di autorizzazione OAuth 2.0 da utilizzare con integrazioni gestite per AWS IoT Device Management Connector. le integrazioni gestite per AWS IoT Device Management supportano anche il flusso del codice di autorizzazione con [Proof Key for Code Exchange (](https://www.rfc-editor.org/rfc/rfc7636)PKCE).
Il server di autorizzazione deve:
+ Emetti token di accesso che contengono l'ID estraibile dell'utente finale o del proprietario della risorsa, ad esempio token JWT
+ Puoi restituire l'ID dell'utente finale per ogni token di accesso emesso
In caso contrario, il connettore non sarà in grado di supportare l'operazione richiesta. `AWS.ActivateUser` Ciò impedirà l'utilizzo dei connettori con le integrazioni gestite.
Se lo sviluppatore o il proprietario del connettore non gestisce il proprio server di autorizzazione, il server di autorizzazione utilizzato deve fornire l'autorizzazione per le risorse gestite dalla piattaforma di terze parti dello sviluppatore del connettore. Ciò significa che tutti i token ricevuti dalle integrazioni gestite dal server di autorizzazione devono fornire limiti di sicurezza significativi sui dispositivi (la risorsa). Ad esempio, un token per utenti finali non consente comandi su un altro dispositivo dell'utente finale; le autorizzazioni fornite dal token sono mappate alle risorse all'interno della piattaforma. Considerate l'esempio di *Lights Incorporated*. Quando un utente finale avvia il flusso di collegamento dell'account con il proprio connettore, viene reindirizzato alla pagina di accesso di *Lights Incorporated* che si trova davanti al server di autorizzazione. *Dopo aver effettuato l'accesso e concesso le autorizzazioni al client, forniscono un token che consente al connettore di accedere alle risorse all'interno del proprio account Lights Incorporated.*
**Proprietario della risorsa (utente finale)**
In qualità di proprietario della risorsa, consenti a integrazioni gestite per i clienti di AWS IoT Device Management di accedere alle risorse associate al tuo account eseguendo il collegamento dell'account. Ad esempio, si consideri la lampadina intelligente che un utente finale ha inserito nell'applicazione mobile *Lights* Incorporated. Il proprietario della risorsa si riferisce all'account dell'utente finale che ha acquistato e effettuato l'onboarding del dispositivo. Nel nostro esempio, il proprietario della risorsa è modellato come un account *Lights Incorporated OAuth2 2.0*. In qualità di proprietario della risorsa, questo account fornisce le autorizzazioni per emettere comandi e gestire il dispositivo.
**Server di risorse**
Questo è il server che ospita le risorse protette che richiedono l'autorizzazione all'accesso (dati del dispositivo). Il AWS cliente deve accedere alle risorse protette per conto di un utente finale e lo fa tramite integrazioni gestite per i connettori AWS IoT Device Management dopo il collegamento dell'account. Considerando ad esempio la lampadina intelligente di prima, il server di risorse è un servizio basato su cloud di proprietà di *Lights Incorporated* che gestisce la lampadina dopo l'installazione. Tramite il server di risorse, il proprietario della risorsa può impartire comandi alla lampadina intelligente, come accenderla e spegnerla. La risorsa protetta fornisce solo le autorizzazioni per l'account dell'utente finale e per altri account a accounts/entities cui potrebbe aver fornito l'autorizzazione.
**Cliente**
In questo contesto, il client è il tuo connettore C2C. Un client è definito come un'applicazione a cui viene concesso l'accesso alle risorse all'interno di un server di risorse per conto dell'utente finale. Il processo di collegamento dell'account rappresenta il connettore, il client, che richiede l'accesso alle risorse di un utente finale all'interno del cloud di terze parti.
Sebbene il connettore sia il OAuth client, le integrazioni gestite per AWS IoT Device Management eseguono operazioni per conto del connettore. Ad esempio, le integrazioni gestite per AWS IoT Device Management inoltrano richieste al server di autorizzazione per ottenere un token di accesso. Il connettore è ancora considerato il client perché è l'unico componente che accede alla risorsa protetta (dati del dispositivo) nel server di risorse.
Considerate la lampadina intelligente che è stata integrata da un utente finale. Una volta completato il collegamento dell'account tra la piattaforma del cliente e il server di autorizzazione di *Lights Incorporated*, il connettore stesso comunicherà con il server di risorse per recuperare informazioni sulla lampadina intelligente dell'utente finale. Il connettore può quindi ricevere comandi dall'utente finale. Ciò include l'accensione o lo spegnimento della luce per loro conto tramite il server di risorse *Lights Incorporated*. Pertanto, designiamo il connettore come client.
# Flusso di lavoro per il collegamento degli account
Affinché le integrazioni gestite di un cliente per la piattaforma AWS IoT Device Management interagiscano con i dispositivi di un utente finale sulla piattaforma di terze parti tramite il connettore C2C, ottiene il token di accesso tramite il seguente flusso di lavoro:
1. Quando un utente avvia l'onboarding di dispositivi di terze parti tramite l'applicazione del cliente, le integrazioni gestite per AWS IoT Device Management restituiscono l'URI di autorizzazione e il. AssociationId
1. Il front-end dell'applicazione memorizza AssociationId e reindirizza l'utente finale alla pagina di accesso della piattaforma di terze parti.
1. L'utente finale accede. L'utente finale concede al client l'accesso ai dati del proprio dispositivo.
1. La piattaforma di terze parti crea un codice di autorizzazione. L'utente finale viene reindirizzato alle integrazioni gestite per l'URI di callback della piattaforma AWS IoT Device Management, incluso il codice allegato alla richiesta di reindirizzamento.
1. Le integrazioni gestite scambia questo codice con l'URI del token della piattaforma di terze parti.
1. L'URI del token convalida il codice di autorizzazione e restituisce un token di accesso OAuth2 .0 e un token di aggiornamento, associati all'utente finale.
1. Le integrazioni gestite richiamano il connettore C2C per completare il flusso di collegamento `AWS.ActivateUser` dell'account e ottenere. UserId
1. Le integrazioni gestite restituiscono OAuth RedirectUrl (dalla configurazione Connector Policy) la pagina di autenticazione riuscita all'applicazione del cliente.
**Nota**
In caso di errori, le integrazioni gestite per AWS IoT Device Management aggiungono i parametri di query error ed error\$1description all'URL fornendo i dettagli dell'errore all'applicazione del cliente.
1. L'applicazione del cliente reindirizza l'utente finale a. OAuth RedirectUrl A questo punto il front-end dell'applicazione conosce AssociationId l'associazione sin dal primo passaggio.
Tutte le richieste successive effettuate da integrazioni gestite per AWS IoT Device Management tramite il connettore C2C alla piattaforma cloud di terze parti, come i comandi per scoprire dispositivi e inviare comandi, includeranno il token di accesso OAuth2 .0.
Il diagramma seguente mostra la relazione tra i componenti chiave del collegamento degli account:
![\[Connettore C2C: collegamento dell'account, flusso di lavoro con l'autorizzazione OAuth\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/account-linking-workflow.png)
# Implementa le operazioni di interfaccia del connettore C2C
Managed integrations for AWS IoT Device Management definisce quattro operazioni da gestire per qualificarsi come connettore. AWS Lambda Il connettore C2C deve implementare ognuna delle seguenti operazioni:
1. `AWS.ActivateUser`- Le integrazioni gestite per il AWS IoT Device Management servizio richiamano questa API per recuperare un identificatore utente univoco a livello globale associato al token .0 fornito. OAuth2 Questa operazione può essere utilizzata opzionalmente per eseguire eventuali requisiti aggiuntivi per il processo di collegamento dell'account.
1. `AWS.DiscoverDevices`- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per scoprire i dispositivi dell'utente
1. `AWS.SendCommand`- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per l'invio di comandi per i dispositivi dell'utente
1. `AWS.DeactivateUser`- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per disattivare il token di accesso dell'utente da decollegare nel server di autorizzazione.
Le integrazioni gestite per AWS IoT Device Management sempre richiamano la funzione Lambda con un payload di stringa JSON tramite l'azione. AWS Lambda `invokeFunction` Le operazioni di richiesta devono includere un `operationName` campo in ogni payload della richiesta. Per ulteriori informazioni, consulta [Invoke](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html) in AWS Lambda API Reference.
Ogni timeout di chiamata è impostato su due secondi e, se la chiamata fallisce, verrà ritentata cinque volte.
La Lambda implementata per il connettore analizzerà an `operationName` dal payload della richiesta e implementerà la funzionalità corrispondente da mappare al cloud di terze parti:
```
public ConnectorResponse handleRequest(final ConnectorRequest request)
throws OperationFailedException {
Operation operation;
try {
operation = Operation.valueOf(request.payload().operationName());
} catch (IllegalArgumentException ex) {
throw new ValidationException(
"Unknown operation '%s'".formatted(request.payload().operationName()),
ex
);
}
return switch (operation) {
case ActivateUser -> activateUserManager.activateUser(request);
case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
case SendCommand -> sendCommandManager.sendCommand(request);
case DeactivateUser -> deactivateUser.deactivateUser(request);
};
}
```
**Nota**
Lo sviluppatore del connettore deve implementare le `deactivateUser.deactivateUser` operazioni`activateUserManager.activateUser(request)`, `deviceDiscoveryManager.listDevices(request)``sendCommandManager.sendCommand(request)`, e elencate nell'esempio precedente.
L'esempio seguente descrive in dettaglio una richiesta di connettore generica proveniente da integrazioni gestite, in cui sono presenti campi comuni a tutte le interfacce richieste. Dall'esempio, puoi vedere che sono presenti sia un'intestazione di richiesta che un payload della richiesta. Le intestazioni di richiesta sono comuni a tutte le interfacce operative.
```
{
"header": {
"auth": {
"token": “ashriu32yr97feqy7afsaf”,
"type": “OAuth2.0"
}
},
"payload":{
"operationName": "AWS.SendCommand",
"operationVersion": "1.0",
"connectorId": “exampleId”,
…
}
}
```
## Intestazioni di richiesta predefinite
I campi di intestazione predefiniti sono i seguenti.
```
{
"header": {
"auth": {
"token": string, // end user's Access Token
"type": ENUM ["OAuth2.0"],
}
}
}
```
Qualsiasi API ospitata da un connettore deve elaborare i seguenti parametri di intestazione:
**Intestazioni e campi predefiniti**
| | | |
| --- |--- |--- |
| Campo | Obbligatorio/facoltativo | Descrizione |
| `header:auth` | Sì | Informazioni di autorizzazione fornite dal costruttore di connettori C2C durante la registrazione dei connettori. |
| `header:auth:token` | Sì | Token di autorizzazione dell'utente generato dal provider di servizi cloud di terze parti e collegato a. `connectorAssociationID` |
| `header:auth:type` | Sì | Il tipo di autorizzazione necessaria. |
**Nota**
A tutte le richieste al connettore verrà allegato il token di accesso dell'utente finale. Si può presumere che il collegamento dell'account tra l'utente finale e il cliente delle integrazioni gestite sia già avvenuto.
## Payload della richiesta
Oltre alle intestazioni comuni, ogni richiesta avrà un payload. Sebbene questo payload abbia campi unici per ogni tipo di operazione, ogni payload ha una serie di campi predefiniti che saranno sempre presenti.
**Richiedi i campi del payload:**
+ `operationName`: L'operazione di una determinata richiesta, pari a uno dei seguenti valori:`AWS.ActivateUser`,, `AWS.SendCommand``AWS.DiscoverDevices`,`AWS.DeactivateUser`.
+ `operationVersion`: Ogni operazione è suddivisa in versioni per consentirne l'evoluzione nel tempo e fornire una definizione stabile dell'interfaccia per i connettori di terze parti. Le integrazioni gestite inseriscono un campo di versione nel payload di tutte le richieste.
+ `connectorId`: L'ID del connettore a cui è stata inviata la richiesta.
## Intestazioni di risposta predefinite
Ogni operazione risponderà con una risposta `ACK` alle integrazioni gestite per AWS IoT Device Management che confermerà che il connettore C2C ha ricevuto la richiesta e ha iniziato a elaborarla. Di seguito è riportato un esempio generico di tale risposta:
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
Ogni risposta operativa deve avere la seguente intestazione comune:
```
{
"header": {
"responseCode": Integer
}
}
```
La tabella seguente elenca l'intestazione di risposta predefinita:
**Intestazione e campo di risposta predefiniti**
| | | |
| --- |--- |--- |
| Campo | Obbligatorio/facoltativo | Commento |
| `header:responseCode` | Sì | ENUM di valori che indicano lo stato di esecuzione della richiesta. |
Nelle varie interfacce di connettore e schemi API descritti in questo documento è presente un `responseMessage` campo or. `Message` Questo è un campo opzionale utilizzato dal connettore C2C Lambda per rispondere con qualsiasi contesto relativo alla richiesta e alla sua esecuzione. Preferibilmente, qualsiasi errore che dia origine a un codice di stato diverso da `200` dovrebbe includere un valore di messaggio che descriva l'errore.
## Rispondi alle richieste di funzionamento del connettore C2C con l'API SendConnectorEvent
Le integrazioni gestite AWS IoT Device Management prevedono che il connettore si comporti in modo asincrono per ogni operazione. `AWS.SendCommand` `AWS.DiscoverDevices` Ciò significa che la risposta iniziale a queste operazioni «riconosce» semplicemente che il connettore C2C ha ricevuto la richiesta.
Utilizzando l'`SendConnectorEvent`API, il connettore dovrebbe inviare i tipi di eventi dall'elenco seguente a for `AWS.DiscoverDevices` and `AWS.SendCommand` operations, oltre a eventi proattivi del dispositivo (come l'accensione e lo spegnimento manuale di una luce). Per una spiegazione dettagliata di questi tipi di eventi e dei relativi casi d'uso, consulta [Implementa AWS. DiscoverDevices operazione](discover-devices-op.md)[Implementa AWS. SendCommand operazione](send-command-op.md), e[Invia gli eventi del dispositivo con l'API SendConnectorEvent](send-connector-events.md).
Ad esempio, se il connettore C2C riceve una `DiscoverDevices` richiesta, le integrazioni gestite per AWS IoT Device Management si aspettano che risponda in modo sincrono con il formato di risposta definito sopra. Quindi, devi richiamare l'`SendConnectorEvent`API con la struttura della richiesta definita in, per un evento DEVICE\$1DISCOVERY. [Implementa AWS. DiscoverDevices operazione](discover-devices-op.md) La chiamata `SendConnectorEvent` on API può avvenire ovunque tu abbia accesso alle credenziali Lambda del tuo connettore C2C. Account AWS Il flusso di rilevamento dei dispositivi non ha esito positivo finché le integrazioni gestite per AWS IoT Device Management non ricevono questo evento.
**Nota**
In alternativa, la chiamata `SendConnectorEvent` API può avvenire prima della risposta alla chiamata Lambda del connettore C2C, se necessario. Tuttavia, questo flusso contraddice il modello asincrono per lo sviluppo del software.
+ **SendConnectorEvent**- Il connettore chiama questa API managed integrations for AWS IoT Device Management per inviare eventi del dispositivo a integrazioni gestite per AWS IoT Device Management. Solo 3 tipi di eventi accettati dalle integrazioni gestite:
+ "**DEVICE\$1DISCOVERY**" — Questa operazione relativa all'evento deve essere utilizzata per inviare un elenco di dispositivi rilevati all'interno del cloud di terze parti per un token di accesso specifico.
+ **«DEVICE\$1COMMAND\$1RESPONSE**" — Questa operazione evento deve essere utilizzata per inviare un evento specifico del dispositivo come risultato dell'esecuzione del comando.
+ **«DEVICE\$1EVENT**" — Questa operazione evento deve essere utilizzata per qualsiasi evento proveniente dal dispositivo che non sia il risultato diretto di un comando basato sull'utente. Questo può servire come tipo di evento generale per segnalare in modo proattivo le modifiche o le notifiche dello stato del dispositivo.
# Implementa AWS. ActivateUser operazione
L'`AWS.ActivateUser`operazione è necessaria per le integrazioni gestite per AWS IoT Device Management per recuperare un identificatore utente dal token .0 di OAuth2 un utente finale. Le integrazioni gestite per AWS IoT Device Management passeranno il OAuth token all'interno dell'intestazione della richiesta e si aspetta che il connettore includa l'identificatore utente univoco a livello globale nel payload di risposta. Questa operazione viene eseguita dopo un flusso di collegamento dell'account riuscito.
L'elenco seguente descrive i requisiti del connettore per facilitare il corretto flusso di `AWS.Activate` utenti.
+ Il tuo connettore C2C Lambda può elaborare un messaggio di richiesta `AWS.ActivateUser` operativa proveniente da integrazioni gestite per AWS IoT Device Management.
+ Il connettore C2C Lambda può determinare un identificatore utente univoco da un token .0 fornito. OAuth2 Normalmente, può essere estratto dal token stesso, se si tratta di un token JWT, o richiesto dal token al server di autorizzazione.
**Flusso di lavoro di `AWS.ActivateUser`**
1. Integrazioni gestite per AWS IoT Device Management richiamare il connettore C2C Lambda con il seguente payload:
```
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload": {
"operationName": "AWS.ActivateUser",
"operationVersion": "1.0.0",
"connectorId": "Your-Connector-ID",
}
}
```
1. Il connettore C2C determina l'ID utente, dal token o interrogando il server di risorse di terze parti, da includere nella risposta. `AWS.ActivateUser`
1. Il connettore C2C risponde alla chiamata dell'operazione `AWS.ActivateUser` Lambda, incluso il payload predefinito e l'identificatore utente corrispondente all'interno del campo. `userId`
```
{
"header": {
"responseCode":200
},
"payload": {
"responseMessage": "Successfully activated user with connector-id `Your-Connector-Id.”,
"userId": "123456"
}
}
```
# Implementa AWS. DiscoverDevices operazione
Device Discovery allinea l'elenco dei dispositivi fisici di proprietà dell'utente finale con le rappresentazioni digitali di tali dispositivi degli utenti finali gestite nelle integrazioni gestite per AWS IoT Device Management. Viene eseguita da un AWS cliente su dispositivi di proprietà dell'utente finale solo dopo aver completato il collegamento dell'account tra l'utente e le integrazioni gestite per AWS IoT Device Management. Il rilevamento dei dispositivi è un processo asincrono in cui le integrazioni gestite per AWS IoT Device Management richiamano un connettore per avviare la richiesta di rilevamento dei dispositivi. Un connettore C2C restituisce un elenco di dispositivi degli utenti finali rilevati in modo asincrono con un identificatore di riferimento (denominato «) generato da integrazioni gestite. `deviceDiscoveryId`
Il diagramma seguente illustra il flusso di lavoro di rilevamento dei dispositivi tra l'utente finale e le integrazioni gestite per AWS IoT Device Management:
![\[AWS. DiscoverDevices flusso di lavoro\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/device-discovery-workflow.png)
**AWS. DiscoverDevices flusso di lavoro**
1. Il cliente avvia il processo di scoperta del dispositivo per conto dell'utente finale.
1. Le integrazioni gestite per la AWS IoT Device Management generazione di un identificatore di riferimento richiesto `deviceDiscoveryId` per la richiesta di rilevamento del dispositivo generata dal Cliente. AWS
1. Integrazioni gestite per l' AWS IoT Device Management invio di una richiesta di rilevamento del dispositivo al connettore C2C utilizzando l'interfaccia `AWS.DiscoverDevices` operativa, inclusa una richiesta valida per OAuth `accessToken` l'utente finale e la. `deviceDiscoveryId`
1. Gli archivi del connettore `deviceDiscoveryId` devono essere inclusi nell'evento. `DEVICE_DISCOVERY` Questo evento conterrà anche un elenco dei dispositivi degli utenti finali scoperti e dovrà essere inviato alle integrazioni gestite per AWS IoT Device Management con l'`SendConnectorEvent`API come `DEVICE_DISCOVERY` evento.
1. Il connettore C2C chiamerà il server di risorse per recuperare tutti i dispositivi di proprietà dell'utente finale.
1. Il connettore C2C Lambda risponde all'invocazione Lambda `invokeFunction` () con la risposta ACK alle integrazioni gestite per AWS IoT Device Management, fungendo da risposta iniziale per l'operazione. `AWS.DiscoverDevices` Managed Integrations notifica al cliente con un ACK il processo di scoperta dei dispositivi avviato.
1. Il server di risorse ti invia un elenco di dispositivi posseduti e gestiti dall'utente finale.
1. Il connettore converte ogni dispositivo dell'utente finale nelle integrazioni gestite per il formato del dispositivo richiesto da AWS IoT Device Management`ConnectorDeviceId`, `ConnectorDeviceName` incluso un report sulle capacità per ogni dispositivo.
1. Il connettore C2C fornisce anche informazioni sul proprietario `UserId` dei dispositivi rilevati. Può essere recuperato dal server di risorse come parte dell'elenco dei dispositivi o in una chiamata separata a seconda dell'implementazione del server di risorse.
1. Successivamente, il connettore C2C chiamerà le integrazioni gestite per l'API AWS IoT Device Management`SendConnectorEvent`, tramite SigV4 utilizzando Account AWS credenziali e con il parametro operativo impostato come «DEVICE\$1DISCOVERY». Ogni dispositivo nell'elenco dei dispositivi inviati alle integrazioni gestite per AWS IoT Device Management sarà rappresentato da parametri specifici del dispositivo come`connectorDeviceId`, `connectorDeviceName` e a. `capabilityReport`
1. In base alla risposta del tuo server di risorse, devi notificare di conseguenza le integrazioni gestite per AWS IoT Device Management.
Ad esempio, se il tuo server di risorse riceve una risposta in pagine all'elenco dei dispositivi rilevati per un utente finale, per ogni sondaggio puoi inviare un singolo evento `DEVICE_DISCOVERY` operativo, con un parametro di. `statusCode` `3xx` Se il rilevamento dei dispositivi è ancora in corso, ripeti i passaggi 5, 6 e 7.
1. Managed Integrations for AWS IoT Device Management invia una notifica al cliente in merito alla scoperta dei dispositivi dell'utente finale.
1. Se il connettore C2C invia un evento `DEVICE_DISCOVERY` operativo con il `statusCode` parametro aggiornato con un valore di 200, le integrazioni gestite notificheranno al cliente il completamento del flusso di lavoro di individuazione dei dispositivi.
**Importante**
Se lo si desidera, i passaggi da 7 a 11 possono verificarsi prima del passaggio 6. Ad esempio, se la piattaforma di terze parti dispone di un'API per elencare i dispositivi di un utente finale, l'evento DEVICE\$1DISCOVERY può essere inviato `SendConnectorEvent` prima che il connettore C2C Lambda risponda con il tipico ACK.
## Requisiti del connettore C2C per il rilevamento dei dispositivi
L'elenco seguente descrive i requisiti del connettore C2C per facilitare la corretta individuazione dei dispositivi.
+ Il connettore C2C Lambda a può elaborare un messaggio di richiesta di rilevamento del dispositivo proveniente da integrazioni gestite per AWS IoT Device Management e gestirne l'operazione. `AWS.DiscoverDevices`
+ Il connettore C2C può chiamare le integrazioni gestite per AWS IoT Device Management APIs tramite SigV4 utilizzando le credenziali utilizzate per la registrazione del Account AWS connettore.
## Processo di scoperta dei dispositivi
I passaggi seguenti descrivono il processo di scoperta dei dispositivi con il connettore C2C e le integrazioni gestite per AWS IoT Device Management.
**Processo di scoperta dei dispositivi**
1. Le integrazioni gestite attivano il rilevamento dei dispositivi:
1. Invia una richiesta POST a `DiscoverDevices` con il seguente payload JSON:
```
/DiscoverDevices
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload": {
"operationName": "AWS.DiscoverDevices",
"operationVersion": "1.0",
"connectorId": "Your-Connector-Id",
"deviceDiscoveryId": "12345678"
}
}
```
1. Il connettore conferma la scoperta:
1. Il connettore invia una conferma con la seguente risposta JSON:
```
{
"header": {
"responseCode":200
},
"payload": {
"responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`"
}
}
```
1. Il connettore invia l'evento Device Discovery:
1. Invia una richiesta POST a `/connector-event/{your_connector_id}` con il seguente payload 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"]
}]
}]
}
}
]
}
```
## Costruisci un CapabilityReport per l'evento DISCOVER\$1DEVICES
Come illustrato nella struttura degli eventi sopra definita, ogni dispositivo segnalato in un evento DISCOVER\$1DEVICES, che funge da risposta a un'`AWS.DiscoverDevices`operazione, richiederà una CapbilityReport descrizione delle funzionalità del dispositivo corrispondente. Un `CapabilityReport` indica le integrazioni gestite per le funzionalità dei dispositivi AWS IoT Device Management in un formato conforme a Matter. I seguenti campi devono essere forniti nel ``: CapabilityReport
+ `nodeId`, String: identificatore per il nodo dei dispositivi contenente quanto segue `endpoints`
+ `version`, String: versione di questo nodo del dispositivo, impostata dallo sviluppatore del connettore
+ `endpoints`, Elenco: Elenco delle AWS implementazioni del Matter Data Model supportate da questo endpoint del dispositivo.
+ `id`, String: identificatore dell'endpoint impostato dallo sviluppatore del connettore
+ `deviceTypes`, Elenco: elenco dei tipi di dispositivi acquisiti da questo endpoint, ad esempio «Fotocamera».
+ `clusters`, Elenco: Elenco delle AWS implementazioni del Matter Data Model supportate da questo endpoint.
+ `id`, String: identificatore del cluster come definito dallo standard Matter.
+ `revision`, Numero intero: numero di revisione del cluster definito dallo standard Matter.
+ `attributes`, Mappa: mappa degli identificatori degli attributi e dei corrispondenti valori di stato correnti del dispositivo, con identificatori e valori validi definiti dallo standard Matter.
+ `id`, String: ID dell'attributo definito dalle AWS implementazioni del Matter Data Model.
+ `value`, Oggetto: il valore corrente dell'attributo definito dall'attributo ID. Il tipo di «valore» può cambiare a seconda dell'attributo. Il `value` campo è facoltativo per ogni attributo e deve essere incluso solo se il connettore lambda è in grado di determinare lo stato corrente durante il rilevamento.
+ `commands`, Elenco: Elenco dei comandi IDs supportati da questo cluster come definito dallo standard Matter.
+ `events`, Elenco: Elenco degli eventi IDs supportati da questo cluster come definito dallo standard Matter.
Per l'elenco corrente delle funzionalità supportate e le relative [AWS implementazioni del Matter Data Model](matter-data-model.md), fate riferimento all'ultima versione della documentazione del modello di dati.
# Implementa AWS. SendCommand operazione
L'`AWS.SendCommand`operazione consente alle integrazioni gestite per AWS IoT Device Management di inviare comandi avviati dall'utente finale tramite il AWS cliente al server di risorse. Il tuo server di risorse può supportare diversi tipi di dispositivi, ognuno dei quali ha il proprio modello di risposta. L'esecuzione dei comandi è un processo asincrono in cui le integrazioni gestite per AWS IoT Device Management inviano una richiesta di esecuzione del comando con un `TraceID`, che il connettore includerà in una risposta al comando inviata alle integrazioni gestite tramite la `` SendConnectorEvent API. Le integrazioni gestite per AWS IoT Device Management si aspettano che il server di risorse restituisca una risposta che confermi che il comando è stato ricevuto, ma non indica necessariamente che il comando è stato eseguito.
Il diagramma seguente illustra il flusso di esecuzione del comando con un esempio in cui l'utente finale tenta di accendere le luci della propria casa:
![\[Workflow di esecuzione dei comandi del dispositivo\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/send-command-workflow.png)
**Workflow di esecuzione dei comandi del dispositivo**
1. Un utente finale invia un comando per accendere una luce utilizzando l'applicazione del AWS cliente.
1. Il cliente inoltra le informazioni sui comandi alle integrazioni gestite per AWS IoT Device Management con le informazioni sul dispositivo dell'utente finale.
1. Le integrazioni gestite generano un «traceID» che il connettore utilizzerà per inviare le risposte ai comandi al servizio.
1. le integrazioni gestite per AWS IoT Device Management inviano la richiesta di comando al connettore, utilizzando l'interfaccia `AWS.SendCommand` operativa.
1. Il payload definito da questa interfaccia è costituito dall'identificatore del dispositivo, dai comandi del dispositivo formulati come Matterendpoints/clusters/commands, dal token di accesso dell'utente finale e da altri parametri richiesti.
1. Il connettore `traceId` memorizza i dati da includere nella risposta al comando.
1. Il connettore traduce la richiesta di comando di integrazioni gestite nel formato appropriato del server di risorse.
1. Il connettore riceve `UserId` dal token di accesso fornito dall'utente finale e lo associa al comando.
1. `UserId`Può essere recuperato dal server di risorse utilizzando una chiamata separata o estratto dal token di accesso nel caso di JWT e token simili.
1. L'implementazione dipende dal server di risorse e dai dettagli del token di accesso.
1. Il connettore richiama il server di risorse per «accendere» la luce dell'utente finale.
1. Il server di risorse interagisce con il dispositivo.
1. Il connettore comunica alle integrazioni gestite per AWS IoT Device Management che il server di risorse ha fornito il comando, rispondendo con un ACK come risposta iniziale sincrona al comando.
1. Le integrazioni gestite le inoltrano quindi all'applicazione del cliente.
1. Dopo che il dispositivo ha acceso la luce, l'evento del dispositivo viene catturato dal server di risorse.
1. Il server di risorse invia l'evento del dispositivo al connettore.
1. Il connettore trasforma l'evento del dispositivo generato dal server di risorse in un tipo di operazione di evento DEVICE\$1COMMAND\$1RESPONSE di integrazioni gestite.
1. Il connettore chiama l'API con l'operazione «DEVICE\$1COMMAND\$1RESPONSE`SendConnectorEvent`».
1. Allega le integrazioni `traceId` fornite da managed integrations per AWS IoT Device Management nella richiesta iniziale.
1. Le integrazioni gestite notificano al cliente la modifica dello stato del dispositivo dell'utente finale.
1. Il cliente notifica all'utente finale che la luce del dispositivo si è accesa.
**Nota**
La configurazione del server di risorse determina la logica per la gestione dei messaggi di richiesta e risposta dei comandi del dispositivo non riusciti. Ciò include i tentativi di riprovare i messaggi utilizzando lo stesso ReferenceID per il comando.
## Requisiti del connettore C2C per l'esecuzione dei comandi del dispositivo
L'elenco seguente descrive i requisiti del connettore C2C per facilitare la corretta esecuzione dei comandi del dispositivo.
+ Il connettore C2C Lambda può elaborare i messaggi di richiesta `AWS.SendCommand` operativa provenienti da integrazioni gestite per AWS IoT Device Management.
+ Il connettore C2C deve tenere traccia dei comandi inviati al server di risorse e mapparli con il `traceID` appropriato.
+ Puoi chiamare integrazioni gestite per le API del servizio AWS IoT Device Management tramite SigV4 utilizzando AWS le credenziali Account AWS utilizzate per la registrazione del connettore C2C.
1. Le integrazioni gestite inviano il comando al connettore (fare riferimento al passaggio 4 nel diagramma precedente).
1.
```
/Send-Command
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload": {
"operationName": "AWS.SendCommand",
"operationVersion": "1.0",
"connectorId": "Your-Connector-Id",
"connectorDeviceId": "Your_Device_Id",
"traceId": "traceId-3241u78123419",
"endpoints": [{
"id": "1",
"clusters": [{
"id": "0x0202",
"commands": [{
"0xff01":
{
"0x0000": "3”
}
}]
}]
}]
}
}
```
1. Comando ACK del connettore C2C (fare riferimento al passaggio 7 del diagramma precedente in cui il connettore invia ACK alle integrazioni gestite per AWS IoT Device Management Service).
1.
```
{
"header":{
"responseCode":200
},
"payload":{
"responseMessage": "Successfully received send-command request for connector 'Your-Connector-Id' and connector-device-id 'Your_Device_Id'"
}
}
```
1. Il connettore invia l'evento Device Command Response (fare riferimento al passaggio 11 nel diagramma precedente).
1.
```
AWS-API: /SendConnectorEvent
URI: POST /connector-event/{Your-Connector-Id}
{
"UserId": "End-User-Id",
"Operation": "DEVICE_COMMAND_RESPONSE",
"OperationVersion": "1.0",
"StatusCode": 200,
"Message": “Example message”,
"ConnectorDeviceId": "Your_Device_Id",
"TraceId": "traceId-3241u78123419",
"MatterEndpoint": {
"id": "1",
"clusters": [{
"id": "0x0202",
"attributes": [
{
"0x0000": “3”
}
],
"commands": [
"0xff01":
{
"0x0000": "3”
}
]
}]
}
}
```
**Nota**
Le modifiche allo stato del dispositivo a seguito dell'esecuzione di un comando non si rifletteranno nelle integrazioni gestite per AWS IoT Device Management fino a quando l'evento DEVICE\$1COMMAND\$1RESPONSE corrispondente non sarà stato ricevuto tramite l'API. SendConnectorEvent Ciò significa che fino a quando le integrazioni gestite non riceveranno l'evento della fase 3 precedente, indipendentemente dal fatto che la risposta alla chiamata del connettore indichi l'esito positivo o meno, lo stato del dispositivo non verrà aggiornato.
## Interpretazione degli «endpoint» della materia inclusa in AWS. SendCommand richiesta
Le integrazioni gestite utilizzeranno le funzionalità del dispositivo riportate durante l'individuazione del dispositivo per determinare quali comandi un dispositivo può accettare. Ogni funzionalità del dispositivo è modellata attraverso AWS implementazioni del Matter Data Model; pertanto, tutti i comandi in entrata verranno derivati dal campo `commands` all'interno di un determinato cluster. È responsabilità del connettore analizzare il campo `endpoints`, determinare il comando Matter corrispondente e tradurlo in modo che il comando corretto raggiunga il dispositivo. In genere, ciò significa tradurre il modello di dati Matter nelle relative richieste API.
Dopo l'esecuzione del comando, il connettore determina quali `attributi` definiti dalle AWS implementazioni del Matter Data Model sono cambiati di conseguenza. Queste modifiche vengono quindi segnalate alle integrazioni gestite per AWS IoT Device Management tramite eventi API DEVICE\$1COMMAND\$1RESPONSE inviati con l'API. `SendConnectorEvent`
Considera il campo `endpoints` incluso nel payload di esempio seguente: `AWS.SendCommand`
```
"endpoints": [{
"id": "1",
"clusters": [{
"id": "0x0202",
"commands": [{
"0xff01":
{
"0x0000": "3”
}
}]
}]
}]
```
**Da questo oggetto, il connettore può determinare quanto segue:**
1. Imposta le informazioni sull'endpoint e sul cluster:
1. Imposta l'endpoint `id` su «1".
**Nota**
Se un dispositivo definisce più endpoint, ad esempio un singolo cluster, questo id viene utilizzato per indirizzare il comando alla funzionalità corretta. On/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off
1. Imposta il cluster `id` su «0x0202" (cluster Fan Control).
1. Imposta le informazioni sul comando:
1. Imposta l'identificatore del comando su «0xff01" (comando Update State definito da). AWS
1. Aggiorna gli identificatori degli attributi inclusi con i valori forniti nella richiesta.
1. Aggiorna l'attributo:
1. Imposta l'identificatore dell'attributo su «0x0000" (FanMode attributo del Fan Control Cluster).
1. Imposta il valore dell'attributo su «3" (alta velocità della ventola).
Managed integrations ha definito due tipi di comandi «personalizzati» che non sono strettamente definiti dalle AWS implementazioni del Matter Data Model: i ReadState comandi and. UpdateState Per ottenere e impostare gli attributi del cluster definiti da Matter, le integrazioni gestite invieranno al connettore una `AWS.SendCommand` richiesta con il comando IDs relativo a UpdateState (id: 0xff01) o ReadState (id: 0xff02), con i parametri corrispondenti degli attributi che devono essere aggiornati o letti. Questi comandi possono essere richiamati per QUALSIASI tipo di dispositivo per attributi impostati come modificabili (aggiornabili) o recuperabili (leggibili) dalla corrispondente implementazione del Matter Data Model. AWS
# Invia gli eventi del dispositivo con l'API SendConnectorEvent
## Panoramica degli eventi avviati dal dispositivo
Sebbene l'`SendConnectorEvent`API venga utilizzata per rispondere in modo asincrono alle `AWS.DiscoverDevices` operazioni `AWS.SendCommand` e alle operazioni, viene anche utilizzata per notificare alle integrazioni gestite eventuali eventi avviati dal dispositivo. Gli eventi avviati dal dispositivo possono essere definiti come qualsiasi evento generato da un dispositivo senza un comando avviato dall'utente. Questi eventi del dispositivo possono includere, a titolo esemplificativo, modifiche dello stato del dispositivo, rilevamento del movimento, livelli della batteria e altro ancora. Puoi inviare questi eventi alle integrazioni gestite utilizzando l'`SendConnectorEvent`API con l'operazione **DEVICE\$1EVENT**.
La sezione seguente utilizza una telecamera intelligente installata in una casa come esempio per spiegare ulteriormente il flusso di lavoro di questi eventi:
![\[Workflow degli eventi del dispositivo\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/device-events-workflow.png)
**Workflow degli eventi del dispositivo**
1. La videocamera rileva un movimento per il quale genera un evento che viene inviato al server di risorse.
1. Il server di risorse elabora l'evento e lo invia al connettore C2C.
1. Il connettore traduce questo evento nelle integrazioni gestite per l'interfaccia AWS IoT Device Management`DEVICE_EVENT`.
1. Il connettore C2C invia questo evento del dispositivo alle integrazioni gestite utilizzando l'`SendConnectorEvent`API con Operation impostata su «DEVICE\$1EVENT».
1. Le integrazioni gestite identificano il cliente interessato e trasmettono questo evento al cliente.
1. Il cliente riceve questo evento e lo visualizza all'utente tramite un identificatore utente.
Per ulteriori informazioni sul funzionamento delle `SendConnectorEvent` API, consulta `SendConnectorEvent` la Guida di riferimento alle integrazioni gestite per l'API AWS IoT Device Management.
## Requisiti per gli eventi avviati dal dispositivo
Di seguito sono riportati alcuni requisiti per gli eventi avviati dal dispositivo.
+ La risorsa del connettore C2C dovrebbe essere in grado di ricevere eventi asincroni del dispositivo dal server di risorse
+ La risorsa del connettore C2C dovrebbe essere in grado di richiamare integrazioni gestite per le API del servizio AWS IoT Device Management tramite SigV4 utilizzando AWS le credenziali Account AWS utilizzate per la registrazione del connettore C2C.
L'esempio seguente mostra un connettore che invia un evento originato dal dispositivo tramite l'API: SendConnectorEvent
```
AWS-API: /SendConnectorEvent
URI: POST /connector-event/{Your-Connector-Id}
{
"UserId": "Your-End-User-ID",
"Operation": "DEVICE_EVENT",
"OperationVersion": "1.0",
"StatusCode": 200,
"Message": None,
"ConnectorDeviceId": "Your_Device_Id",
"MatterEndpoint": {
"id": "1",
"clusters": [{
"id": "0x0202",
"attributes": [
{
"0x0000": "3"
}
]
}]
}]
}
```
Dall'esempio seguente, vediamo quanto segue:
+ Proviene dall'endpoint del dispositivo con ID uguale a 1.
+ La funzionalità del dispositivo a cui si riferisce questo evento ha un ID cluster di **0x0202**, relativo al cluster Fan Control matter.
+ L'attributo che è stato modificato ha l'ID **0x000**, relativo al Fan Mode Enum all'interno del cluster. **È stato aggiornato al valore **3**, relativo al valore High.**
+ Poiché `connectorId` è un parametro restituito dal servizio cloud al momento della creazione, i connettori devono eseguire query utilizzando GetCloudConnector e filtrare per`lambdaARN`. Il file di lambda `ARN` viene interrogato tramite l'API. `Lambda.get_function_url_config` Ciò consente l'`CloudConnectorId`accesso dinamico in lambda e non la configurazione statica come in precedenza.
# Implementa AWS. DeactivateUser operazione
## panoramica sulla disattivazione degli utenti
La disattivazione dei token di accesso utente forniti è necessaria quando un cliente elimina il proprio account AWS cliente o quando un utente finale desidera scollegare il proprio account nel sistema dal sistema del cliente. AWS In entrambi i casi d'uso, le integrazioni gestite devono facilitare questo flusso di lavoro utilizzando il connettore C2C.
L'immagine seguente illustra la rimozione del collegamento di un account utente finale dal sistema
![\[Flusso di lavoro di disattivazione degli utenti\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/user-deactivate-workflow.png)
**Flusso di lavoro di disattivazione degli utenti**
1. L'utente avvia il processo di decollegamento tra l'account del AWS cliente e il server di autorizzazione di terze parti associato al connettore C2C.
1. Il cliente avvia l'eliminazione dell'associazione dell'utente tramite integrazioni gestite per AWS IoT Device Management.
1. Le integrazioni gestite avviano il processo di disattivazione tramite richiesta al connettore utilizzando l'interfaccia operativa. `AWS.DeactivateUser`
1. Il token di accesso /user è incluso nell'intestazione della richiesta.
1. Il connettore C2C accetta la richiesta e richiama il server di autorizzazione per revocare il token e qualsiasi accesso che fornisce.
1. Ad esempio, gli eventi di un account utente non collegato non devono più essere inviati alle integrazioni gestite dopo l'esecuzione. `AWS.DeactivateUser`
1. Il server di autorizzazione revoca l'accesso e invia una risposta al connettore C2C.
1. Il connettore C2C invia alle integrazioni gestite per AWS IoT Device Management un ACK che indica che il token di accesso dell'utente è stato revocato.
1. Le integrazioni gestite eliminano tutte le risorse di proprietà dell'utente finale che erano associate al tuo server di risorse.
1. Le integrazioni gestite inviano un ACK al cliente, indicando che tutte le associazioni relative al sistema sono state eliminate.
1. Il cliente notifica all'utente finale che il suo account è stato scollegato dalla piattaforma.
## AWS. DeactivateUser requisiti
+ La funzione Lambda del connettore C2C riceve un messaggio di richiesta dalle integrazioni gestite per gestire l'operazione. `AWS.DeactivateUser`
+ Il connettore C2C deve revocare il token **OAuth2.0** fornito e il token di aggiornamento corrispondente dell'utente all'interno del server di autorizzazione.
Di seguito è riportato un esempio di `AWS.DeactivateUser` richiesta che il connettore riceverà:
```
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload":{
"operationName": "AWS.DeactivateUser"
"operationVersion": "1.0"
"connectorId": "Your-connector-Id"
}
}
```
# Invoca il tuo connettore C2C
AWS Lambda consente politiche basate sulle risorse per autorizzare chi può richiamare una Lambda. Poiché le integrazioni gestite per AWS IoT Device Management sono una Servizio AWS, è necessario consentire alle integrazioni gestite di richiamare il connettore C2C Lambda tramite la policy delle risorse.
Allega una politica delle risorse con almeno le seguenti autorizzazioni minime al tuo connettore C2C Lambda. Ciò fornisce integrazioni gestite con i privilegi di invoke della funzione Lambda. Questa politica include una `Condition` chiave per aiutarti a limitare l'usabilità dei tuoi `connectorId` dati ai soli utenti previsti.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "default",
"Statement": [
{
"Sid": "Your-Desired-Policy-ID",
"Effect": "Allow",
"Principal": {
"Service": "iotmanagedintegrations.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:ca-central-1:444455556666:function:connector-lambda-name",
"Condition": {
"StringEquals": {
"aws:SourceArn": "arn:aws:iotmanagedintegrations:ca-central-1:444455556666:account-association/account-association-id"
}
}
}
]
}
```
------
# Aggiungi le autorizzazioni al tuo ruolo IAM
Tutte le integrazioni gestite APIs richiedono l'autenticazione AWS SigV4 per essere invocate. SigV4 è un protocollo di firma per autenticare AWS le richieste API utilizzando le tue credenziali. Account AWS Il ruolo IAM utilizzato per richiamare le integrazioni gestite APIs deve disporre delle seguenti autorizzazioni per poter richiamare correttamente: APIs
```
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [
"iotmanagedintegrations:Your-Required-Actions"
],
"Resource": [
"Your-Resource"
]
}]
}
```
Per ulteriori informazioni sull'aggiunta di queste autorizzazioni, contatta. Supporto
**Risorse aggiuntive**
Per registrare il connettore C2C, è necessario quanto segue:
+ L'ARN Lambda che designa il connettore che desideri registrare.
# Testa manualmente il tuo connettore C2C
Per testare manualmente il connettore C2C end-to-end, è necessario simulare sia il cliente che l'utente finale.
**Avrai bisogno delle seguenti risorse:**
+ Un AWS Lambda ARN che indica il connettore da testare.
+ Un account utente di testing OAuth 2.0 dalla tua piattaforma cloud.
+ Un connettore registrato con integrazioni gestite per AWS IoT Device Management. Per ulteriori informazioni, consulta [Usa un connettore C2C (Cloud-to-Cloud)](use-c2c-create-cloud-connector.md).
# 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 comunichi con un fornitore APIs terzo per creare un connettore. Successivamente, richiama l'[CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html)API 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 **Connector ID** 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\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/iot-managedintegrations-createcloudconnector.png)
**Nota**
Usa [GetCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html), [UpdateCloudConnector[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html), e [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs se necessario per questa procedura.
1. **CreateConnectorDestination**
Configura Destinazioni per fornire le impostazioni e le credenziali di autenticazione necessarie ai connettori per stabilire connessioni sicure con i cloud di fornitori di terze parti. Utilizza Destinations per registrare le credenziali di autenticazione di terze parti con integrazioni gestite, ad esempio i dettagli di autorizzazione OAuth 2.0, tra cui l'URL di autorizzazione, lo schema di autenticazione e la posizione delle credenziali all'interno. Gestione dei segreti AWS
**Prerequisiti**
Prima di creare un **ConnectorDestination**, devi:
+ Chiama l'[CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html)API per creare un connettore. L'ID restituito dalla funzione viene utilizzato nella chiamata [CreateConnectorDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html)API API.
+ Recupera il `tokenUrl` file per la piattaforma 3P del connettore. **(Puoi scambiare un **AuthCode** con un AccessToken).**
+ Recupera l'**AuthURL per la piattaforma 3P** del connettore. (Gli utenti finali possono autenticarsi utilizzando nome utente e password).
+ Usa `clientId` e `clientSecret` (dalla piattaforma 3P) nel gestore segreto del tuo account.
**Esempio di richiesta e risposta CreateConnectorDestination API:**
```
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": "", // The connectorID instance from response of Step 1.
"SecretsManager": {
"arn": "arn:aws:secretsmanager:*****:secret:*******",
"versionId": "********"
},
"ClientToken": "***"
}
Response:
{
"Id":"string"
}
```
**Flusso di creazione di destinazioni cloud:**
![\[CreateConnectorDestination Fase di richiamo dell'API\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/iot-managedintegrations-createconnectordestination.png)
**Nota**
Utilizzare [GetCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html), [UpdateCloudConnector[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html), e [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs se necessario per questa procedura.
1. **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:
+ Chiama l'[CreateConnectorDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html)API per creare una destinazione. L'ID restituito dalla funzione viene utilizzato nella chiamata [CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html)API.
+ Richiama l'[CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html)API.
**Esempio di richiesta e risposta CreateAccountAssociation API:**
```
Request:
{
"Name": "CreateAccountAssociation",
"Description": "CreateAccountAssociation",
"ConnectorDestinationId": "", //The destinationID from destination creation.
"ClientToken": "***"
}
Response:
{
"Id":"string"
}
```
**Nota**
Utilizzare [GetCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html), [UpdateCloudConnector[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html), e [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs se necessario per questa procedura.
An **AccountAssociation**ha uno stato che viene interrogato da [GetAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetAccountAssociation.html)e. [ListAccountAssociations](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListAccountAssociations.html) APIs **Questi APIs mostrano lo stato dell'Associazione.** L'[StartAccountAssociationRefresh](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartAccountAssociationRefresh.html)API consente l'aggiornamento di uno **AccountAssociation**stato alla scadenza del relativo token di aggiornamento.
1. **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. Per scoprire un dispositivo 3P e creare un ManagedThing per il dispositivo 3P, è necessario seguire i passaggi seguenti in sequenza.
1. Chiama [StartDeviceDiscovery](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartDeviceDiscovery.html)l'API per avviare il processo di scoperta del dispositivo.
**Esempio di richiesta e risposta StartDeviceDiscovery API:**
```
Request:
{
"DiscoveryType": "CLOUD",
"AccountAssociationId": "*****",
"ClientToken": "abc"
}
Response:
{
"Id": "string",
"StartedAt": number
}
```
1. Richiama [GetDeviceDiscovery](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetDeviceDiscovery.html)l'API per verificare lo stato del processo di scoperta.
1. Invoca [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html)l'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"
}
```
1. Richiama l'[CreateManagedThing](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateManagedThing.html)API 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:XXXX:",
"AuthenticationMaterialType": "DISCOVERED_DEVICE",
"Name": "sample-device-name"
"ClientToken": "xxx"
}
Response:
{
"Arn": "string", // This is the ARN of the managedThing
"CreatedAt": number,
"Id": "string"
}
```
1. Invoca [GetManagedThing](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetManagedThing.html)l'API per visualizzare questa nuova creazione`managedThing`. Lo stato sarà`UNASSOCIATED`.
1. Invoca [RegisterAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_RegisterAccountAssociation.html)l'API per associarlo `managedThing` a uno specifico`accountAssociation`. Al termine di un'[RegisterAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_RegisterAccountAssociation.html)API di successo, lo `ASSOCIATED` stato `managedThing` cambia.
**Esempio di richiesta e risposta RegisterAccountAssociation API:**
```
Request:
{
"AccountAssociationId": "string",
"DeviceDiscoveryId": "string",
"ManagedThingId": "string"
}
Response:
{
"AccountAssociationId": "string",
"DeviceDiscoveryId": "string",
"ManagedThingId": "string"
}
```
1. **Invia un comando al dispositivo 3P**
Per controllare un dispositivo appena installato, utilizza l'[SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API, 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.
**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 del dispositivo 3P:**
![\[Invia il comando al dispositivo 3P\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/iot-managedintegrations-send-to-device.png)
1. **Il connettore invia eventi alle integrazioni gestite**
**L'[SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)API acquisisce quattro tipi di eventi dal connettore alle integrazioni gestite, rappresentati dai seguenti valori enum per il parametro Operation Type:**
+ **DEVICE\$1COMMAND\$1RESPONSE: la risposta** asincrona che il connettore invia in risposta a un comando.
+ **DEVICE\$1DISCOVERY**: in risposta a un processo di rilevamento dei dispositivi, il connettore invia l'elenco dei dispositivi rilevati alle integrazioni gestite, utilizza l'API. [SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)
+ **DEVICE\$1EVENT: invia gli eventi** del dispositivo ricevuti.
+ **DEVICE\$1COMMAND\$1REQUEST: richieste di comando avviate** dal dispositivo. Ad esempio, i flussi di lavoro WebRTC.
Il connettore può anche inoltrare gli eventi del dispositivo utilizzando l'[SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)API, con un parametro opzionale. `userId`
+ Per gli eventi dei dispositivi con`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 senza`userId`:
**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\]](http://docs.aws.amazon.com/it_it/iot-mi/latest/devguide/images/iot-managedintegrations-send-events.png)
1. **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 un AWS account specifico IDs 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.