1. Introduzione
Il programma Accesso ai dispositivi fornisce l'API Smart Device Management, un'API REST che consente agli sviluppatori di controllare i dispositivi Google Nest dalle loro applicazioni. Gli utenti devono dare il consenso per l'accesso di terze parti ai loro dispositivi Nest.
Esistono tre passaggi chiave per un'integrazione di Accesso ai dispositivi efficace:
- Creazione di un progetto: crea un progetto nella piattaforma Google Cloud e registrati come sviluppatore nella console Accesso ai dispositivi.
- Collegamento dell'account: incoraggia gli utenti attraverso il flusso di collegamento dell'account e recupera un codice di accesso. Scambia il codice con un token di accesso.
- Controllo dispositivo: effettua richieste all'API Smart Device Management per controllare i dispositivi inviando comandi con il token di accesso.
In questo codelab, approfondiremo il funzionamento dell'accesso ai dispositivi creando un'applicazione web per la gestione dell'autenticazione ed effettuando chiamate all'API Smart Device Management. Esploreremo anche il deployment di un semplice server proxy utilizzando Node.js ed Express per instradare le richieste di accesso ai dispositivi.
Prima di iniziare, ti consigliamo di ripassare le tecnologie web comuni che utilizzeremo in questo codelab, ad esempio l'autenticazione con OAuth 2.0 o la creazione di un'app web con Node.js, anche se non sono prerequisiti.
Cosa ti serve
- Node.js 8 o versioni successive
- Account Google con un Nest Thermostat collegato
Obiettivi didattici
- Configurazione di un progetto Firebase che ospita pagine web statiche e Cloud Functions
- Invio di richieste di accesso al dispositivo tramite un'applicazione web basata su browser
- Creazione di un server proxy con Node.js ed Express per instradare le richieste
2. Creazione di progetti
Per configurare l'integrazione di Accesso ai dispositivi, gli sviluppatori devono creare un progetto Google Cloud Platform (Google Cloud). Un ID client e un client secret generati all'interno del progetto Google Cloud verranno utilizzati nell'ambito del flusso OAuth tra l'applicazione dello sviluppatore e Google Cloud. Gli sviluppatori devono anche visitare la console di Accesso ai dispositivi per creare un progetto per accedere all'API Smart Device Management.
Piattaforma Google Cloud
Vai alla piattaforma Google Cloud. Fai clic su Crea un nuovo progetto e fornisci un nome al progetto. Verrà visualizzato anche l'ID progetto [GCP-Project-Id] per Google Cloud. Registralo perché verrà utilizzato durante la configurazione di Firebase. Faremo riferimento a questo ID come [GCP-Project-Id] in questo codelab.
Il primo passaggio consiste nell'abilitare la libreria API necessaria nel nostro progetto. Vai su API e Servizi > Library e cerca l'API Smart Device Management. Devi abilitare questa API per autorizzare il progetto a effettuare richieste alle chiamate API Device Access.
Prima di procedere con la creazione delle credenziali OAuth, dobbiamo configurare la schermata per il consenso OAuth per il nostro progetto. Vai a API e servizi > Schermata consenso OAuth. In Tipo di utente, scegli esterno. Fornisci un nome e un'email di assistenza per la tua app, nonché i dati di contatto dello sviluppatore per completare la prima schermata. Quando ti viene chiesto di indicare Utenti di test, assicurati di fornire l'indirizzo email dei dispositivi collegati in questo passaggio.
Dopo aver configurato la schermata per il consenso OAuth, vai ad API e servizi > Credenziali. Fai clic su +Crea credenziali e seleziona ID client OAuth. Per il tipo di applicazione, seleziona Applicazione web.
Specifica un nome per il cliente e fai clic su CREA. Aggiungeremo un'origine JavaScript autorizzata e un URI di reindirizzamento autorizzato in un secondo momento. Al termine di questa procedura verranno visualizzati [Client-Id] e [Client-Secret] associati a questo client OAuth 2.0.
Console Accesso ai dispositivi
Vai alla Console Accesso ai dispositivi. Se non hai mai utilizzato la Console Accesso ai dispositivi, riceverai il contratto relativo ai Termini di servizio e una quota di registrazione di $5.
Crea un nuovo progetto e assegnagli un nome. Nella finestra successiva, fornisci l'[Client-Id] ricevuto da Google Cloud nel passaggio precedente.
Se attivi gli eventi e completi i passaggi per la creazione del progetto, verrà visualizzata la home page del progetto. [Project-Id] verrà visualizzato sotto il nome che hai assegnato al progetto.
Prendi nota di [Project-Id] perché lo utilizzeremo per inviare richieste all'API Smart Device Management.
3. Configurazione di Firebase
Firebase offre agli sviluppatori un modo semplice e veloce per eseguire il deployment di applicazioni web. Svilupperemo un'applicazione web lato client per la nostra integrazione di Accesso al dispositivo utilizzando Firebase.
Crea un progetto Firebase
Vai alla Console Firebase. Fai clic su Aggiungi progetto, quindi seleziona il progetto che hai creato al passaggio Creazione del progetto. Verrà creato un progetto Firebase che verrà collegato al tuo progetto Google Cloud [GCP-Project-Id].
Una volta creato il progetto Firebase, viene visualizzata la seguente schermata:
Installa gli strumenti di Firebase
Firebase fornisce un insieme di strumenti a riga di comando per compilare e implementare l'app. Per installare questi strumenti, apri una nuova finestra del terminale ed esegui il seguente comando. Verranno installati gli strumenti Firebase a livello globale.
$ npm i -g firebase-tools
Per verificare che gli strumenti Firebase siano installati correttamente, controlla le informazioni sulla versione.
$ firebase --version
Puoi accedere agli strumenti dell'interfaccia a riga di comando di Firebase con il tuo Account Google utilizzando il comando login.
$ firebase login
Inizializza progetto di hosting
Quando sei in grado di accedere, il passaggio successivo è inizializzare un progetto di hosting per la tua applicazione web. Dal terminale, vai alla cartella in cui vuoi creare il progetto ed esegui il seguente comando:
$ firebase init hosting
Firebase ti porrà una serie di domande per iniziare a utilizzare un progetto di hosting:
- Seleziona un'opzione: Utilizza un progetto esistente
- Seleziona un progetto Firebase predefinito per questa directory: Scegli***[GCP-Project-Id]***
- Quale directory pubblica vuoi utilizzare? - Pubblico
- Configurare come app a pagina singola? - Sì
- Vuoi configurare build e deployment automatici con GitHub? - No
Una volta inizializzato il progetto, puoi eseguirne il deployment in Firebase con il seguente comando:
$ firebase deploy
Firebase eseguirà la scansione del progetto e implementerà i file necessari nell'hosting cloud.
Quando apri l'URL di hosting in un browser, dovresti vedere la pagina appena di cui hai eseguito il deployment:
Ora che conosci le nozioni di base su come eseguire il deployment di una pagina web con Firebase, passiamo al deployment del nostro esempio di Codelab.
4. Esempio di codelab
Puoi clonare il repository codelab ospitato su GitHub utilizzando il comando seguente:
$ git clone https://github.com/google/device-access-codelab-web-app.git
In questo repository forniamo esempi in due cartelle separate. La cartella codelab-start contiene i file necessari per iniziare dal punto attuale di questo codelab. La cartella codelab-done contiene una versione completa di questo codelab, con il client completamente funzionale e il server node.js.
Useremo i file dalla cartella codelab-start in questo codelab, ma se ti blocchi in qualsiasi momento ti invitiamo a fare riferimento anche alla versione completata dal codelab.
File di esempio codelab
La struttura dei file della cartella codelab-start è la seguente:
public ├───index.html ├───scripts.js ├───style.css firebase.json
La cartella pubblica contiene pagine statiche della nostra applicazione. firebase.json è responsabile dell'instradamento delle richieste web alla nostra app. Nella versione codelab-done, vedrai anche una directory functions, contenente la logica per il nostro server proxy (express) di cui eseguire il deployment su Google Cloud Functions.
Esempio di deployment di codelab
Copia i file da codelab-start nella directory del progetto.
$ firebase deploy
Al termine del deployment di Firebase, dovresti essere in grado di vedere l'applicazione Codelab:
Per avviare il flusso di autenticazione sono necessarie le credenziali del partner, che verranno trattate nella sezione successiva.
5. Gestione di OAuth
OAuth è lo standard web per la delega dell'accesso, comunemente utilizzata dagli utenti per concedere alle applicazioni di terze parti l'accesso ai dati del proprio account senza condividere le password. Utilizziamo OAuth 2.0 per consentire agli sviluppatori di accedere ai dispositivi degli utenti tramite Accesso al dispositivo.
Specifica URI di reindirizzamento
Il primo passaggio del flusso OAuth prevede il passaggio di un insieme di parametri all'endpoint OAuth 2.0 di Google. Dopo aver ottenuto il consenso dell'utente, i server OAuth di Google emettono una richiesta con un codice di autorizzazione all'URI di reindirizzamento.
Aggiorna la costante SERVER_URI (riga 19) con il tuo URL di Hosting in scripts.js:
const SERVER_URI = "https://[GCP-Project-Id].web.app";
Se esegui di nuovo il deployment dell'app con questa modifica, l'URI di reindirizzamento utilizzato per il progetto verrà aggiornato.
$ firebase deploy
Attivare l'URI di reindirizzamento
Dopo aver aggiornato l'URI di reindirizzamento nel file di script, devi aggiungerlo all'elenco degli URI di reindirizzamento consentiti per l'ID client che hai creato per il progetto. Vai alla pagina Credenziali in Google Cloud Platform, dove sono elencate tutte le credenziali create per il tuo progetto:
Nell'elenco ID client OAuth 2.0, seleziona l'ID client che hai creato nel passaggio Creazione progetto. Aggiungi l'URI di reindirizzamento dell'app all'elenco di URI di reindirizzamento autorizzati per il tuo progetto.
Prova ad accedere.
Vai all'URL di hosting che hai configurato con Firebase, inserisci le credenziali del partner e fai clic sul pulsante ACCEDI. L'ID client e il client secret sono le credenziali che hai ottenuto da Google Cloud Platform, mentre l'ID progetto proviene dalla console Accesso ai dispositivi.
Il pulsante ACCEDI guiderà gli utenti attraverso il flusso OAuth per la tua azienda, a partire dalla schermata di accesso al loro Account Google. Dopo aver eseguito l'accesso, agli utenti verrà chiesto di fornire le autorizzazioni del tuo progetto per accedere ai loro dispositivi Nest.
Poiché questa è un'app fittizia, Google emetterà un avviso prima di emettere un reindirizzamento.
Fai clic su "Avanzate", poi seleziona "Vai a web.app (non sicuro)". per completare il reindirizzamento alla tua app.
Nella richiesta GET in arrivo verrà fornito un codice OAuth, che l'app scambierà poi con un token di accesso e un token di aggiornamento.
6. Controllo dei dispositivi
L'app di esempio Accesso dispositivo utilizza le chiamate dell'API REST Smart Device Management per controllare i dispositivi Google Nest. Queste chiamate implicano il passaggio del token di accesso nell'intestazione di una richiesta GET o POST, insieme a un payload necessario per determinati comandi.
Abbiamo scritto una funzione generica di richiesta di accesso per gestire queste chiamate. Tuttavia, sarà necessario fornire a questa funzione l'endpoint corretto e l'oggetto payload quando necessario.
function deviceAccessRequest(method, call, localpath, payload = null) {...}
- method: tipo di richiesta HTTP (
GEToPOST) - chiamata : una stringa che rappresenta la chiamata API, utilizzata per instradare le risposte (
listDevices,thermostatMode,temperatureSetpoint) - localpath: l'endpoint a cui viene effettuata la richiesta, contenente l'ID progetto e l'ID dispositivo (aggiunto dopo
https://smartdevicemanagement.googleapis.com/v1) - payload (*): dati aggiuntivi richiesti per la chiamata all'API (ad esempio, un valore numerico che rappresenta la temperatura per un setpoint)
Creeremo controlli UI di esempio (Elenca dispositivi, Imposta modalità, Imposta temp.) per controllare un Nest Thermostat:
Questi controlli UI chiameranno le funzioni corrispondenti (listDevices(), postThermostatMode(), postTemperatureSetpoint()) da scripts.js. Vengono lasciate vuote per consentirti di implementarle. L'obiettivo è scegliere il metodo/percorso corretto e passare il payload alla funzione deviceAccessRequest(...).
Elenco dispositivi
La chiamata di Accesso al dispositivo più semplice è listDevices. Utilizza una richiesta GET e non richiede payload. L'endpoint deve essere strutturato utilizzando projectId. Completa la funzione listDevices() nel seguente modo:
function listDevices() {
var endpoint = "/enterprises/" + projectId + "/devices";
deviceAccessRequest('GET', 'listDevices', endpoint);
}
Salva le modifiche ed esegui di nuovo il deployment del progetto Firebase con il seguente comando:
$ firebase deploy
Una volta implementata la nuova versione dell'app, prova a ricaricare la pagina e fai clic su ELENCA DISPOSITIVI. Dovrebbe apparire nell'elenco sotto Controllo dispositivi, dove dovresti vedere l'ID del tuo termostato:
Se selezioni i dispositivi dall'elenco, il campo deviceId verrà aggiornato nel file scripts.js. Per i prossimi due controlli, dovremo specificare deviceId per il dispositivo specifico che vogliamo controllare.
Controllo del termostato
Il controllo di base di Nest Thermostat nell'API Smart Device Management offre due caratteristiche. ThermostatMode e TemperatureSetpoint. ThermostatMode imposta la modalità di Nest Thermostat su una delle quattro possibili modalità: {Off, Heat, Cool, HeatCool}. Quindi, dobbiamo fornire la modalità selezionata come parte del payload.
Sostituisci la funzione postThermostatMode() in scripts.js con quanto segue:
function postThermostatMode() {
var endpoint = "/enterprises/" + projectId + "/devices/" + deviceId + ":executeCommand";
var tempMode = id("tempMode").value;
var payload = {
"command": "sdm.devices.commands.ThermostatMode.SetMode",
"params": {
"mode": tempMode
}
};
deviceAccessRequest('POST', 'thermostatMode', endpoint, payload);
}
La funzione successiva, postTemperatureSetpoint(), gestisce l'impostazione della temperatura (in Celsius) per Nest Thermostat. Nel payload possono essere impostati due parametri, heatCelsius e coolCelsius, a seconda della modalità del termostato selezionata.
function postTemperatureSetpoint() {
var endpoint = "/enterprises/" + projectId + "/devices/" + deviceId + ":executeCommand";
var heatCelsius = parseFloat(id("heatCelsius").value);
var coolCelsius = parseFloat(id("coolCelsius").value);
var payload = {
"command": "",
"params": {}
};
if ("HEAT" === id("tempMode").value) {
payload.command = "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat";
payload.params["heatCelsius"] = heatCelsius;
}
else if ("COOL" === id("tempMode").value) {
payload.command = "sdm.devices.commands.ThermostatTemperatureSetpoint.SetCool";
payload.params["coolCelsius"] = coolCelsius;
}
else if ("HEATCOOL" === id("tempMode").value) {
payload.command = "sdm.devices.commands.ThermostatTemperatureSetpoint.SetRange";
payload.params["heatCelsius"] = heatCelsius;
payload.params["coolCelsius"] = coolCelsius;
} else {
console.log("Off and Eco mode don't allow this function");
return;
}
deviceAccessRequest('POST', 'temperatureSetpoint', endpoint, payload);
}
7. Server Node.js (facoltativo)
Complimenti! Hai creato un'applicazione web lato client che può inviare richieste all'API Smart Device Management da un browser. Per chi vuole creare sul lato server, vogliamo aiutarti a iniziare con un server proxy che può reindirizzare le richieste dal browser.
Per questo server proxy, utilizzeremo Cloud Functions per Firebase, Node.js ed Express.
Inizializza Cloud Functions
Apri una nuova finestra del terminale, vai alla directory del progetto ed esegui questo comando:
$ firebase init functions
Firebase ti porrà una serie di domande per inizializzare Cloud Functions:
- Quale linguaggio vuoi utilizzare per scrivere le funzioni Cloud? - JavaScript
- Vuoi utilizzare ESLint per individuare probabili bug e applicare lo stile? - No
- Vuoi installare le dipendenze con npm ora? - Sì
Questa operazione inizializza una cartella functions nel progetto e installa le dipendenze necessarie. Vedrai che la cartella del progetto contiene una directory functions, con un file index.js per definire le funzioni cloud, package.json per definire le impostazioni e una directory node_modules per contenere le dipendenze.
Per creare la funzionalità lato server utilizzeremo due librerie npm: express e xmlhttprequest. Dovrai aggiungere le seguenti voci all'elenco delle dipendenze nel file package.json:
"xmlhttprequest": "^1.8.0", "express": "^4.17.0"
Quindi, eseguire l'installazione di npm dalla directory Functions dovrebbe installare le dipendenze per il progetto:
$ npm install
Se npm riscontra un problema con il download dei pacchetti, puoi provare a salvare xmlhttprequest ed express esplicitamente con il seguente comando:
$ npm install express xmlhttprequest --save
Eseguire l'upgrade al piano Blaze
Per utilizzare il comando firebase deploy devi eseguire l'upgrade al piano Blaze, che richiede l'aggiunta di un metodo di pagamento al tuo account. Vai a Panoramica del progetto > Utilizzo e fatturazione e assicurati di selezionare il piano Blaze per il tuo progetto.
Crea Express Server
Un server Express segue un semplice framework per rispondere alle richieste GET e POST in arrivo. Abbiamo creato un servlet che ascolta le richieste POST, le trasmette a un URL di destinazione specificato nel payload e risponde con la risposta ricevuta dal trasferimento.
Modifica il file index.js nella directory Functions in modo che abbia il seguente aspetto:
const XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
const functions = require('firebase-functions');
const express = require('express');
const http = require('http');
const app = express();
app.use(express.json());
//***** Device Access - Proxy Server *****//
// Serving Get Requests (Not used)
app.get('*', (request, response) => {
response.status(200).send("Hello World!");
});
// Serving Post Requests
app.post('*', (request, response) => {
setTimeout(() => {
// Read the destination address from payload:
var destination = request.body.address;
// Create a new proxy post request:
var xhr = new XMLHttpRequest();
xhr.open('POST', destination);
// Add original headers to proxy request:
for (var key in request.headers) {
var value = request.headers[key];
xhr.setRequestHeader(key, value);
}
// Add command/parameters to proxy request:
var newBody = {};
newBody.command = request.body.command;
newBody.params = request.body.params;
// Respond to original request with the response coming
// back from proxy request (to Device Access Endpoint)
xhr.onload = function () {
response.status(200).send(xhr.responseText);
};
// Send the proxy request!
xhr.send(JSON.stringify(newBody));
}, 1000);
});
// Export our app to firebase functions:
exports.app = functions.https.onRequest(app);
Per inoltrare le richieste al nostro server, dobbiamo modificare le riscritture da firebase.json come segue:
{
"hosting": {
"public": "public",
"ignore": [
"firebase.json",
"**/.*",
"**/node_modules/**"
],
"rewrites": [{
"source": "/proxy**",
"function": "app"
},{
"source": "**",
"destination": "/index.html"
}
]
}
}
In questo modo, gli URL che iniziano con /proxy verranno indirizzati al nostro server Express e il resto continuerà a indirizzare al nostro index.html.
Chiamate API proxy
Ora che il server è pronto, definiamo un URI del proxy in scripts.js per consentire al browser di inviare richieste a questo indirizzo:
const PROXY_URI = SERVER_URI + "/proxy";
Aggiungi poi una funzione proxyRequest scripts.js, che ha la stessa firma della funzione deviceAccessRequest(...), per le chiamate indirette di Accesso al dispositivo.
function proxyRequest(method, call, localpath, payload = null) {
var xhr = new XMLHttpRequest();
// We are doing our post request to our proxy server:
xhr.open(method, PROXY_URI);
xhr.setRequestHeader('Authorization', 'Bearer ' + accessToken);
xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
xhr.onload = function () {
// Response is passed to deviceAccessResponse function:
deviceAccessResponse(call, xhr.response);
};
// We are passing the device access endpoint in address field of the payload:
payload.address = "https://smartdevicemanagement.googleapis.com/v1" + localpath;
if ('POST' === method && payload)
xhr.send(JSON.stringify(payload));
else
xhr.send();
}
L'ultimo passaggio prevede la sostituzione delle chiamate deviceAccessRequest(...) con la funzione proxyRequest(...), nelle funzioni postThermostatMode() e postTemperatureSetpoint() all'interno di scripts.js.
Esegui firebase deploy per aggiornare l'app.
$ firebase deploy
Con questo, ora hai un server proxy Node.js in esecuzione che utilizza Express su Cloud Functions.
Fornire le autorizzazioni per Cloud Functions
L'ultimo passaggio consiste nel rivedere le autorizzazioni di accesso per le tue funzioni Cloud Functions e assicurarti che l'applicazione lato client sia in grado di chiamarle.
Da Google Cloud Platform, vai alla scheda Cloud Functions dal menu, quindi seleziona la funzione Cloud Functions:
Fai clic su Autorizzazioni, quindi su Aggiungi membro. Scrivi allUsers nel campo del nuovo membro e seleziona Cloud Functions > Invoker di Cloud Functions. Se fai clic su Salva, viene visualizzato un messaggio di avviso:
Se selezioni Consenti accesso pubblico, la tua applicazione lato client potrà utilizzare la funzione cloud.
Congratulazioni, hai completato tutti i passaggi. Ora puoi accedere alla tua app web e attivare i controlli dei dispositivi indirizzati tramite il server proxy.
Passaggi successivi
Cerchi modi per ampliare le tue competenze su Accesso al dispositivo? Consulta la documentazione sui trait per scoprire di più sul controllo di altri dispositivi Nest e sulla procedura di certificazione per conoscere la procedura per lanciare il tuo prodotto in tutto il mondo.
Migliora le tue competenze con l'app di esempio dell'applicazione web Accesso ai dispositivi, dove potrai ampliare la tua esperienza Codelab ed eseguire il deployment di un'applicazione web funzionante per controllare videocamere, campanelli e termostati Nest.