Subscribe to Events

Events are asynchronous and managed by Google Cloud Pub/Sub, in a single topic per Project. Events provide updates for all devices and structures and receipt of events is assured as long as the access token is not revoked by the user and the event messages have not expired.

Note: If your Device Access integration relies on Pub/Sub events and rarely makes API calls, the user's authorization will be revoked if the refresh token expires. For continued access, you must use the refresh token to refresh the access token within 6 months. For further help with authorization, see Refresh token expiration.

Events are an optional feature of the SDM API. They can easily be implemented and verified by using your Google Cloud project.

Enable events

Events may be enabled in the Device Access Console. Select your Project in the Console, if you haven't already.

Go to the Device Access Console

If you've already enabled events (for example, during project creation), the Pub/Sub topic field in the Project Info section should already have a value, called a Topic ID, in the format of:

projects/sdm-prod/topics/enterprise-project-id

If you haven't enabled events:

1. Click the icon for Pub/Sub topic and select Edit.
2. Check Enable events and click Save.
3. A Topic ID is generated for you in the format shown above.

Copy your Topic ID, you'll need it to create a subscription to the topic so event messages can be retrieved.

Create a pull subscription

A pull subscription is where a subscriber initiates requests to the Pub/Sub server for queued event messages. This is a quick and easy way to verify that events are being generated for your authorized devices.

Open Cloud Shell for your Google Cloud project:

Go to Google Cloud Shell

At the Cloud Shell prompt, run the following command to create a pull subscription to your topic, using whatever subscription-id you like and your unique Topic ID:

gcloud pubsub subscriptions create subscription-id --topic=projects/sdm-prod/topics/enterprise-project-id
Created subscription [projects/gcp-project-name/subscriptions/subscription-id].

Initiate events

To initiate events for the first time once the Pub/Sub subscription has been created, make a call to list your devices as a one-time trigger:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

Events for all structures and devices will publish after this API call.

Generate events

Events are generated for all trait field changes, some of which are automatic, some manual.

For example, if the ambient temperature near your Nest Thermostat changes, an event for the Temperature trait will automatically be sent with a new ambientTemperatureCelsius value.

To manually generate one, either:

1. Physically change the state of your device, such as changing the mode of your Nest Thermostat.
2. Trigger an event, such as motion, person, or sound on a Google Nest Cam Indoor.
3. Execute a device command using the SDM API.

View messages

Event messages can be viewed in your Google Cloud project, in the Pub/Sub Subscriptions section:

Go to Google Cloud Pub/Sub Subscriptions

1. Click on the Subscription ID you created earlier.
2. On the Subscription detail screen, you should see activity for the Unacked message count chart. This indicates event messages have come through for your subscription. If you don't see any activity, wait a little while or generate a few more events.
3. Click VIEW MESSAGES to bring up the Messages panel.
4. Click PULL to view the messages. They should correspond to the actions you used to generate events.

Messages can also be viewed in Cloud Shell with a basic pull command:

gcloud pubsub subscriptions pull subscription-id

For more information on subscription types, as well as the types of events sent by the SDM API and how to use them, see Events.

Manage messages

Messages should be regularly acknowledged and purged, to keep a subscription clean and avoid duplicate message delivery to other subscribers. All subscription messages can manually be purged in the Pub/Sub Subscriptions section:

Go to Google Cloud Pub/Sub Subscriptions

1. Click on the Subscription ID.
2. There are a few ways to acknowledge and purge:
   1. Click VIEW MESSAGES to bring up the Messages panel. Check the Enable ack messages checkbox and click PULL to view and acknowledge all messages.
   2. Click PURGE MESSAGES to purge all existing messages by acknowledging without viewing them. Click PURGE to confirm.

Messages can also be purged in Cloud Shell by using the --auto-ack flag with a basic pull command:

gcloud pubsub subscriptions pull subscription-id --auto-ack

Manage subscriptions

Subscriptions may be configured in a variety of ways, as described in Using subscription properties.

While how you want to manage subscriptions and messages is up to you, for a production application we recommend that you use Service accounts for authentication, rather than a user account like you have so far in this quick start guide. A service account is used by an application or virtual machine, not a person, and has its own unique account key.

For more information on service account authentication with Device Access, see Events.