You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
350 lines
12 KiB
350 lines
12 KiB
// 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/api/annotations.proto";
|
|
import "google/home/graph/v1/device.proto";
|
|
import "google/protobuf/empty.proto";
|
|
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";
|
|
|
|
// 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.
|
|
service HomeGraphApiService {
|
|
// 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) {
|
|
option (google.api.http) = {
|
|
post: "/v1/devices:requestSync"
|
|
body: "*"
|
|
};
|
|
}
|
|
|
|
// 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
|
|
// if so. It also optionally takes in a list of Notifications that may be
|
|
// 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) {
|
|
option (google.api.http) = {
|
|
post: "/v1/devices:reportStateAndNotification"
|
|
body: "*"
|
|
};
|
|
}
|
|
|
|
// Unlink an agent user from Google. As 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
|
|
// 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.
|
|
rpc DeleteAgentUser(DeleteAgentUserRequest) returns (google.protobuf.Empty) {
|
|
option (google.api.http) = {
|
|
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.
|
|
message RequestSyncDevicesRequest {
|
|
// Required. Third-party user id issued by agent's third-party identity
|
|
// provider.
|
|
string agent_user_id = 1;
|
|
|
|
// 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;
|
|
}
|
|
|
|
// Response type for 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):
|
|
// {
|
|
// "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
|
|
// "agentUserId": "1234",
|
|
// "payload": {
|
|
// "devices": {
|
|
// "states": {
|
|
// "123": {
|
|
// "on": true
|
|
// },
|
|
// "456": {
|
|
// "on": true,
|
|
// "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.
|
|
string request_id = 1;
|
|
|
|
// Unique identifier per event (eg: doorbell press).
|
|
string event_id = 4;
|
|
|
|
// Required. Third-party user id.
|
|
string agent_user_id = 2;
|
|
|
|
// 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
|
|
// 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.
|
|
StateAndNotificationPayload payload = 3;
|
|
}
|
|
|
|
// Response type for ReportStateAndNotification call.
|
|
message ReportStateAndNotificationResponse {
|
|
// Request id copied from ReportStateAndNotificationRequest.
|
|
string request_id = 1;
|
|
}
|
|
|
|
// Payload containing the State and Notification information for devices.
|
|
message StateAndNotificationPayload {
|
|
// The devices for updating State and sending Notifications.
|
|
ReportStateAndNotificationDevice devices = 1;
|
|
}
|
|
|
|
// The States and Notifications specific to a device.
|
|
message ReportStateAndNotificationDevice {
|
|
// States of devices to update.
|
|
google.protobuf.Struct states = 1;
|
|
|
|
// Notifications metadata for devices.
|
|
google.protobuf.Struct notifications = 2;
|
|
}
|
|
|
|
// Request type for DeleteAgentUser call.
|
|
message DeleteAgentUserRequest {
|
|
// Request id used for debugging.
|
|
string request_id = 1;
|
|
|
|
// 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;
|
|
}
|
|
|