suguo
/
googleapis
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: home/graph/v1 publish client library config annotations & comment updates 

This change includes adding the client library configuration annotations, updated proto comments, and some client library configuration files.

PiperOrigin-RevId: 302042647
This commit is contained in:
Google APIs 2020-03-20 09:30:42 -07:00 committed by Copybara-Service
parent c8c8c0bd15
commit cfabc98c6b
5 changed files with 233 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
google/home/graph/v1/BUILD.bazel
View File

@ -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",

2
google/home/graph/v1/device.proto
View File

@ -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.

280
google/home/graph/v1/homegraph.proto
View File

@ -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<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.
// 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;
}

44
google/home/graph/v1/homegraph_grpc_service_config.json Executable file
View File

@ -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"
]
}
}
]
}

12
google/home/graph/v1/homegraph_v1.yaml Normal file
View File

@ -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