Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per imparare a sviluppare azioni per la smart home. Nota:continuerai a creare azioni nella Console Actions.

Richiedi sincronizzazione

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.
Puoi

La sincronizzazione delle richieste attiva una richiesta SYNC al tuo evasione per qualsiasi utente Google con dispositivi a cui è associato il valore agentUserId specificato (che hai inviato nella richiesta di sincronizzazione originale). In questo modo puoi aggiornare i dispositivi degli utenti senza scollegarli e ricollegarli. Tutti gli utenti collegati a questo identificatore riceveranno una richiesta SYNC.

Devi attivare una richiesta SYNC:

  • Se l'utente aggiunge un nuovo dispositivo.
  • Se l'utente rimuove un dispositivo esistente.
  • Se l'utente rinomina un dispositivo esistente.
  • Se implementi un nuovo tipo di dispositivo, una caratteristica o aggiungi una nuova funzionalità,

Inizia

Per implementare la richiesta di sincronizzazione, procedi nel seguente modo:

Abilita l'API Google HomeGraph

  1. In Google Cloud Console , go to the HomeGraph API page.

    Vai alla pagina dell'API HomeGraph
  2. Seleziona il progetto che corrisponde al tuo ID progetto smart home.
  3. Fai clic su ABILITA.

Crea una chiave dell'account di servizio

Segui queste istruzioni per generare una chiave dell'account di servizio da Google Cloud Console:

Nota: assicurati di utilizzare il progetto GCP corretto quando esegui questi passaggi. Questo è il progetto che corrisponde al tuo ID progetto smart home.
  1. In Google Cloud Console, vai alla pagina Crea chiave account di servizio.

    Vai alla pagina Crea chiave account di servizio
  2. Nell'elenco Account di servizio, seleziona Nuovo account di servizio.
  3. Inserisci un nome nel campo Service account name (Nome account di servizio).
  4. Inserisci un ID nel campo ID account di servizio.
  5. Dall'elenco Role (Ruolo), seleziona Service Accounts (Account di servizio) > Service Account Token Creator (Creatore token account di servizio).

  6. In Tipo di chiave, seleziona l'opzione JSON.

  7. Fai clic su Crea. Un file JSON contenente la chiave che viene scaricata sul computer.

Chiama l'API

HTTP

L'API Home Graph fornisce un endpoint HTTP

  1. Utilizza il file JSON dell'account di servizio scaricato per creare un JSON Web Token (JWT). Per maggiori informazioni, consulta la pagina Autenticazione con un account di servizio.
  2. Ottieni un token di accesso OAuth 2.0 con l'ambito https://www.googleapis.com/auth/homegraph utilizzando oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crea la richiesta JSON con agentUserId. Di seguito è riportato un esempio di richiesta JSON per Richiedi sincronizzazione:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Unisci il JSON di richiesta della sincronizzazione e il token nella richiesta POST HTTP all'endpoint di Google Home Graph. Ecco un esempio di come eseguire la richiesta dalla riga di comando utilizzando curl, come test:
  7. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d @request-body.json \
      "https://homegraph.googleapis.com/v1/devices:requestSync"
    

gRPC

L'API Home Graph fornisce un endpoint gRPC

  1. Recupera la definizione del servizio dei buffer di protocollo per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori gRPC per generare stub client per uno dei lingue supportati.
  3. Chiama il metodo RequestSync.

Node.js

Il client Node.js delle API di Google fornisce associazioni per l'API Home Graph.

  1. Inizializza il servizio google.homegraph utilizzando le credenziali predefinite dell'applicazione.
  2. Chiama il metodo requestSync con RequestSyncDevicesRequest. Restituisce Promise con un valore RequestSyncDevicesResponse vuoto.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

La libreria client dell'API HomeGraph per Java fornisce associazioni per l'API Home Graph.

  1. Inizializzare HomeGraphApiService utilizzando le credenziali predefinite dell'applicazione.
  2. Chiama il metodo requestSync con RequestSyncDevicesRequest. Restituisce un elemento ReportStateAndNotificationResponse vuoto.
// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

Risposte di errore

Quando chiami Richiesta sincronizzazione, potresti ricevere una delle seguenti risposte di errore. Queste risposte si presentano sotto forma di codici di stato HTTP.

  • 400 Bad Request: il server non è riuscito a elaborare la richiesta inviata dal client a causa di una sintassi non valida. Le cause comuni includono JSON non valido o utilizzando null invece di "" per un valore stringa.
  • 403 Forbidden: il server non è riuscito a elaborare la richiesta indicata per il messaggio agentUserId a causa di un errore durante l'aggiornamento del token. Assicurati che l'endpoint OAuth risponda correttamente per aggiornare le richieste di token e controlla lo stato del collegamento dell'account dell'utente.
  • 404 Not Found: non è stato possibile trovare la risorsa richiesta, ma potrebbe essere disponibile in futuro. In genere, ciò significa che l'account utente non è collegato a Google o abbiamo ricevuto un agentUserId non valido. Assicurati che agentUserId corrisponda al valore fornito nella risposta SYNC e gestisci correttamente gli intent DISCONNECT.
  • 429 Too Many Requests: è stato superato il numero massimo di richieste di sincronizzazione simultanee per il agentUserId specificato. Un chiamante può emettere una sola richiesta di sincronizzazione simultanea, a meno che il flag async non sia impostato su true.