Request Sync

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 should 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 the user change a device location such as rooms (only if your application supports this).
  • If you implement a new device type, trait, or add a new device feature.

Get started

To implement Report State:

Enable the API and download credentials

Do the following to implement Request Sync:

  1. In the Cloud Platform Console, go to the Projects page. Select the project that matches your smart home project id.

  2. Enable the Google HomeGraph API.

  3. Generate an API key. From the left navbar, select Credentials under APIs & Services. Click the Create Credentials button and select API key. Copy the API key for later use.

Call the API

Use the API key mentioned above and the agentUserId in your request. Here's an example of how to make the request in the command line using curl, as a test:

curl -i -s -X POST -H "Content-Type: application/json" -d "{agentUserId: \"agentUserId\", async: true}" "https://homegraph.googleapis.com/v1/devices:requestSync?key=API_KEY"

Code sample

Node.js

const {smarthome} = require('actions-on-google');
const app = smarthome({
  key: '123ABC'
});
// ...
// New device is added for user
app.requestSync('user-123')
  .then((res) => {
    // Request sync was successful
  })
  .catch((res) => {
    // Request sync failed
  });

Java

GCP Console

Note: Ensure that you are using the correct GCP project when performing these steps. This is the project that matches your smart home project ID.
  1. In the GCP Console, go to the Create service account key page.

    Go to the Create Service Account Key page
  2. From the Service account list, select New service account.
  3. In the Service account name field, enter a name.
  4. In the Service account ID field, enter a ID.
  5. From the Role list, select Service Accounts > Service Account Token Creator.

  6. For the Key type, select the JSON option.

  7. Click Create. A JSON file that contains your key downloads to your computer.
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");
}

Python

#!/usr/bin/env python

# Copyright 2018 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import argparse
import json

import requests
from six.moves import urllib

def request_sync(api_key, agent_user_id):
    url = 'https://homegraph.googleapis.com/v1/devices:requestSync?key=' + api_key
    data = {"agentUserId": agent_user_id};

    response = requests.post(url, json=data)

    print 'Response: ' + response.text

    return response.status_code == requests.codes.ok

def main(api_key, agent_user_id):
    if (request_sync(api_key, agent_user_id)):
        print 'Request Sync has been done successfully.'
    else:
        print 'Request Sync failed. Please check the log above.'

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument(
        'api_key',
        help='The api key downloaded from Google Cloud Platform Console.')
    parser.add_argument(
        'agent_user_id',
        help='The unique user ID on the agent\'s platform which returned in the SYNC response.')

    args = parser.parse_args()

    main(args.api_key, args.agent_user_id)

Error responses

See these possible responses to understand what you may receive back from Google upon making a Request Sync request.