From 0e07113e776bdd8fcc0783372e08bb6e76cb1b5b Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 25 Mar 2020 08:14:22 -0700 Subject: [PATCH] docs: Update documentation with links to smart home developer guides and reference pages. Remove outdated authorization instructions. PiperOrigin-RevId: 302892245 --- google/home/graph/v1/device.proto | 69 +++++------ google/home/graph/v1/homegraph.proto | 175 +++++++++++++-------------- 2 files changed, 116 insertions(+), 128 deletions(-) diff --git a/google/home/graph/v1/device.proto b/google/home/graph/v1/device.proto index d64f2694..0629e3a0 100644 --- a/google/home/graph/v1/device.proto +++ b/google/home/graph/v1/device.proto @@ -22,31 +22,34 @@ option go_package = "google.golang.org/genproto/googleapis/home/graph/v1;graph"; option java_outer_classname = "DeviceProto"; option java_package = "com.google.home.graph.v1"; -// Third-party partner's device definition. +// Third-party device definition. message Device { - // Third-party partner's device ID. + // Third-party device ID. string id = 1; - // Hardware type of the device (e.g. light, outlet, etc). + // Hardware type of the device. + // See [device + // types](https://developers.google.com/assistant/smarthome/guides). string type = 2; // Traits supported by the device. + // See [device + // traits](https://developers.google.com/assistant/smarthome/traits). repeated string traits = 3; - // Name of the device given by the third party. This includes names given to - // the device via third party device manufacturer's app, model names for the - // device, etc. + // Names given to this device by your smart home Action. DeviceNames name = 4; - // Indicates whether the state of this device is being reported to Google - // through ReportStateAndNotification call. + // Indicates whether your smart home Action will report state of this device + // to Google via [ReportStateAndNotification][]. bool will_report_state = 5; - // If the third-party partner's cloud configuration includes placing devices - // in rooms, the name of the room can be provided here. + // Suggested name for the room where this device is installed. + // Google attempts to use this value during user setup. string room_hint = 6; - // As in roomHint, for structures that users set up in the partner's system. + // Suggested name for the structure where this device is installed. + // Google attempts to use this value during user setup. string structure_hint = 7; // Device manufacturer, model, hardware version, and software version. @@ -55,31 +58,29 @@ message Device { // Attributes for the traits supported by the device. google.protobuf.Struct attributes = 9; - // Custom JSON data provided by the manufacturer and attached to QUERY and - // EXECUTE requests in AoG. + // Custom device attributes stored in Home Graph and provided to your + // smart home Action in each + // [QUERY](https://developers.google.com/assistant/smarthome/reference/intent/query) + // and + // [EXECUTE](https://developers.google.com/assistant/smarthome/reference/intent/execute) + // intent. google.protobuf.Struct custom_data = 10; - // IDs of other devices associated with this device. This is used to - // represent a device group (e.g. bonded zone) or "facets" synced - // through different flows (e.g. Google Nest Hub Max with a Nest Camera). - // - // This may also be used to pass in alternate IDs used to identify a cloud - // synced device for local execution (i.e. local verification). If used for - // local verification, this field is synced from the cloud. + // Alternate IDs associated with this device. + // This is used to identify cloud synced devices enabled for + // [local + // execution](https://developers.google.com/assistant/smarthome/concepts/local). repeated AgentOtherDeviceId other_device_ids = 11; - // Indicates whether the device is capable of sending notifications. This - // field will be set by the agent (partner) on an incoming SYNC. If a device - // is not capable of generating notifications, the partner should set this - // flag to false. If a partner is not capable of calling - // ReportStateAndNotification to send notifications to Google, the partner - // should set this flag to false. If there is a user setting in the partner - // app to enable notifications and it is turned off, the partner should set - // this flag to false. + // Indicates whether your smart home Action will report notifications + // to Google for this device via [ReportStateAndNotification][]. + // + // If your smart home Action enables users to control device notifications, + // you should update this field and call [RequestSyncDevices][]. bool notification_supported_by_agent = 12; } -// Different names for the device. +// Identifiers used to describe the device. message DeviceNames { // Primary name of the device, generally provided by the user. string name = 1; @@ -87,8 +88,8 @@ message DeviceNames { // Additional names provided by the user for the device. repeated string nicknames = 2; - // List of names provided by the partner rather than the user, often - // manufacturer names, SKUs, etc. + // List of names provided by the manufacturer rather than the user, such as + // serial numbers, SKUs, etc. repeated string default_names = 3; } @@ -107,11 +108,11 @@ message DeviceInfo { string sw_version = 4; } -// Identifies a device in the third party or first party system. +// Alternate third-party device ID. message AgentOtherDeviceId { - // The agent's ID. Generally it is the agent's AoG project id. + // Project ID for your smart home Action. string agent_id = 1; - // Device ID defined by the agent. The device_id must be unique. + // Unique third-party device ID. string device_id = 2; } diff --git a/google/home/graph/v1/homegraph.proto b/google/home/graph/v1/homegraph.proto index 982eb9dd..26e3e8df 100644 --- a/google/home/graph/v1/homegraph.proto +++ b/google/home/graph/v1/homegraph.proto @@ -32,21 +32,25 @@ option (google.api.resource_definition) = { pattern: "agentUsers/{agent_user_path=**}" }; -// Google HomeGraph API service. The HomeGraph service provides support for -// storing and querying first-party and third-party devices, rooms and -// structures, and the relationships among them and their state in the home. It -// stores entities and their relationships in the home. +// Google Home Graph API service. The Home Graph service provides support for +// accessing first-party and third-party devices stored in Google's Home Graph. +// The Home Graph database provides contextual data about the relationships +// between devices and the home. +// +// For more details, see the [Home Graph developer +// guide](https://developers.google.com/assistant/smarthome/concepts/homegraph). service HomeGraphApiService { option (google.api.default_host) = "homegraph.googleapis.com"; - // Requests a `SYNC` call from Google to a 3p partner's home control agent for - // a user. + // Requests Google to send an `action.devices.SYNC` + // [intent](https://developers.google.com/assistant/smarthome/reference/intent/sync) + // to your smart home Action to update device metadata for the given user. // // - // The third-party user's identity is passed in as `agent_user_id` - // (see [RequestSyncDevicesRequest][google.home.graph.v1.RequestSyncDevicesRequest]) and forwarded back to the agent. - // The agent is identified by the API key or JWT signed by the partner's - // service account. + // The third-party user's identity is passed via the `agent_user_id` + // (see [RequestSyncDevicesRequest][google.home.graph.v1.RequestSyncDevicesRequest]). + // This request must be authorized using service account credentials from your + // Actions console project. rpc RequestSyncDevices(RequestSyncDevicesRequest) returns (RequestSyncDevicesResponse) { option (google.api.http) = { post: "/v1/devices:requestSync" @@ -55,21 +59,22 @@ service HomeGraphApiService { option (google.api.method_signature) = "agent_user_id"; } - // Reports device state and optionally sends device notifications. Called by - // an agent when the device state of a third-party changes or the agent wants - // to send a notification about the device. See - // [Implement Report State](/actions/smarthome/report-state) for more - // information. - // This method updates a predefined set of states for a device, which all - // devices have according to their prescribed traits (for example, a light - // will have the [OnOff](/actions/smarthome/traits/onoff) trait that reports - // the state `on` as a boolean value). - // A new state may not be created and an INVALID_ARGUMENT code will be thrown - // if so. It also optionally takes in a list of Notifications that may be - // created, which are associated to this state change. + // Reports device state and optionally sends device notifications. + // Called by your smart home Action when the state of a third-party device + // changes or you need to send a notification about the device. + // See [Implement Report + // State](https://developers.google.com/assistant/smarthome/develop/report-state) + // for more information. // - // The third-party user's identity is passed in as `agent_user_id`. - // The agent is identified by the JWT signed by the partner's service account. + // This method updates the device state according to its declared + // [traits](https://developers.google.com/assistant/smarthome/concepts/devices-traits). + // Publishing a new state value outside of these traits will result in an + // `INVALID_ARGUMENT` error response. + // + // The third-party user's identity is passed in via the `agent_user_id` + // (see [ReportStateAndNotificationRequest][google.home.graph.v1.ReportStateAndNotificationRequest]). + // This request must be authorized using service account credentials from your + // Actions console project. rpc ReportStateAndNotification(ReportStateAndNotificationRequest) returns (ReportStateAndNotificationResponse) { option (google.api.http) = { post: "/v1/devices:reportStateAndNotification" @@ -78,31 +83,17 @@ service HomeGraphApiService { option (google.api.method_signature) = "request_id,event_id,agent_user_id,payload"; } - // Unlinks an agent user from Google. As a result, all data related to this - // user will be deleted. + // Unlinks the given third-party user from your smart home Action. + // All data related to this user will be deleted. // - // Here is how the agent user is created in Google: + // For more details on how users link their accounts, see + // [fulfillment and + // authentication](https://developers.google.com/assistant/smarthome/concepts/fulfillment-authentication). // - // 1. When a user opens their Google Home App, they can begin linking a 3p - // partner. - // 2. User is guided through the OAuth process. - // 3. After entering the 3p credentials, Google gets the 3p OAuth token and - // uses it to make a Sync call to the 3p partner and gets back all of the - // user's data, including `agent_user_id` and devices. - // 4. Google creates the agent user and stores a mapping from the - // `agent_user_id` -> Google ID mapping. Google also - // stores all of the user's devices under that Google ID. - // - // The mapping from `agent_user_id` to Google ID is many to many, since one - // Google user can have multiple 3p accounts, and multiple Google users can - // map to one `agent_user_id` (e.g., a husband and wife share one Nest account - // username/password). - // - // The third-party user's identity is passed in as `agent_user_id`. - // The agent is identified by the JWT signed by the partner's service account. - // - // Note: Special characters (except "/") in `agent_user_id` must be - // URL-encoded. + // The third-party user's identity is passed in via the `agent_user_id` + // (see [DeleteAgentUserRequest][google.home.graph.v1.DeleteAgentUserRequest]). + // This request must be authorized using service account credentials from your + // Actions console project. rpc DeleteAgentUser(DeleteAgentUserRequest) returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{agent_user_id=agentUsers/**}" @@ -110,10 +101,13 @@ service HomeGraphApiService { option (google.api.method_signature) = "request_id,agent_user_id"; } - // Gets the device states for the devices in [QueryRequest][google.home.graph.v1.QueryRequest]. - // The third-party user's identity is passed in as `agent_user_id`. The agent - // is identified by the JWT signed by the third-party partner's service - // account. + // Gets the current states in Home Graph for the given set of the third-party + // user's devices. + // + // The third-party user's identity is passed in via the `agent_user_id` + // (see [QueryRequest][google.home.graph.v1.QueryRequest]). + // This request must be authorized using service account credentials from your + // Actions console project. rpc Query(QueryRequest) returns (QueryResponse) { option (google.api.http) = { post: "/v1/devices:query" @@ -123,9 +117,11 @@ service HomeGraphApiService { } // Gets all the devices associated with the given third-party user. - // The third-party user's identity is passed in as `agent_user_id`. The agent - // is identified by the JWT signed by the third-party partner's service - // account. + // + // The third-party user's identity is passed in via the `agent_user_id` + // (see [SyncRequest][google.home.graph.v1.SyncRequest]). + // This request must be authorized using service account credentials from your + // Actions console project. rpc Sync(SyncRequest) returns (SyncResponse) { option (google.api.http) = { post: "/v1/devices:sync" @@ -139,8 +135,7 @@ service HomeGraphApiService { // [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices) // call. message RequestSyncDevicesRequest { - // Required. Third-party user ID issued by agent's third-party identity - // provider. + // Required. Third-party user ID. string agent_user_id = 1 [(google.api.field_behavior) = REQUIRED]; // Optional. If set, the request will be added to a queue and a response will @@ -151,7 +146,9 @@ message RequestSyncDevicesRequest { // Response type for the // [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices) -// call. Intentionally empty upon success. An HTTP response code is returned +// call. +// +// Intentionally empty upon success. An HTTP response code is returned // with more details upon failure. message RequestSyncDevicesResponse { @@ -159,11 +156,11 @@ message RequestSyncDevicesResponse { // Request type for the // [`ReportStateAndNotification`](#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification) -// call. It may include States, Notifications, or both. This request uses -// globally unique flattened state names instead of namespaces based on traits -// to align with the existing QUERY and EXECUTE APIs implemented by 90+ Smart -// Home partners. States and notifications are defined per `device_id` (for example, "123" -// and "456" in the following example). # Example +// call. It may include states, notifications, or both. States and notifications +// are defined per `device_id` (for example, "123" and "456" in the following +// example). +// # Example +// // ```json // { // "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", @@ -196,16 +193,7 @@ message ReportStateAndNotificationRequest { // Token to maintain state in the follow up notification response. string follow_up_token = 5; - // Required. State of devices to update and notification metadata for devices. For - // example, if a user turns a light on manually, a state update should be - // sent so that the information is always the current status of the device. - // Notifications are independent from the state and its piece of the payload - // should contain everything necessary to notify the user. Although it may be - // related to a state change, it does not need to be. For example, if a - // device can turn on/off and change temperature, the states reported would - // include both "on" and "70 degrees" but the 3p may choose not to send any - // notification for that, or to only say that the "the room is heating up", - // keeping state and notification independent. + // Required. State of devices to update and notification metadata for devices. StateAndNotificationPayload payload = 3 [(google.api.field_behavior) = REQUIRED]; } @@ -225,10 +213,14 @@ message StateAndNotificationPayload { // The states and notifications specific to a device. message ReportStateAndNotificationDevice { - // States of devices to update. + // States of devices to update. See the **Device STATES** section + // of the individual trait [reference + // guides](https://developers.google.com/assistant/smarthome/traits). google.protobuf.Struct states = 1; - // Notifications metadata for devices. + // Notifications metadata for devices. See the **Device NOTIFICATIONS** + // section of the individual trait [reference + // guides](https://developers.google.com/assistant/smarthome/traits). google.protobuf.Struct notifications = 2; } @@ -249,11 +241,7 @@ message DeleteAgentUserRequest { } // Request type for the -// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. This should -// be the same format as the Actions on Google `action.devices.QUERY` -// [request](/actions/smarthome/create-app#actiondevicesquery) with the -// exception of the extra `agent_user_id` and no `intent` and `customData` -// fields. +// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. message QueryRequest { // Request ID used for debugging. string request_id = 1; @@ -261,33 +249,34 @@ message QueryRequest { // Required. Third-party user ID. string agent_user_id = 2 [(google.api.field_behavior) = REQUIRED]; - // Required. Inputs containing third-party partner's device IDs for which to + // Required. Inputs containing third-party device IDs for which to // get the device states. repeated QueryRequestInput inputs = 3 [(google.api.field_behavior) = REQUIRED]; } // Device ID inputs to [QueryRequest][google.home.graph.v1.QueryRequest]. message QueryRequestInput { - // Payload containing third-party partner's device IDs. + // Payload containing third-party device IDs. QueryRequestPayload payload = 1; } // Payload containing device IDs. message QueryRequestPayload { - // Third-party partner's device IDs for which to get the device states. + // Third-party device IDs for which to get the device states. repeated AgentDeviceId devices = 1; } -// Third-party partner's device ID for one device. +// Third-party device ID for one device. message AgentDeviceId { - // Third-party partner's device ID. + // Third-party device ID. string id = 1; } // Response type for the -// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. This should -// follow the same format as the Actions on Google `action.devices.QUERY` -// [response](/actions/smarthome/create-app#actiondevicesquery). +// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. +// This should follow the same format as the Google smart home +// `action.devices.QUERY` +// [response](https://developers.google.com/assistant/smarthome/reference/intent/query). // # Example // // ```json @@ -328,10 +317,7 @@ message QueryResponsePayload { } // Request type for the [`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync) -// call. This should follow the same format as the Actions on Google -// `action.devices.SYNC` -// [request](/actions/smarthome/create-app#actiondevicessync) with the exception -// of the extra `agent_user_id` and no `intent` field. +// call. message SyncRequest { // Request ID used for debugging. string request_id = 1; @@ -341,9 +327,10 @@ message SyncRequest { } // Response type for the -// [`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync) call. This should -// follow the same format as the Actions on Google `action.devices.SYNC` -// [response](/actions/smarthome/create-app#actiondevicessync). +// [`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync) call. +// This should follow the same format as the Google smart home +// `action.devices.SYNC` +// [response](https://developers.google.com/assistant/smarthome/reference/intent/sync). // # Example // // ```json