// 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. // 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.cloud.iot.v1; import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/cloud/iot/v1/resources.proto"; import "google/iam/v1/iam_policy.proto"; import "google/iam/v1/policy.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/field_mask.proto"; option cc_enable_arenas = true; option go_package = "google.golang.org/genproto/googleapis/cloud/iot/v1;iot"; option java_multiple_files = true; option java_outer_classname = "DeviceManagerProto"; option java_package = "com.google.cloud.iot.v1"; // Internet of Things (IoT) service. Securely connect and manage IoT devices. service DeviceManager { option (google.api.default_host) = "cloudiot.googleapis.com"; option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform," "https://www.googleapis.com/auth/cloudiot"; // Creates a device registry that contains devices. rpc CreateDeviceRegistry(CreateDeviceRegistryRequest) returns (DeviceRegistry) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*}/registries" body: "device_registry" }; option (google.api.method_signature) = "parent,device_registry"; } // Gets a device registry configuration. rpc GetDeviceRegistry(GetDeviceRegistryRequest) returns (DeviceRegistry) { option (google.api.http) = { get: "/v1/{name=projects/*/locations/*/registries/*}" }; option (google.api.method_signature) = "name"; } // Updates a device registry configuration. rpc UpdateDeviceRegistry(UpdateDeviceRegistryRequest) returns (DeviceRegistry) { option (google.api.http) = { patch: "/v1/{device_registry.name=projects/*/locations/*/registries/*}" body: "device_registry" }; option (google.api.method_signature) = "device_registry,update_mask"; } // Deletes a device registry configuration. rpc DeleteDeviceRegistry(DeleteDeviceRegistryRequest) returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/locations/*/registries/*}" }; option (google.api.method_signature) = "name"; } // Lists device registries. rpc ListDeviceRegistries(ListDeviceRegistriesRequest) returns (ListDeviceRegistriesResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*}/registries" }; option (google.api.method_signature) = "parent"; } // Creates a device in a device registry. rpc CreateDevice(CreateDeviceRequest) returns (Device) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*/registries/*}/devices" body: "device" }; option (google.api.method_signature) = "parent,device"; } // Gets details about a device. rpc GetDevice(GetDeviceRequest) returns (Device) { option (google.api.http) = { get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}" additional_bindings { get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}" } }; option (google.api.method_signature) = "name"; } // Updates a device. rpc UpdateDevice(UpdateDeviceRequest) returns (Device) { option (google.api.http) = { patch: "/v1/{device.name=projects/*/locations/*/registries/*/devices/*}" body: "device" additional_bindings { patch: "/v1/{device.name=projects/*/locations/*/registries/*/groups/*/devices/*}" body: "device" } }; option (google.api.method_signature) = "device,update_mask"; } // Deletes a device. rpc DeleteDevice(DeleteDeviceRequest) returns (google.protobuf.Empty) { option (google.api.http) = { delete: "/v1/{name=projects/*/locations/*/registries/*/devices/*}" }; option (google.api.method_signature) = "name"; } // List devices in a device registry. rpc ListDevices(ListDevicesRequest) returns (ListDevicesResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/locations/*/registries/*}/devices" additional_bindings { get: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}/devices" } }; option (google.api.method_signature) = "parent"; } // Modifies the configuration for the device, which is eventually sent from // the Cloud IoT Core servers. Returns the modified configuration version and // its metadata. rpc ModifyCloudToDeviceConfig(ModifyCloudToDeviceConfigRequest) returns (DeviceConfig) { option (google.api.http) = { post: "/v1/{name=projects/*/locations/*/registries/*/devices/*}:modifyCloudToDeviceConfig" body: "*" additional_bindings { post: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}:modifyCloudToDeviceConfig" body: "*" } }; option (google.api.method_signature) = "name,binary_data"; } // Lists the last few versions of the device configuration in descending // order (i.e.: newest first). rpc ListDeviceConfigVersions(ListDeviceConfigVersionsRequest) returns (ListDeviceConfigVersionsResponse) { option (google.api.http) = { get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/configVersions" additional_bindings { get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/configVersions" } }; option (google.api.method_signature) = "name"; } // Lists the last few versions of the device state in descending order (i.e.: // newest first). rpc ListDeviceStates(ListDeviceStatesRequest) returns (ListDeviceStatesResponse) { option (google.api.http) = { get: "/v1/{name=projects/*/locations/*/registries/*/devices/*}/states" additional_bindings { get: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}/states" } }; option (google.api.method_signature) = "name"; } // Sets the access control policy on the specified resource. Replaces any // existing policy. rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/locations/*/registries/*}:setIamPolicy" body: "*" additional_bindings { post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:setIamPolicy" body: "*" } }; option (google.api.method_signature) = "resource,policy"; } // Gets the access control policy for a resource. // Returns an empty policy if the resource exists and does not have a policy // set. rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/locations/*/registries/*}:getIamPolicy" body: "*" additional_bindings { post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:getIamPolicy" body: "*" } }; option (google.api.method_signature) = "resource"; } // Returns permissions that a caller has on the specified resource. // If the resource does not exist, this will return an empty set of // permissions, not a NOT_FOUND error. rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/locations/*/registries/*}:testIamPermissions" body: "*" additional_bindings { post: "/v1/{resource=projects/*/locations/*/registries/*/groups/*}:testIamPermissions" body: "*" } }; option (google.api.method_signature) = "resource,permissions"; } // Sends a command to the specified device. In order for a device to be able // to receive commands, it must: // 1) be connected to Cloud IoT Core using the MQTT protocol, and // 2) be subscribed to the group of MQTT topics specified by // /devices/{device-id}/commands/#. This subscription will receive commands // at the top-level topic /devices/{device-id}/commands as well as commands // for subfolders, like /devices/{device-id}/commands/subfolder. // Note that subscribing to specific subfolders is not supported. // If the command could not be delivered to the device, this method will // return an error; in particular, if the device is not subscribed, this // method will return FAILED_PRECONDITION. Otherwise, this method will // return OK. If the subscription is QoS 1, at least once delivery will be // guaranteed; for QoS 0, no acknowledgment will be expected from the device. rpc SendCommandToDevice(SendCommandToDeviceRequest) returns (SendCommandToDeviceResponse) { option (google.api.http) = { post: "/v1/{name=projects/*/locations/*/registries/*/devices/*}:sendCommandToDevice" body: "*" additional_bindings { post: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}:sendCommandToDevice" body: "*" } }; option (google.api.method_signature) = "name,binary_data"; option (google.api.method_signature) = "name,binary_data,subfolder"; } // Associates the device with the gateway. rpc BindDeviceToGateway(BindDeviceToGatewayRequest) returns (BindDeviceToGatewayResponse) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*/registries/*}:bindDeviceToGateway" body: "*" additional_bindings { post: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}:bindDeviceToGateway" body: "*" } }; option (google.api.method_signature) = "parent,gateway_id,device_id"; } // Deletes the association between the device and the gateway. rpc UnbindDeviceFromGateway(UnbindDeviceFromGatewayRequest) returns (UnbindDeviceFromGatewayResponse) { option (google.api.http) = { post: "/v1/{parent=projects/*/locations/*/registries/*}:unbindDeviceFromGateway" body: "*" additional_bindings { post: "/v1/{parent=projects/*/locations/*/registries/*/groups/*}:unbindDeviceFromGateway" body: "*" } }; option (google.api.method_signature) = "parent,gateway_id,device_id"; } } // Request for `CreateDeviceRegistry`. message CreateDeviceRegistryRequest { // Required. The project and cloud region where this device registry must be created. // For example, `projects/example-project/locations/us-central1`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "locations.googleapis.com/Location" } ]; // Required. The device registry. The field `name` must be empty. The server will // generate that field from the device registry `id` provided and the // `parent` field. DeviceRegistry device_registry = 2 [(google.api.field_behavior) = REQUIRED]; } // Request for `GetDeviceRegistry`. message GetDeviceRegistryRequest { // Required. The name of the device registry. For example, // `projects/example-project/locations/us-central1/registries/my-registry`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; } // Request for `DeleteDeviceRegistry`. message DeleteDeviceRegistryRequest { // Required. The name of the device registry. For example, // `projects/example-project/locations/us-central1/registries/my-registry`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; } // Request for `UpdateDeviceRegistry`. message UpdateDeviceRegistryRequest { // Required. The new values for the device registry. The `id` field must be empty, and // the `name` field must indicate the path of the resource. For example, // `projects/example-project/locations/us-central1/registries/my-registry`. DeviceRegistry device_registry = 1 [(google.api.field_behavior) = REQUIRED]; // Required. Only updates the `device_registry` fields indicated by this mask. // The field mask must not be empty, and it must not contain fields that // are immutable or only set by the server. // Mutable top-level fields: `event_notification_config`, `http_config`, // `mqtt_config`, and `state_notification_config`. google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED]; } // Request for `ListDeviceRegistries`. message ListDeviceRegistriesRequest { // Required. The project and cloud region path. For example, // `projects/example-project/locations/us-central1`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "locations.googleapis.com/Location" } ]; // The maximum number of registries to return in the response. If this value // is zero, the service will select a default size. A call may return fewer // objects than requested. A non-empty `next_page_token` in the response // indicates that more data is available. int32 page_size = 2; // The value returned by the last `ListDeviceRegistriesResponse`; indicates // that this is a continuation of a prior `ListDeviceRegistries` call and // the system should return the next page of data. string page_token = 3; } // Response for `ListDeviceRegistries`. message ListDeviceRegistriesResponse { // The registries that matched the query. repeated DeviceRegistry device_registries = 1; // If not empty, indicates that there may be more registries that match the // request; this value should be passed in a new // `ListDeviceRegistriesRequest`. string next_page_token = 2; } // Request for `CreateDevice`. message CreateDeviceRequest { // Required. The name of the device registry where this device should be created. // For example, // `projects/example-project/locations/us-central1/registries/my-registry`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; // Required. The device registration details. The field `name` must be empty. The server // generates `name` from the device registry `id` and the // `parent` field. Device device = 2 [(google.api.field_behavior) = REQUIRED]; } // Request for `GetDevice`. message GetDeviceRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; // The fields of the `Device` resource to be returned in the response. If the // field mask is unset or empty, all fields are returned. Fields have to be // provided in snake_case format, for example: `last_heartbeat_time`. google.protobuf.FieldMask field_mask = 2; } // Request for `UpdateDevice`. message UpdateDeviceRequest { // Required. The new values for the device. The `id` and `num_id` fields must // be empty, and the field `name` must specify the name path. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0`or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. Device device = 2 [(google.api.field_behavior) = REQUIRED]; // Required. Only updates the `device` fields indicated by this mask. // The field mask must not be empty, and it must not contain fields that // are immutable or only set by the server. // Mutable top-level fields: `credentials`, `blocked`, and `metadata` google.protobuf.FieldMask update_mask = 3 [(google.api.field_behavior) = REQUIRED]; } // Request for `DeleteDevice`. message DeleteDeviceRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; } // Request for `ListDevices`. message ListDevicesRequest { // Required. The device registry path. Required. For example, // `projects/my-project/locations/us-central1/registries/my-registry`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; // A list of device numeric IDs. If empty, this field is ignored. Maximum // IDs: 10,000. repeated uint64 device_num_ids = 2; // A list of device string IDs. For example, `['device0', 'device12']`. // If empty, this field is ignored. Maximum IDs: 10,000 repeated string device_ids = 3; // The fields of the `Device` resource to be returned in the response. The // fields `id` and `num_id` are always returned, along with any // other fields specified in snake_case format, for example: // `last_heartbeat_time`. google.protobuf.FieldMask field_mask = 4; // Options related to gateways. GatewayListOptions gateway_list_options = 6; // The maximum number of devices to return in the response. If this value // is zero, the service will select a default size. A call may return fewer // objects than requested. A non-empty `next_page_token` in the response // indicates that more data is available. int32 page_size = 100; // The value returned by the last `ListDevicesResponse`; indicates // that this is a continuation of a prior `ListDevices` call and // the system should return the next page of data. string page_token = 101; } // Options for limiting the list based on gateway type and associations. message GatewayListOptions { // If not set, all devices and gateways are returned. If set, the list is // filtered based on gateway type and associations. oneof filter { // If `GATEWAY` is specified, only gateways are returned. If `NON_GATEWAY` // is specified, only non-gateway devices are returned. If // `GATEWAY_TYPE_UNSPECIFIED` is specified, all devices are returned. GatewayType gateway_type = 1; // If set, only devices associated with the specified gateway are returned. // The gateway ID can be numeric (`num_id`) or the user-defined string // (`id`). For example, if `123` is specified, only devices bound to the // gateway with `num_id` 123 are returned. string associations_gateway_id = 2; // If set, returns only the gateways with which the specified device is // associated. The device ID can be numeric (`num_id`) or the user-defined // string (`id`). For example, if `456` is specified, returns only the // gateways to which the device with `num_id` 456 is bound. string associations_device_id = 3; } } // Response for `ListDevices`. message ListDevicesResponse { // The devices that match the request. repeated Device devices = 1; // If not empty, indicates that there may be more devices that match the // request; this value should be passed in a new `ListDevicesRequest`. string next_page_token = 2; } // Request for `ModifyCloudToDeviceConfig`. message ModifyCloudToDeviceConfigRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; // The version number to update. If this value is zero, it will not check the // version number of the server and will always update the current version; // otherwise, this update will fail if the version number found on the server // does not match this version number. This is used to support multiple // simultaneous updates without losing data. int64 version_to_update = 2; // Required. The configuration data for the device. bytes binary_data = 3 [(google.api.field_behavior) = REQUIRED]; } // Request for `ListDeviceConfigVersions`. message ListDeviceConfigVersionsRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; // The number of versions to list. Versions are listed in decreasing order of // the version number. The maximum number of versions retained is 10. If this // value is zero, it will return all the versions available. int32 num_versions = 2; } // Response for `ListDeviceConfigVersions`. message ListDeviceConfigVersionsResponse { // The device configuration for the last few versions. Versions are listed // in decreasing order, starting from the most recent one. repeated DeviceConfig device_configs = 1; } // Request for `ListDeviceStates`. message ListDeviceStatesRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; // The number of states to list. States are listed in descending order of // update time. The maximum number of states retained is 10. If this // value is zero, it will return all the states available. int32 num_states = 2; } // Response for `ListDeviceStates`. message ListDeviceStatesResponse { // The last few device states. States are listed in descending order of server // update time, starting from the most recent one. repeated DeviceState device_states = 1; } // Request for `SendCommandToDevice`. message SendCommandToDeviceRequest { // Required. The name of the device. For example, // `projects/p0/locations/us-central1/registries/registry0/devices/device0` or // `projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Device" } ]; // Required. The command data to send to the device. bytes binary_data = 2 [(google.api.field_behavior) = REQUIRED]; // Optional subfolder for the command. If empty, the command will be delivered // to the /devices/{device-id}/commands topic, otherwise it will be delivered // to the /devices/{device-id}/commands/{subfolder} topic. Multi-level // subfolders are allowed. This field must not have more than 256 characters, // and must not contain any MQTT wildcards ("+" or "#") or null characters. string subfolder = 3; } // Response for `SendCommandToDevice`. message SendCommandToDeviceResponse { } // Request for `BindDeviceToGateway`. message BindDeviceToGatewayRequest { // Required. The name of the registry. For example, // `projects/example-project/locations/us-central1/registries/my-registry`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; // Required. The value of `gateway_id` can be either the device numeric ID or the // user-defined device identifier. string gateway_id = 2 [(google.api.field_behavior) = REQUIRED]; // Required. The device to associate with the specified gateway. The value of // `device_id` can be either the device numeric ID or the user-defined device // identifier. string device_id = 3 [(google.api.field_behavior) = REQUIRED]; } // Response for `BindDeviceToGateway`. message BindDeviceToGatewayResponse { } // Request for `UnbindDeviceFromGateway`. message UnbindDeviceFromGatewayRequest { // Required. The name of the registry. For example, // `projects/example-project/locations/us-central1/registries/my-registry`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: "cloudiot.googleapis.com/Registry" } ]; // Required. The value of `gateway_id` can be either the device numeric ID or the // user-defined device identifier. string gateway_id = 2 [(google.api.field_behavior) = REQUIRED]; // Required. The device to disassociate from the specified gateway. The value of // `device_id` can be either the device numeric ID or the user-defined device // identifier. string device_id = 3 [(google.api.field_behavior) = REQUIRED]; } // Response for `UnbindDeviceFromGateway`. message UnbindDeviceFromGatewayResponse { }