Richiedi sincronizzazione

La richiesta di sincronizzazione attiva una richiesta SYNC al tuo partner di evasione per qualsiasi utente Google con dispositivi a cui è associato il valore agentUserId specificato (che hai inviato nella richiesta SYNC originale). In questo modo puoi aggiornare i dispositivi degli utenti senza scollegare e ricollegare il loro account. 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, un nuovo trait o aggiungi una nuova funzionalità del dispositivo.

Inizia

Per implementare la sincronizzazione delle richieste:

Abilita l'API Google HomeGraph

  1. In Google Cloud Console, vai alla pagina dell'API HomeGraph.

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

Creare 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 Google Cloud corretto quando esegui questi passaggi. Questo è il progetto corrispondente al tuo ID progetto smart home.
  1. In Google Cloud Console, vai alla pagina Crea chiave account di servizio.

    Vai alla pagina Crea chiave dell'account di servizio
  2. Dall'elenco Account di servizio, seleziona Nuovo account di servizio.
  3. Inserisci un nome nel campo Nome account di servizio.
  4. Nel campo ID account di servizio, inserisci un ID.
  5. Nell'elenco Ruolo, seleziona Account di servizio > Creatore token account di servizio.

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

  7. Fai clic su Crea. Sul computer viene scaricato un file JSON contenente la chiave.

Chiama l'API

HTTP

L'API HomeGraph fornisce un endpoint HTTP

  1. Utilizza il file JSON dell'account di servizio scaricato per creare un token web JSON (JWT). Per maggiori informazioni, consulta la sezione 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. Ecco una richiesta JSON di esempio per la sincronizzazione delle richieste:
  5. {
      "agentUserId": "user-123"
    }
  6. Combina il JSON di richiesta di sincronizzazione e il token nella richiesta POST HTTP all'endpoint di Google Home Graph. Ecco un esempio di come effettuare la richiesta nella 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 HomeGraph fornisce un endpoint gRPC

  1. Ottieni la definizione del servizio Protocol Buffers per l'API Home Graph.
  2. Segui la documentazione per gli sviluppatori di gRPC per generare stub di client per una delle lingue supportate.
  3. Chiama il metodo RequestSync.

Node.js

Il client Node.js per le 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 un Promise con un 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. Inizializza HomeGraphApiService utilizzando le Credenziali predefinite dell'applicazione.
  2. Chiama il metodo requestSync con RequestSyncDevicesRequest. Restituisce un 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 Request Sync, 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 è stato in grado di elaborare la richiesta inviata dal client a causa di una sintassi non valida. Le cause comuni includono JSON non valido o l'utilizzo di null anziché "" per un valore di stringa.
  • 403 Forbidden - Il server non è stato in grado di elaborare la richiesta per agentUserId specificato a causa di un errore durante l'aggiornamento del token. Assicurati che l'endpoint OAuth risponda correttamente alle richieste di aggiornamento dei token e controlla lo stato di collegamento dell'account dell'utente.
  • 404 Not Found - La risorsa richiesta non è stata trovata, ma potrebbe essere disponibile in futuro. In genere, significa che l'account utente non è collegato a Google o che abbiamo ricevuto un agentUserId non valido. Assicurati che agentUserId corrisponda al valore fornito nella risposta SYNC e che gestisci correttamente gli intent DISCONNECT.
  • 429 Too Many Requests: è stato superato il numero massimo di richieste di sincronizzazione contemporaneamente per agentUserId specificato. Un chiamante può inviare una sola richiesta di sincronizzazione in contemporanea a meno che il flag async non sia impostato su true.