blob: 4fd3c81f19296cfb2d63e3bff5e49832180693a3 [file] [log] [blame]
// 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.cloud.iot.v1;
import "google/api/annotations.proto";
import "google/cloud/iot/v1/resources.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.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";
// Add resources to imported types.
// See alternative, where this can be specified within the RPC method declaration.
// In that case, these options will not be needed.
option (google.api.resource_imported_reference) = {
type_name: "google.iam.v1.SetIamPolicyRequest",
// field_name: "resource", // Infered when there is only one string field in the message.
resource_reference: "iam" // Defined in resources.proto; but in the same namespace as this file
};
option (google.api.resource_imported_reference) = {
type_name: "google.iam.v1.GetIamPolicyRequest",
// field_name: "resource", // Infered when there is only one string field in the message.
resource_reference: "iam" // Defined in resources.proto; but in the same namespace as this file
};
option (google.api.resource_imported_reference) = {
type_name: "google.iam.v1.TestIamPermissionsRequest",
// field_name: "resource", // Infered when there is only one string field in the message.
resource_reference: "iam" // Defined in resources.proto; but in the same namespace as this file
};
// Internet of things (IoT) service. Allows to manipulate device registry
// instances and the registration of devices (Things) to the cloud.
service DeviceManager {
// 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"
};
}
// Gets a device registry configuration.
rpc GetDeviceRegistry(GetDeviceRegistryRequest) returns (DeviceRegistry) {
option (google.api.http) = {
get: "/v1/{name=projects/*/locations/*/registries/*}"
};
}
// 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"
};
}
// Deletes a device registry configuration.
rpc DeleteDeviceRegistry(DeleteDeviceRegistryRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/{name=projects/*/locations/*/registries/*}"
};
}
// Lists device registries.
rpc ListDeviceRegistries(ListDeviceRegistriesRequest) returns (ListDeviceRegistriesResponse) {
option (google.api.http) = {
get: "/v1/{parent=projects/*/locations/*}/registries"
};
}
// 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"
};
}
// 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/*}"
}
};
}
// 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"
}
};
}
// Deletes a device.
rpc DeleteDevice(DeleteDeviceRequest) returns (google.protobuf.Empty) {
option (google.api.http) = {
delete: "/v1/{name=projects/*/locations/*/registries/*/devices/*}"
additional_bindings {
delete: "/v1/{name=projects/*/locations/*/registries/*/groups/*/devices/*}"
}
};
}
// 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/*/groups/*}/devices"
}
};
}
// 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: "*"
}
};
}
// 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"
}
};
}
// 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"
}
};
}
// 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: "*"
}
};
// Alternatively the imported reference can be placed in the method declaration.
// The "resource_imported_request_reference" states it's for the request proto message.
// "field_name" is optional in the case then the request message only contains one
// string field. If it's omitted when there are multiple string fields then the
// generator will fail with an "ambiguous resource field" error.
option (google.api.resource_imported_request_reference).resource_reference = "iam";
}
// 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: "*"
}
};
// Alternatively the imported reference can be placed in the method declaration.
// The "resource_imported_request_reference" states it's for the request proto message.
// "field_name" is optional in the case then the request message only contains one
// string field. If it's omitted when there are multiple string fields then the
// generator will fail with an "ambiguous resource field" error.
option (google.api.resource_imported_request_reference).resource_reference = "iam";
}
// 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: "*"
}
};
// Alternatively the imported reference can be placed in the method declaration.
// The "resource_imported_request_reference" states it's for the request proto message.
// "field_name" is optional in the case then the request message only contains one
// string field. If it's omitted when there are multiple string fields then the
// generator will fail with an "ambiguous resource field" error.
option (google.api.resource_imported_request_reference).resource_reference = "iam";
}
}
// Request for `CreateDeviceRegistry`.
message CreateDeviceRegistryRequest {
// 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.resource_reference) = "location"];
// 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;
}
// Request for `GetDeviceRegistry`.
message GetDeviceRegistryRequest {
// The name of the device registry. For example,
// `projects/example-project/locations/us-central1/registries/my-registry`.
string name = 1 [(google.api.resource_reference) = "registry"];
}
// Request for `DeleteDeviceRegistry`.
message DeleteDeviceRegistryRequest {
// The name of the device registry. For example,
// `projects/example-project/locations/us-central1/registries/my-registry`.
string name = 1 [(google.api.resource_reference) = "registry"];
}
// Request for `UpdateDeviceRegistry`.
message UpdateDeviceRegistryRequest {
// 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.resource_reference) = "regisrty"];
// 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;
}
// Request for `ListDeviceRegistries`.
message ListDeviceRegistriesRequest {
// The project and cloud region path. For example,
// `projects/example-project/locations/us-central1`.
string parent = 1 [(google.api.resource_reference) = "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, but if there is a non-empty `page_token`, it
// indicates that more entries are available.
int32 page_size = 2;
// The value returned by the last `ListDeviceRegistriesResponse`; indicates
// that this is a continuation of a prior `ListDeviceRegistries` call, and
// that 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 {
// 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.resource_reference) = "registry"];
// The device registration details. The field `name` must be empty. The server
// will generate that field from the device registry `id` provided and the
// `parent` field.
Device device = 2;
}
// Request for `GetDevice`.
message GetDeviceRequest {
// 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.resource_reference) = "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.
google.protobuf.FieldMask field_mask = 2;
}
// Request for `UpdateDevice`.
message UpdateDeviceRequest {
// The new values for the device registry. 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;
// 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;
}
// Request for `DeleteDevice`.
message DeleteDeviceRequest {
// 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.resource_reference) = "device"];
}
// Request for `ListDevices`.
message ListDevicesRequest {
// The device registry path. Required. For example,
// `projects/my-project/locations/us-central1/registries/my-registry`.
string parent = 1 [(google.api.resource_reference) = "registry"];
// A list of device numerical ids. If empty, it will ignore this field. This
// field cannot hold more than 10,000 entries.
repeated uint64 device_num_ids = 2;
// A list of device string identifiers. If empty, it will ignore this field.
// For example, `['device0', 'device12']`. This field cannot hold more than
// 10,000 entries.
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 by default, along with any
// other fields specified.
google.protobuf.FieldMask field_mask = 4;
// 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, but if there is a non-empty `page_token`, it
// indicates that more entries are available.
int32 page_size = 100;
// The value returned by the last `ListDevicesResponse`; indicates
// that this is a continuation of a prior `ListDevices` call, and
// that the system should return the next page of data.
string page_token = 101;
}
// 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 {
// 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.resource_reference) = "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;
// The configuration data for the device.
bytes binary_data = 3;
}
// Request for `ListDeviceConfigVersions`.
message ListDeviceConfigVersionsRequest {
// 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.resource_reference) = "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 {
// 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.resource_reference) = "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;
}