Synchronize new proto/yaml changes.

PiperOrigin-RevId: 201434004

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

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;
+}

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<string, google.protobuf.Struct> 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;
+}

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