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.
Events are an optional feature of the SDM API. They can easily be implemented and verified by using your Google Cloud Platform (GCP) project.
Events may be enabled in the Device Access Console. Select your Project in the Console, if you haven't already.
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:
If you haven't enabled events:
- Click the icon for Pub/Sub topic and select Edit.
- Check Enable events and click Save.
- 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 GCP project:
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-idCreated subscription [projects/gcp-project-name/subscriptions/subscription-id].
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.
Events are generated for all trait field changes, some of which are automatic, some manual.
For example, if the ambient temperature near your
Google Nest Thermostat changes, an event for the
automatically be sent with a new
To manually generate one, either:
- Physically change the state of your device, such as changing the mode of your Nest Thermostat.
- Trigger an event, such as motion, person, or sound on a Google Nest Cam.
- Execute a device command using the SDM API.
Event messages can be viewed in your GCP project, in the Pub/Sub Subscriptions section:
- Click on the Subscription ID you created earlier.
- 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.
- Click VIEW MESSAGES to bring up the Messages panel.
- 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
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.
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:
- Click on the Subscription ID.
- There are a few ways to acknowledge and purge:
- Click VIEW MESSAGES to bring up the Messages panel. Check the Enable ack messages checkbox and click PULL to view and acknowledge all messages.
- 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
gcloud pubsub subscriptions pull subscription-id --auto-ack
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.