diff --git a/google/home/graph/v1/BUILD.bazel b/google/home/graph/v1/BUILD.bazel index d5b7e97d..a9e0d0b0 100644 --- a/google/home/graph/v1/BUILD.bazel +++ b/google/home/graph/v1/BUILD.bazel @@ -17,6 +17,9 @@ proto_library( ], deps = [ "//google/api:annotations_proto", + "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", "@com_google_protobuf//:empty_proto", "@com_google_protobuf//:struct_proto", ], @@ -58,7 +61,7 @@ java_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", test_deps = [ ":graph_java_grpc", ], @@ -113,7 +116,7 @@ go_gapic_library( gapic_yaml = "homegraph_gapic.yaml", importpath = "google.golang.org/api/homegraph/v1", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [ ":graph_go_proto", ], @@ -154,6 +157,9 @@ moved_proto_library( srcs = [":graph_proto"], deps = [ "//google/api:annotations_proto", + "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", "@com_google_protobuf//:empty_proto", "@com_google_protobuf//:struct_proto", ], @@ -176,7 +182,7 @@ py_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [ ":graph_py_grpc", ":graph_py_proto", @@ -220,7 +226,7 @@ php_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [ ":graph_php_grpc", ":graph_php_proto", @@ -251,7 +257,7 @@ nodejs_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [], ) @@ -290,7 +296,7 @@ ruby_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [ ":graph_ruby_grpc", ":graph_ruby_proto", @@ -334,7 +340,7 @@ csharp_gapic_library( src = ":graph_proto_with_info", gapic_yaml = "homegraph_gapic.yaml", package = "google.home.graph.v1", - service_yaml = "//google/home/graph:base.yaml", + service_yaml = "homegraph_v1.yaml", deps = [ ":graph_csharp_grpc", ":graph_csharp_proto", diff --git a/google/home/graph/v1/device.proto b/google/home/graph/v1/device.proto index bf090525..d64f2694 100644 --- a/google/home/graph/v1/device.proto +++ b/google/home/graph/v1/device.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google Inc. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/google/home/graph/v1/homegraph.proto b/google/home/graph/v1/homegraph.proto index b8b277ad..982eb9dd 100644 --- a/google/home/graph/v1/homegraph.proto +++ b/google/home/graph/v1/homegraph.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google Inc. +// Copyright 2020 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,6 +17,9 @@ syntax = "proto3"; package google.home.graph.v1; import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; import "google/home/graph/v1/device.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/struct.proto"; @@ -24,114 +27,144 @@ import "google/protobuf/struct.proto"; 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"; +option (google.api.resource_definition) = { + type: "homegraph.googleapis.com/AgentUserPath" + pattern: "agentUsers/{agent_user_path=**}" +}; -// 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 -// entities and their relationships in the home. +// 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. service HomeGraphApiService { - // Requests a Sync call from Google to a 3p partner's home control agent for + 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. // // - // 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. Agent is identified by the API key or JWT - // signed by the partner's service account. - rpc RequestSyncDevices(RequestSyncDevicesRequest) - returns (RequestSyncDevicesResponse) { + // 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. + rpc RequestSyncDevices(RequestSyncDevicesRequest) returns (RequestSyncDevicesResponse) { option (google.api.http) = { post: "/v1/devices:requestSync" body: "*" }; + 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. - // This method updates a predefined set of States for a device, which all - // devices have (for example a light will have OnOff, Color, Brightness). - // A new State may not be created and an INVALID_ARGUMENT code will be thrown + // 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. + // created, which are associated to this state change. // - // 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. - rpc ReportStateAndNotification(ReportStateAndNotificationRequest) - returns (ReportStateAndNotificationResponse) { + // 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. + rpc ReportStateAndNotification(ReportStateAndNotificationRequest) returns (ReportStateAndNotificationResponse) { option (google.api.http) = { post: "/v1/devices:reportStateAndNotification" body: "*" }; + option (google.api.method_signature) = "request_id,event_id,agent_user_id,payload"; } - // Unlink an agent user from Google. As result, all data related to this user - // will be deleted. + // Unlinks an agent user from Google. As a result, all data related to this + // user will be deleted. // // 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 + // + // 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. husband and wife share one Nest account + // map to one `agent_user_id` (e.g., a 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. + // 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. + // Note: Special characters (except "/") in `agent_user_id` must be + // URL-encoded. rpc DeleteAgentUser(DeleteAgentUserRequest) returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{agent_user_id=agentUsers/**}" }; + option (google.api.method_signature) = "request_id,agent_user_id"; } - // 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. + // 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. rpc Query(QueryRequest) returns (QueryResponse) { option (google.api.http) = { post: "/v1/devices:query" body: "*" }; + option (google.api.method_signature) = "request_id,agent_user_id,inputs"; } // 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. + // 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. rpc Sync(SyncRequest) returns (SyncResponse) { option (google.api.http) = { post: "/v1/devices:sync" body: "*" }; + option (google.api.method_signature) = "request_id,agent_user_id"; } } -// Request type for RequestSyncDevices call. +// Request type for the +// [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices) +// call. message RequestSyncDevicesRequest { - // Required. Third-party user id issued by agent's third-party identity + // Required. Third-party user ID issued by agent's third-party identity // provider. - string agent_user_id = 1; + 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 // be returned immediately. The queue allows for de-duplication of // simultaneous requests. - bool async = 2; + bool async = 2 [(google.api.field_behavior) = OPTIONAL]; } -// Response type for RequestSyncDevices call. Intentionally empty upon success. -// An HTTP response code is returned with more details upon failure. -message RequestSyncDevicesResponse {} +// Response type for the +// [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices) +// call. Intentionally empty upon success. An HTTP response code is returned +// with more details upon failure. +message RequestSyncDevicesResponse { -// Sample ReportStateAndNotificationRequest, with states and notifications -// defined per device_id (eg: "123" and "456" in the following example): +} + +// 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 +// ```json // { // "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", // "agentUserId": "1234", @@ -146,51 +179,25 @@ message RequestSyncDevicesResponse {} // "brightness": 10 // } // }, -// "notifications": { -// "123": { -// "ObjectDetected": { -// "priority": 0, -// "objects": { -// "NAMED": ["Alice", "Bob", "Carol", "Eve"] -// } -// }, -// "DoorUnlocked": { -// "priority": 0, -// "keyUsed": { -// "keyName": "Wife's key" -// } -// } -// }, -// "456": { -// "SprinklersOn": { -// "priority": 0, -// "timeStarted": "1513792702" -// } -// } -// } // } // } // } -// Request type for 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. -// Next tag: 6. +// ``` message ReportStateAndNotificationRequest { - // Request id used for debugging. + // Request ID used for debugging. string request_id = 1; - // Unique identifier per event (eg: doorbell press). + // Unique identifier per event (for example, a doorbell press). string event_id = 4; - // Required. Third-party user id. - string agent_user_id = 2; + // Required. Third-party user ID. + string agent_user_id = 2 [(google.api.field_behavior) = REQUIRED]; // Token to maintain state in the follow up notification response. string follow_up_token = 5; - // 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 + // 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 @@ -199,22 +206,24 @@ message ReportStateAndNotificationRequest { // 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. - StateAndNotificationPayload payload = 3; + StateAndNotificationPayload payload = 3 [(google.api.field_behavior) = REQUIRED]; } -// Response type for ReportStateAndNotification call. +// Response type for the +// [`ReportStateAndNotification`](#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification) +// call. message ReportStateAndNotificationResponse { - // Request id copied from ReportStateAndNotificationRequest. + // Request ID copied from [ReportStateAndNotificationRequest][google.home.graph.v1.ReportStateAndNotificationRequest]. string request_id = 1; } -// Payload containing the State and Notification information for devices. +// Payload containing the state and notification information for devices. message StateAndNotificationPayload { - // The devices for updating State and sending Notifications. + // The devices for updating state and sending notifications. ReportStateAndNotificationDevice devices = 1; } -// The States and Notifications specific to a device. +// The states and notifications specific to a device. message ReportStateAndNotificationDevice { // States of devices to update. google.protobuf.Struct states = 1; @@ -223,33 +232,41 @@ message ReportStateAndNotificationDevice { google.protobuf.Struct notifications = 2; } -// Request type for DeleteAgentUser call. +// Request type for the +// [`DeleteAgentUser`](#google.home.graph.v1.HomeGraphApiService.DeleteAgentUser) +// call. message DeleteAgentUserRequest { - // Request id used for debugging. + // Request ID used for debugging. string request_id = 1; - // Required. Third-party user id. - string agent_user_id = 2; + // Required. Third-party user ID. + string agent_user_id = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "homegraph.googleapis.com/AgentUserPath" + } + ]; } -// 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. +// 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. message QueryRequest { // Request ID used for debugging. string request_id = 1; // Required. Third-party user ID. - string agent_user_id = 2; + string agent_user_id = 2 [(google.api.field_behavior) = REQUIRED]; // Required. Inputs containing third-party partner's device IDs for which to // get the device states. - repeated QueryRequestInput inputs = 3; + repeated QueryRequestInput inputs = 3 [(google.api.field_behavior) = REQUIRED]; } -// Device ID inputs to QueryRequest. +// Device ID inputs to [QueryRequest][google.home.graph.v1.QueryRequest]. message QueryRequestInput { // Payload containing third-party partner's device IDs. QueryRequestPayload payload = 1; @@ -257,7 +274,7 @@ message QueryRequestInput { // Payload containing device IDs. message QueryRequestPayload { - // Third-party partner's device IDs to get device states for. + // Third-party partner's device IDs for which to get the device states. repeated AgentDeviceId devices = 1; } @@ -267,9 +284,34 @@ message AgentDeviceId { 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). +// 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). +// # Example +// +// ```json +// { +// "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", +// "payload": { +// "devices": { +// "123": { +// "on": true, +// "online": true +// }, +// "456": { +// "on": true, +// "online": true, +// "brightness": 80, +// "color": { +// "name": "cerulean", +// "spectrumRGB": 31655 +// } +// } +// } +// } +// } +// ``` message QueryResponse { // Request ID used for debugging. Copied from the request. string request_id = 1; @@ -285,19 +327,26 @@ message QueryResponsePayload { 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. +// 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. message SyncRequest { // Request ID used for debugging. string request_id = 1; // Required. Third-party user ID. - string agent_user_id = 2; + string agent_user_id = 2 [(google.api.field_behavior) = REQUIRED]; } -// Example SyncResponse: +// 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). +// # Example +// +// ```json // { // "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", // "payload": { @@ -328,10 +377,7 @@ message SyncRequest { // }] // } // } -// -// 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; @@ -346,5 +392,5 @@ message SyncResponsePayload { string agent_user_id = 1; // Devices associated with the third-party user. - repeated google.home.graph.v1.Device devices = 2; + repeated Device devices = 2; } diff --git a/google/home/graph/v1/homegraph_grpc_service_config.json b/google/home/graph/v1/homegraph_grpc_service_config.json new file mode 100755 index 00000000..32b4eadb --- /dev/null +++ b/google/home/graph/v1/homegraph_grpc_service_config.json @@ -0,0 +1,44 @@ +{ + "methodConfig": [ + { + "name": [ + { + "service": "google.home.graph.v1.HomeGraphApiService", + "method": "RequestSyncDevices" + }, + { + "service": "google.home.graph.v1.HomeGraphApiService", + "method": "ReportStateAndNotification" + } + ], + "timeout": "10s" + }, + { + "name": [ + { + "service": "google.home.graph.v1.HomeGraphApiService", + "method": "DeleteAgentUser" + }, + { + "service": "google.home.graph.v1.HomeGraphApiService", + "method": "Query" + }, + { + "service": "google.home.graph.v1.HomeGraphApiService", + "method": "Sync" + } + ], + "timeout": "10s", + "retryPolicy": { + "maxAttempts": 5, + "initialBackoff": "0.100s", + "maxBackoff": "60s", + "backoffMultiplier": 1.3, + "retryableStatusCodes": [ + "UNAVAILABLE", + "DEADLINE_EXCEEDED" + ] + } + } + ] +} diff --git a/google/home/graph/v1/homegraph_v1.yaml b/google/home/graph/v1/homegraph_v1.yaml new file mode 100644 index 00000000..ae04cedc --- /dev/null +++ b/google/home/graph/v1/homegraph_v1.yaml @@ -0,0 +1,12 @@ +type: google.api.Service +config_version: 3 +name: homegraph.googleapis.com +title: HomeGraph API + +apis: +- name: google.home.graph.v1.HomeGraphApiService + +backend: + rules: + - selector: 'google.home.graph.v1.HomeGraphApiService.*' + deadline: 60.0