aws-apigateway-iot

Tutte le classi sono in fase di sviluppo attivo e soggette a modifiche o rimozione non compatibili con le versioni precedenti in qualsiasi versione futura. Questi non sono soggetti allaControllo semantico delle versioniModello. Ciò significa che, mentre è possibile utilizzarli, potrebbe essere necessario aggiornare il codice sorgente quando si esegue l'aggiornamento a una versione più recente di questo pacchetto.

Nota: Per garantire la corretta funzionalità, i pacchetti AWS Solutions Constructs e i pacchetti AWS CDK nel progetto devono essere della stessa versione.

Linguaggio	Pacchetto
Python	aws_solutions_constructs.aws_apigateway_iot
TypeScript	@aws-solutions-constructs/aws-apigateway-iot
Java	software.amazon.awsconstructs.services.apigatewayiot

Overview

Questo Construct di soluzioni AWS implementa un'API REST del gateway API Amazon connessa al modello AWS IoT.

Questo costrutto crea un proxy HTTPS scalabile tra API Gateway e AWS IoT. Ciò risulta utile quando si desidera consentire ai dispositivi legacy che non supportano il protocollo MQTT o MQTT/WebSocket di interagire con la piattaforma AWS IoT.

Questa implementazione consente di pubblicare messaggi di sola scrittura su determinati argomenti MQTT e supporta anche gli aggiornamenti shadow dei dispositivi HTTPS agli elementi consentiti nel Registro di sistema dei dispositivi. Non coinvolge le funzioni Lambda per il proxy dei messaggi, e si basa invece sull'integrazione diretta API Gateway all'AWS IoT che supporta sia i messaggi JSON che i messaggi binari.

Ecco una definizione di modello distribuibile minima in TypeScript:

import { ApiGatewayToIot } from '@aws-solutions-constructs/aws-apigateway-iot';

new ApiGatewayToIot(this, 'ApiGatewayToIotPattern', {
    iotEndpoint: 'a1234567890123-ats'
});

Initializer

new ApiGatewayToIot(scope: Construct, id: string, props: ApiGatewayToIotProps);

Parametri

• scopeConstruct

• idstring

• propsApiGatewayToIotProps

Forme di costruzione modelli

Nome	Tipo	Descrizione
IOtendPoint	string	Sottodominio dell'endpoint AWS IoT per integrare il API Gateway con (ad esempio a1234567890123-ats).
ApiGatewayCreateApiKey?	boolean	Se è impostato sutrue, viene creata una chiave API e associata a un UsagePlan. L'utente deve specificare l'intestazione `x-api-key` durante l'accesso a RestApi. Valore predefinito impostato sufalse: .
ApiGatewayExecutionRole?	iam.Role	Il ruolo IAM utilizzato da API Gateway per accedere a AWS IoT. Se non viene specificato, viene creato un ruolo predefinito con accesso jolly ('*') a tutti gli argomenti e le cose.
ApiGatewayProps?	api.restApiProps	Oggetti di scena facoltativi forniti dall'utente per sovrascrivere gli oggetti di scena predefiniti per l'API REST del gateway API.
LogGroupProps?	logs.LogGroupProps	Argomenti facoltativi forniti dall'utente per sovrascrivere gli oggetti di scena predefiniti per il gruppo di log CloudWatch Logs.

Proprietà modello

Nome	Tipo	Descrizione
ApiGateway	api.RestApi	Restituisce un'istanza dell'API REST del gateway API creata dal modello.
APigatewayCloudWatchRole	iam.Role	Restituisce un'istanza del ruolo IAM creato dal pattern che abilita la registrazione degli accessi dall'API REST del gateway API a CloudWatch.
ApiGatewayLogGroup	logs.LogGroup	Restituisce un'istanza del gruppo di log creato dal modello a cui vengono inviati i log di accesso API REST del API Gateway API.
ApiGateWayRole	iam.Role	Restituisce un'istanza del ruolo IAM creato dal pattern per l'API REST del gateway API.

Impostazioni predefinite

L'implementazione predefinita di questo modello senza sostituzioni imposterà i seguenti valori predefiniti:

Amazon API Gateway

• Distribuisci di un endpoint API ottimizzato per gli edge

• Crea risorse API conPOSTMetodo per pubblicare messaggi in Argomenti IoT

• Crea risorse API conPOSTMetodo per pubblicare messaggi inThingShadoweNamedShadows

• Attivazione della registrazione CloudWatch per API Gateway

• Configurare il ruolo IAM per API Gateway con accesso a tutti gli argomenti

• Impostare l'AuthorizationType predefinito per tutti i metodi API su IAM

• Attiva traccia X-Ray

• Crea un UsagePlan e associa aprodfase

Di seguito è riportata una descrizione delle diverse risorse e metodi esposti dal API Gateway dopo la distribuzione del Costrutto. Consultare laEsempiper ulteriori informazioni su come testare facilmente questi endpoint tramitecurl: .

Metodo	Risorsa	Parametri di query	Codici restituiti	Descrizione
POST	/message/<topics>	qos	200/403/500	Chiamando questo endpoint, è necessario passare gli argomenti su cui si desidera pubblicare (ad es./message/device/foo»).
POST	/shadow/<thingName>	Nessuna	200/403/500	Questo percorso permette di aggiornare il documento shadow di una cosa, dato il suothingNameUtilizzando il tipo di copia shadow senza nome (classico). Il corpo deve essere conforme alla struttura ombreggiata standard comprendentestatenodo e associatodesiredereportedNodi. Consultare laAggiornamento di una copia shadowper un esempio.
POST	/shadow/<thingName>/<shadowName>	Nessuna	200/403/500	Questo percorso consente di aggiornare il documento shadow denominato di una cosa, dato il suothingNamee lashadowNameutilizzando il tipo di ombreggiatura con nome. Il corpo deve essere conforme alla struttura ombreggiata standard comprendentestatenodo e associatodesiredereportedNodi. Consultare laAggiornamento di una copia shadowper un esempio.

Architecture

Examples

Gli esempi seguenti funzionano solo conAPI_KEYtipi di autenticazione, dal momento che l'autorizzazione IAM richiede anche un token Sigv4 da specificare, assicurarsi che ilapiGatewayCreateApiKeydei tuoi oggetti di scena Construct è impostata sutruedurante la distribuzione dello stack, altrimenti gli esempi seguenti non funzioneranno.

Pubblicazione di un messaggio

È possibile utilizzarecurlper pubblicare un messaggio su diversi argomenti MQTT utilizzando l'API HTTPS. L'esempio seguente pubblicherà un messaggio suldevice/fooArgomento.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"Hello": "World"}'
      

Nota: Sostituisci ilstage-id,region, eapi-keycon i valori di distribuzione.

È possibile concatenare i nomi degli argomenti nell'URL e l'API accetta fino a 7 sottoargomenti su cui è possibile pubblicare. Ad esempio, nell'esempio seguente viene pubblicato un messaggio nell'argomentodevice/foo/bar/abc/xyz: .

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo/bar/abc/xyz -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"Hello": "World"}'
      

Aggiornamento di una copia shadow

Per aggiornare il documento shadow associato a una determinata cosa, è possibile emettere una richiesta di stato shadow utilizzando un nome di cosa. Consultare l'esempio seguente su come aggiornare una copia shadow di un oggetto.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/shadow/device1 -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"state": {"desired": { "Hello": "World" }}}'
      

Aggiornamento di una copia shadow

Per aggiornare il documento shadow associato all'ombra denominata di una determinata cosa, è possibile emettere una richiesta di stato shadow utilizzando un nome di cosa e un nome shadow. Vedere l'esempio seguente su come aggiornare un'ombra denominata.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/shadow/device1/shadow1 -H "x-api-key: <api-key>" -H "Content-Type: application/json" -d '{"state": {"desired": { "Hello": "World" }}}'
      

Invio di payload binari

È possibile inviare un payload binario all'API proxy, fino al servizio AWS IoT. Nell'esempio seguente viene inviato il contenuto della copiaREADME.mdassociato a questo modulo (trattato come dati binari) perdevice/fooArgomento tramiteapplication/octet-streamTipo di contenuto.

curl -XPOST https://<stage-id>.execute-api.<region>.amazonaws.com/prod/message/device/foo/bar/baz/qux -H "x-api-key: <api-key>" -H "Content-Type: application/octet-stream" --data-binary @README.md
      

Nota: Eseguire questo comando mentre si trova nella directory di questo progetto. È quindi possibile testare l'invio di altri tipi di file binari dal file system.

GitHub

Per visualizzare il codice per questo modello, creare/visualizzare problemi e richieste pull e altro ancora:
	@aws -solutions-constructs/aws-apigateway-iot