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

docs: Update documentation with links to smart home developer guides and reference pages. Remove outdated authorization instructions. 

PiperOrigin-RevId: 302892245
This commit is contained in:
Google APIs 2020-03-25 08:14:22 -07:00 committed by Copybara-Service
parent 551cf1e6e3
commit 0e07113e77
2 changed files with 116 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -22,31 +22,34 @@ 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.
// Third-party device definition.
message Device {
// Third-party partner's device ID.
// Third-party device ID.
string id = 1;
// Hardware type of the device (e.g. light, outlet, etc).
// Hardware type of the device.
// See [device
// types](https://developers.google.com/assistant/smarthome/guides).
string type = 2;
// Traits supported by the device.
// See [device
// traits](https://developers.google.com/assistant/smarthome/traits).
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.
// Names given to this device by your smart home Action.
DeviceNames name = 4;
// Indicates whether the state of this device is being reported to Google
// through ReportStateAndNotification call.
// Indicates whether your smart home Action will report state of this device
// to Google via [ReportStateAndNotification][].
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.
// Suggested name for the room where this device is installed.
// Google attempts to use this value during user setup.
string room_hint = 6;
// As in roomHint, for structures that users set up in the partner's system.
// Suggested name for the structure where this device is installed.
// Google attempts to use this value during user setup.
string structure_hint = 7;
// Device manufacturer, model, hardware version, and software version.
@ -55,31 +58,29 @@ message Device {
// 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.
// Custom device attributes stored in Home Graph and provided to your
// smart home Action in each
// [QUERY](https://developers.google.com/assistant/smarthome/reference/intent/query)
// and
// [EXECUTE](https://developers.google.com/assistant/smarthome/reference/intent/execute)
// intent.
google.protobuf.Struct custom_data = 10;
// IDs of other devices associated with this device. This is used to
// represent a device group (e.g. bonded zone) or "facets" synced
// through different flows (e.g. Google Nest Hub Max with a Nest Camera).
//
// This may also be used to pass in alternate IDs used to identify a cloud
// synced device for local execution (i.e. local verification). If used for
// local verification, this field is synced from the cloud.
// Alternate IDs associated with this device.
// This is used to identify cloud synced devices enabled for
// [local
// execution](https://developers.google.com/assistant/smarthome/concepts/local).
repeated AgentOtherDeviceId other_device_ids = 11;
// Indicates whether the device is capable of sending notifications. This
// field will be set by the agent (partner) on an incoming SYNC. If a device
// is not capable of generating notifications, the partner should set this
// flag to false. If a partner is not capable of calling
// ReportStateAndNotification to send notifications to Google, the partner
// should set this flag to false. If there is a user setting in the partner
// app to enable notifications and it is turned off, the partner should set
// this flag to false.
// Indicates whether your smart home Action will report notifications
// to Google for this device via [ReportStateAndNotification][].
//
// If your smart home Action enables users to control device notifications,
// you should update this field and call [RequestSyncDevices][].
bool notification_supported_by_agent = 12;
}
// Different names for the device.
// Identifiers used to describe the device.
message DeviceNames {
// Primary name of the device, generally provided by the user.
string name = 1;
@ -87,8 +88,8 @@ message DeviceNames {
// 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.
// List of names provided by the manufacturer rather than the user, such as
// serial numbers, SKUs, etc.
repeated string default_names = 3;
}
@ -107,11 +108,11 @@ message DeviceInfo {
string sw_version = 4;
}
// Identifies a device in the third party or first party system.
// Alternate third-party device ID.
message AgentOtherDeviceId {
// The agent's ID. Generally it is the agent's AoG project id.
// Project ID for your smart home Action.
string agent_id = 1;
// Device ID defined by the agent. The device_id must be unique.
// Unique third-party device ID.
string device_id = 2;
}

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

@ -32,21 +32,25 @@ option (google.api.resource_definition) = {
pattern: "agentUsers/{agent_user_path=**}"
};
// 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.
// Google Home Graph API service. The Home Graph service provides support for
// accessing first-party and third-party devices stored in Google's Home Graph.
// The Home Graph database provides contextual data about the relationships
// between devices and the home.
//
// For more details, see the [Home Graph developer
// guide](https://developers.google.com/assistant/smarthome/concepts/homegraph).
service HomeGraphApiService {
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.
// Requests Google to send an `action.devices.SYNC`
// [intent](https://developers.google.com/assistant/smarthome/reference/intent/sync)
// to your smart home Action to update device metadata for the given user.
//
//
// 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.
// The third-party user's identity is passed via the `agent_user_id`
// (see [RequestSyncDevicesRequest][google.home.graph.v1.RequestSyncDevicesRequest]).
// This request must be authorized using service account credentials from your
// Actions console project.
rpc RequestSyncDevices(RequestSyncDevicesRequest) returns (RequestSyncDevicesResponse) {
option (google.api.http) = {
post: "/v1/devices:requestSync"
@ -55,21 +59,22 @@ service HomeGraphApiService {
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. 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.
// Reports device state and optionally sends device notifications.
// Called by your smart home Action when the state of a third-party device
// changes or you need to send a notification about the device.
// See [Implement Report
// State](https://developers.google.com/assistant/smarthome/develop/report-state)
// for more information.
//
// 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.
// This method updates the device state according to its declared
// [traits](https://developers.google.com/assistant/smarthome/concepts/devices-traits).
// Publishing a new state value outside of these traits will result in an
// `INVALID_ARGUMENT` error response.
//
// The third-party user's identity is passed in via the `agent_user_id`
// (see [ReportStateAndNotificationRequest][google.home.graph.v1.ReportStateAndNotificationRequest]).
// This request must be authorized using service account credentials from your
// Actions console project.
rpc ReportStateAndNotification(ReportStateAndNotificationRequest) returns (ReportStateAndNotificationResponse) {
option (google.api.http) = {
post: "/v1/devices:reportStateAndNotification"
@ -78,31 +83,17 @@ service HomeGraphApiService {
option (google.api.method_signature) = "request_id,event_id,agent_user_id,payload";
}
// Unlinks an agent user from Google. As a result, all data related to this
// user will be deleted.
// Unlinks the given third-party user from your smart home Action.
// All data related to this user will be deleted.
//
// Here is how the agent user is created in Google:
// For more details on how users link their accounts, see
// [fulfillment and
// authentication](https://developers.google.com/assistant/smarthome/concepts/fulfillment-authentication).
//
// 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., a husband and wife share one Nest account
// username/password).
//
// 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.
// The third-party user's identity is passed in via the `agent_user_id`
// (see [DeleteAgentUserRequest][google.home.graph.v1.DeleteAgentUserRequest]).
// This request must be authorized using service account credentials from your
// Actions console project.
rpc DeleteAgentUser(DeleteAgentUserRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/{agent_user_id=agentUsers/**}"
@ -110,10 +101,13 @@ service HomeGraphApiService {
option (google.api.method_signature) = "request_id,agent_user_id";
}
// 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.
// Gets the current states in Home Graph for the given set of the third-party
// user's devices.
//
// The third-party user's identity is passed in via the `agent_user_id`
// (see [QueryRequest][google.home.graph.v1.QueryRequest]).
// This request must be authorized using service account credentials from your
// Actions console project.
rpc Query(QueryRequest) returns (QueryResponse) {
option (google.api.http) = {
post: "/v1/devices:query"
@ -123,9 +117,11 @@ service HomeGraphApiService {
}
// Gets all the devices associated with the given third-party user.
// 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.
//
// The third-party user's identity is passed in via the `agent_user_id`
// (see [SyncRequest][google.home.graph.v1.SyncRequest]).
// This request must be authorized using service account credentials from your
// Actions console project.
rpc Sync(SyncRequest) returns (SyncResponse) {
option (google.api.http) = {
post: "/v1/devices:sync"
@ -139,8 +135,7 @@ service HomeGraphApiService {
// [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices)
// call.
message RequestSyncDevicesRequest {
// Required. Third-party user ID issued by agent's third-party identity
// provider.
// Required. Third-party user ID.
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
@ -151,7 +146,9 @@ message RequestSyncDevicesRequest {
// Response type for the
// [`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices)
// call. Intentionally empty upon success. An HTTP response code is returned
// call.
//
// Intentionally empty upon success. An HTTP response code is returned
// with more details upon failure.
message RequestSyncDevicesResponse {
@ -159,11 +156,11 @@ message RequestSyncDevicesResponse {
// 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
// call. It may include states, notifications, or both. 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",
@ -196,16 +193,7 @@ message ReportStateAndNotificationRequest {
// Token to maintain state in the follow up notification response.
string follow_up_token = 5;
// 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
// 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.
// Required. State of devices to update and notification metadata for devices.
StateAndNotificationPayload payload = 3 [(google.api.field_behavior) = REQUIRED];
}
@ -225,10 +213,14 @@ message StateAndNotificationPayload {
// The states and notifications specific to a device.
message ReportStateAndNotificationDevice {
// States of devices to update.
// States of devices to update. See the **Device STATES** section
// of the individual trait [reference
// guides](https://developers.google.com/assistant/smarthome/traits).
google.protobuf.Struct states = 1;
// Notifications metadata for devices.
// Notifications metadata for devices. See the **Device NOTIFICATIONS**
// section of the individual trait [reference
// guides](https://developers.google.com/assistant/smarthome/traits).
google.protobuf.Struct notifications = 2;
}
@ -249,11 +241,7 @@ message DeleteAgentUserRequest {
}
// 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.
// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call.
message QueryRequest {
// Request ID used for debugging.
string request_id = 1;
@ -261,33 +249,34 @@ message QueryRequest {
// Required. Third-party user ID.
string agent_user_id = 2 [(google.api.field_behavior) = REQUIRED];
// Required. Inputs containing third-party partner's device IDs for which to
// Required. Inputs containing third-party device IDs for which to
// get the device states.
repeated QueryRequestInput inputs = 3 [(google.api.field_behavior) = REQUIRED];
}
// Device ID inputs to [QueryRequest][google.home.graph.v1.QueryRequest].
message QueryRequestInput {
// Payload containing third-party partner's device IDs.
// Payload containing third-party device IDs.
QueryRequestPayload payload = 1;
}
// Payload containing device IDs.
message QueryRequestPayload {
// Third-party partner's device IDs for which to get the device states.
// Third-party device IDs for which to get the device states.
repeated AgentDeviceId devices = 1;
}
// Third-party partner's device ID for one device.
// Third-party device ID for one device.
message AgentDeviceId {
// Third-party partner's device ID.
// Third-party device ID.
string id = 1;
}
// 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).
// [`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call.
// This should follow the same format as the Google smart home
// `action.devices.QUERY`
// [response](https://developers.google.com/assistant/smarthome/reference/intent/query).
// # Example
//
// ```json
@ -328,10 +317,7 @@ message QueryResponsePayload {
}
// 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.
// call.
message SyncRequest {
// Request ID used for debugging.
string request_id = 1;
@ -341,9 +327,10 @@ message SyncRequest {
}
// 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).
// [`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync) call.
// This should follow the same format as the Google smart home
// `action.devices.SYNC`
// [response](https://developers.google.com/assistant/smarthome/reference/intent/sync).
// # Example
//
// ```json