Request Sync triggers a SYNC
request to your fulfillment for any Google user
with devices that have the specified agentUserId
associated with them (which you sent in the original SYNC request). This allows
you to update users' devices without unlinking and relinking their account. All
users linked to this identifier will receive a SYNC
request.
You must trigger a SYNC
request:
- If the user adds a new device.
- If the user removes an existing device.
- If the user renames an existing device.
- If you implement a new device type, trait, or add a new device feature.
Get started
To implement Request Sync, follow these steps:
Enable the Google HomeGraph API
-
In the Google Cloud Platform Console, go to the HomeGraph API page.
Go to the HomeGraph API page - Select the project that matches your smart home project ID.
- Click ENABLE.
Create a Service Account Key
Follow these instructions to generate a service account key from the GCP Console:
-
In the GCP Console, go to the Create service account key page.
Go to the Create Service Account Key page - From the Service account list, select New service account.
- In the Service account name field, enter a name.
- In the Service account ID field, enter a ID.
From the Role list, select Service Accounts > Service Account Token Creator.
For the Key type, select the JSON option.
- Click Create. A JSON file that contains your key downloads to your computer.
Call the API
HTTP POST
- Use the downloaded service account JSON file to create a JSON Web Token (JWT). For more information, see Authenticating Using a Service Account.
- Obtain an OAuth 2.0 access token with the
https://www.googleapis.com/auth/homegraph
scope using oauth2l: - Create the JSON request with the
agentUserId
. Here's a sample JSON request for Request Sync: - Combine the Request Sync JSON and the token in your HTTP POST
request to the Google Home Graph endpoint. Here's an example of how
to make the request in the command line using
curl
, as a test:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
Node.js
The Actions on Google library for Node.js supports Request Sync over HTTP.
- Place the downloaded service account JSON in your project directory.
- Pass the file location into your
smarthome
constructor. - Call the
requestSync
method with your payload. It returns a Promise.
const {smarthome} = require('actions-on-google'); const app = smarthome({ jwt: mySecretKeyJson }); // ... // New device is added for user app.requestSync('user-123') .then((res) => { // Request sync was successful }) .catch((res) => { // Request sync failed });
Java
The Actions on Google library for Java supports Request Sync over gRPC.
- Place the downloaded service account JSON in your project directory.
- Read the file location to generate a
GoogleCredentials
object. - Call the
requestSync
method with your payload. It returns a server response.
private void onDeviceAdded() throws IOException { FileInputStream stream = new FileInputStream("service-account-key.json"); GoogleCredentials credentials = GoogleCredentials.fromStream(stream); mySmartHomeApp.setCredentials(credentials); RequestSyncDevicesResponse response = mySmartHomeApp.requestSync("user-123"); }
Error responses
You may receive one of the following error responses when calling Request Sync. These responses come in the form of HTTP status codes.
400
- Failure: The server was unable to process the request sent by the client due to invalid syntax. Common causes include malformed JSON or usingnull
instead of "" for a string value.403
- Failure: The server was unable to process the the request for givenagentUserId
due to an error while refreshing the token. Please make sure your OAuth endpoint responds correctly to refresh token request and check the user's account linking status.404
- Failure: The requested resource could not be found but may be available in the future. Typically, this means that the user account is not linked with Google or we received an invalidagentUserId
. Ensure that theagentUserId
matches the value provided in your SYNC response, and you are properly handling DISCONNECT intents.429
- Failure: Maximum number of concurrent sync requests has been exceeded for the givenagentUserId
. A caller may only issue one concurrent sync request unless theasync
flag is set to true.