From e1f78a6b6d2e8d50f7489d5e56eaa1a7137bfb7a Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 20 Jun 2018 16:05:09 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 201434004 --- google/home/graph/base.yaml | 4 + google/home/graph/v1/device.proto | 90 +++++++++++++ google/home/graph/v1/homegraph.proto | 155 +++++++++++++++++++++- google/home/graph/v1/homegraph_gapic.yaml | 26 ++++ 4 files changed, 273 insertions(+), 2 deletions(-) create mode 100644 google/home/graph/v1/device.proto diff --git a/google/home/graph/base.yaml b/google/home/graph/base.yaml index a3b55053..20c3ff8f 100644 --- a/google/home/graph/base.yaml +++ b/google/home/graph/base.yaml @@ -14,3 +14,7 @@ backend: deadline: 60.0 - selector: google.home.graph.v1.HomeGraphApiService.DeleteAgentUser deadline: 60.0 + - selector: google.home.graph.v1.HomeGraphApiService.Query + deadline: 60.0 + - selector: google.home.graph.v1.HomeGraphApiService.Sync + deadline: 60.0 diff --git a/google/home/graph/v1/device.proto b/google/home/graph/v1/device.proto new file mode 100644 index 00000000..62021289 --- /dev/null +++ b/google/home/graph/v1/device.proto @@ -0,0 +1,90 @@ +// Copyright 2018 Google Inc. +// +// 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. + +syntax = "proto3"; + +package google.home.graph.v1; + +import "google/protobuf/struct.proto"; + +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. +message Device { + // Third-party partner's device ID. + string id = 1; + + // Hardware type of the device (e.g. light, outlet, etc). + string type = 2; + + // Traits supported by the device. + 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. + DeviceNames name = 4; + + // Indicates whether the state of this device is being reported to Google + // through ReportStateAndNotification call. + 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. + string room_hint = 6; + + // As in roomHint, for structures that users set up in the partner's system. + string structure_hint = 7; + + // Device manufacturer, model, hardware version, and software version. + DeviceInfo device_info = 8; + + // 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. + string custom_data = 10; +} + +// Different names for the device. +message DeviceNames { + // Primary name of the device, generally provided by the user. + string name = 1; + + // 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. + repeated string default_names = 3; +} + +// Device information. +message DeviceInfo { + // Device manufacturer. + string manufacturer = 1; + + // Device model. + string model = 2; + + // Device hardware version. + string hw_version = 3; + + // Device software version. + string sw_version = 4; +} diff --git a/google/home/graph/v1/homegraph.proto b/google/home/graph/v1/homegraph.proto index 37cba267..194704b4 100644 --- a/google/home/graph/v1/homegraph.proto +++ b/google/home/graph/v1/homegraph.proto @@ -17,6 +17,7 @@ syntax = "proto3"; package google.home.graph.v1; import "google/api/annotations.proto"; +import "google/home/graph/v1/device.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/struct.proto"; @@ -24,7 +25,6 @@ option go_package = "google.golang.org/genproto/googleapis/home/graph/v1;graph"; option java_outer_classname = "HomeGraphApiServiceProto"; option java_package = "com.google.home.graph.v1"; - // Google HomeGraph API. HomeGraph Service provides the support for storing // and querying first-party and third-party devices, rooms and structures, // the relationships among them and their state in the home. It stores @@ -66,7 +66,21 @@ service HomeGraphApiService { // Unlink an agent user from Google. As result, all data related to this user // will be deleted. // - // Third-party user's identity is passed in as agent_user_id. + // Here is how the agent user is created in Google: + // When users open their Google Home App, they can begin linking a 3p + // partner. User is guided through the OAuth process. 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 the user's data, including + // agent_user_id and devices. + // Google then creates the agent user and stores a mapping from the + // agent_user_id -> Google ID mapping. Google also stores all user's devices + // under that Google ID. + // The mapping from agent_user_id -> 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. husband and wife share one Nest account + // username/password). + // + // Third-party user's identity is passed in as agent_user_id // 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. @@ -75,6 +89,26 @@ service HomeGraphApiService { delete: "/v1/{agent_user_id=agentUsers/**}" }; } + + // Gets the device states for the devices in QueryRequest. + // Third-party user's identity is passed in as agent_user_id. Agent is + // identified by the JWT signed by the third-party partner's service account. + rpc Query(QueryRequest) returns (QueryResponse) { + option (google.api.http) = { + post: "/v1/devices:query" + body: "*" + }; + } + + // Gets all the devices associated with the given third-party user. + // Third-party user's identity is passed in as agent_user_id. Agent is + // identified by the JWT signed by the third-party partner's service account. + rpc Sync(SyncRequest) returns (SyncResponse) { + option (google.api.http) = { + post: "/v1/devices:sync" + body: "*" + }; + } } // Request type for RequestSyncDevices call. @@ -193,3 +227,120 @@ message DeleteAgentUserRequest { // Required. Third-party user id. string agent_user_id = 2; } + +// Request type for Query call. This should be the same format as the AoG +// action.devices.QUERY request +// (https://developers.google.com/actions/smarthome/create-app#actiondevicesquery) +// with the exception of the extra "agent_user_id" and no "intent" and +// "customData" field. +message QueryRequest { + // Request ID used for debugging. + string request_id = 1; + + // Required. Third-party user ID. + string agent_user_id = 2; + + // Required. Inputs containing third-party partner's device IDs for which to + // get the device states. + repeated QueryRequestInput inputs = 3; +} + +// Device ID inputs to QueryRequest. +message QueryRequestInput { + // Payload containing third-party partner's device IDs. + QueryRequestPayload payload = 1; +} + +// Payload containing device IDs. +message QueryRequestPayload { + // Third-party partner's device IDs to get device states for. + repeated AgentDeviceId devices = 1; +} + +// Third-party partner's device ID for one device. +message AgentDeviceId { + // Third-party partner's device ID. + string id = 1; +} + +// Response type for Query call. This should follow the same format as AoG +// action.devices.QUERY response +// (https://developers.google.com/actions/smarthome/create-app#actiondevicesquery). +message QueryResponse { + // Request ID used for debugging. Copied from the request. + string request_id = 1; + + // Device states for the devices given in the request. + QueryResponsePayload payload = 2; +} + +// Payload containing device states information. +message QueryResponsePayload { + // States of the devices. Map of third-party device ID to struct of device + // states. + map devices = 1; +} + +// Request type for Sync call. This should follow the same format as AoG +// action.devices.SYNC request +// (https://developers.google.com/actions/smarthome/create-app#actiondevicessync) +// with the exception of the extra "agent_user_id" and no "intent" field. +message SyncRequest { + // Request ID used for debugging. + string request_id = 1; + + // Required. Third-party user ID. + string agent_user_id = 2; +} + +// Example SyncResponse: +// { +// "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", +// "payload": { +// "agentUserId": "1836.15267389", +// "devices": [{ +// "id": "123", +// "type": "action.devices.types.OUTLET", +// "traits": [ +// "action.devices.traits.OnOff" +// ], +// "name": { +// "defaultNames": ["My Outlet 1234"], +// "name": "Night light", +// "nicknames": ["wall plug"] +// }, +// "willReportState": false, +// "deviceInfo": { +// "manufacturer": "lights-out-inc", +// "model": "hs1234", +// "hwVersion": "3.2", +// "swVersion": "11.4" +// }, +// "customData": { +// "fooValue": 74, +// "barValue": true, +// "bazValue": "foo" +// } +// }] +// } +// } +// +// Response type for Sync call. This should follow the same format as AoG +// action.devices.SYNC response +// (https://developers.google.com/actions/smarthome/create-app#actiondevicessync). +message SyncResponse { + // Request ID used for debugging. Copied from the request. + string request_id = 1; + + // Devices associated with the third-party user. + SyncResponsePayload payload = 2; +} + +// Payload containing device information. +message SyncResponsePayload { + // Third-party user ID + string agent_user_id = 1; + + // Devices associated with the third-party user. + repeated google.home.graph.v1.Device devices = 2; +} diff --git a/google/home/graph/v1/homegraph_gapic.yaml b/google/home/graph/v1/homegraph_gapic.yaml index 906df5d4..73342472 100644 --- a/google/home/graph/v1/homegraph_gapic.yaml +++ b/google/home/graph/v1/homegraph_gapic.yaml @@ -156,3 +156,29 @@ interfaces: field_name_patterns: agent_user_id: agent_user_path timeout_millis: 10000 + - name: Query + flattening: + groups: + - parameters: + - request_id + - agent_user_id + - inputs + required_fields: + - agent_user_id + - inputs + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 10000 + - name: Sync + flattening: + groups: + - parameters: + - request_id + - agent_user_id + required_fields: + - agent_user_id + request_object_method: true + retry_codes_name: idempotent + retry_params_name: default + timeout_millis: 10000