Enumerations

HttpState

static

number

Indicates whether DeviceService (HTTP) is enabled or disabled for the registry. See the field description for details.

Value

HTTP_STATE_UNSPECIFIED

No HTTP state specified. If not specified, DeviceService will be enabled by default.

HTTP_ENABLED

Enables DeviceService (HTTP) service for the registry.

HTTP_DISABLED

Disables DeviceService (HTTP) service for the registry.

MqttState

static

number

Indicates whether an MQTT connection is enabled or disabled. See the field description for details.

Value

MQTT_STATE_UNSPECIFIED

No MQTT state specified. If not specified, MQTT will be enabled by default.

MQTT_ENABLED

Enables a MQTT connection.

MQTT_DISABLED

Disables a MQTT connection.

PublicKeyCertificateFormat

static

number

The supported formats for the public key.

Value

UNSPECIFIED_PUBLIC_KEY_CERTIFICATE_FORMAT

The format has not been specified. This is an invalid default value and must not be used.

X509_CERTIFICATE_PEM

An X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

PublicKeyFormat

static

number

The supported formats for the public key.

Value

UNSPECIFIED_PUBLIC_KEY_FORMAT

The format has not been specified. This is an invalid default value and must not be used.

RSA_PEM

An RSA public key encoded in base64, and wrapped by -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----. This can be used to verify RS256 signatures in JWT tokens (RFC7518).

RSA_X509_PEM

As RSA_PEM, but wrapped in an X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

ES256_PEM

Public key for the ECDSA algorithm using P-256 and SHA-256, encoded in base64, and wrapped by -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----. This can be used to verify JWT tokens with the ES256 algorithm (RFC7518). This curve is defined in OpenSSL as the prime256v1 curve.

ES256_X509_PEM

As ES256_PEM, but wrapped in an X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Properties

HttpState

static

number

Indicates whether DeviceService (HTTP) is enabled or disabled for the registry. See the field description for details.

Value

HTTP_STATE_UNSPECIFIED

No HTTP state specified. If not specified, DeviceService will be enabled by default.

HTTP_ENABLED

Enables DeviceService (HTTP) service for the registry.

HTTP_DISABLED

Disables DeviceService (HTTP) service for the registry.

MqttState

static

number

Indicates whether an MQTT connection is enabled or disabled. See the field description for details.

Value

MQTT_STATE_UNSPECIFIED

No MQTT state specified. If not specified, MQTT will be enabled by default.

MQTT_ENABLED

Enables a MQTT connection.

MQTT_DISABLED

Disables a MQTT connection.

PublicKeyCertificateFormat

static

number

The supported formats for the public key.

Value

UNSPECIFIED_PUBLIC_KEY_CERTIFICATE_FORMAT

The format has not been specified. This is an invalid default value and must not be used.

X509_CERTIFICATE_PEM

An X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

PublicKeyFormat

static

number

The supported formats for the public key.

Value

UNSPECIFIED_PUBLIC_KEY_FORMAT

The format has not been specified. This is an invalid default value and must not be used.

RSA_PEM

An RSA public key encoded in base64, and wrapped by -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----. This can be used to verify RS256 signatures in JWT tokens (RFC7518).

RSA_X509_PEM

As RSA_PEM, but wrapped in an X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

ES256_PEM

Public key for the ECDSA algorithm using P-256 and SHA-256, encoded in base64, and wrapped by -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----. This can be used to verify JWT tokens with the ES256 algorithm (RFC7518). This curve is defined in OpenSSL as the prime256v1 curve.

ES256_X509_PEM

As ES256_PEM, but wrapped in an X.509v3 certificate (RFC5280), encoded in base64, and wrapped by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Abstract types

CreateDeviceRegistryRequest

static

Request for CreateDeviceRegistry.

Properties

Parameter

parent

string

The project and cloud region where this device registry must be created. For example, projects/example-project/locations/us-central1.

deviceRegistry

Object

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.

This object should have the same structure as DeviceRegistry

See also

google.cloud.iot.v1.CreateDeviceRegistryRequest definition in proto format

CreateDeviceRequest

static

Request for CreateDevice.

Properties

Parameter

parent

string

The name of the device registry where this device should be created. For example, projects/example-project/locations/us-central1/registries/my-registry.

device

Object

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.

This object should have the same structure as Device

See also

google.cloud.iot.v1.CreateDeviceRequest definition in proto format

DeleteDeviceRegistryRequest

static

Request for DeleteDeviceRegistry.

Property

Parameter

name

string

The name of the device registry. For example, projects/example-project/locations/us-central1/registries/my-registry.

See also

google.cloud.iot.v1.DeleteDeviceRegistryRequest definition in proto format

DeleteDeviceRequest

static

Request for DeleteDevice.

Property

Parameter

name

string

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

See also

google.cloud.iot.v1.DeleteDeviceRequest definition in proto format

Device

static

The device resource.

Properties

Parameter

id

string

The user-defined device identifier. The device ID must be unique within a device registry.

name

string

The resource path name. For example, projects/p1/locations/us-central1/registries/registry0/devices/dev0 or projects/p1/locations/us-central1/registries/registry0/devices/{num_id}. When name is populated as a response from the service, it always ends in the device numeric ID.

numId

number

[Output only] A server-defined unique numeric ID for the device. This is a more compact way to identify devices, and it is globally unique.

credentials

Array of Object

The credentials used to authenticate this device. To allow credential rotation without interruption, multiple device credentials can be bound to this device. No more than 3 credentials can be bound to a single device at a time. When new credentials are added to a device, they are verified against the registry credentials. For details, see the description of the DeviceRegistry.credentials field.

This object should have the same structure as DeviceCredential

lastHeartbeatTime

Object

[Output only] The last time an MQTT PINGREQ was received. This field applies only to devices connecting through MQTT. MQTT clients usually only send PINGREQ messages if the connection is idle, and no other messages have been sent. Timestamps are periodically collected and written to storage; they may be stale by a few minutes.

This object should have the same structure as Timestamp

lastEventTime

Object

[Output only] The last time a telemetry event was received. Timestamps are periodically collected and written to storage; they may be stale by a few minutes.

This object should have the same structure as Timestamp

lastStateTime

Object

[Output only] The last time a state event was received. Timestamps are periodically collected and written to storage; they may be stale by a few minutes.

This object should have the same structure as Timestamp

lastConfigAckTime

Object

[Output only] The last time a cloud-to-device config version acknowledgment was received from the device. This field is only for configurations sent through MQTT.

This object should have the same structure as Timestamp

lastConfigSendTime

Object

[Output only] The last time a cloud-to-device config version was sent to the device.

This object should have the same structure as Timestamp

blocked

boolean

If a device is blocked, connections or requests from this device will fail. Can be used to temporarily prevent the device from connecting if, for example, the sensor is generating bad data and needs maintenance.

lastErrorTime

Object

[Output only] The time the most recent error occurred, such as a failure to publish to Cloud Pub/Sub. This field is the timestamp of 'last_error_status'.

This object should have the same structure as Timestamp

lastErrorStatus

Object

[Output only] The error message of the most recent error, such as a failure to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this field. If no errors have occurred, this field has an empty message and the status code 0 == OK. Otherwise, this field is expected to have a status code other than OK.

This object should have the same structure as Status

config

Object

The most recent device configuration, which is eventually sent from Cloud IoT Core to the device. If not present on creation, the configuration will be initialized with an empty payload and version value of 1. To update this field after creation, use the DeviceManager.ModifyCloudToDeviceConfig method.

This object should have the same structure as DeviceConfig

state

Object

[Output only] The state most recently received from the device. If no state has been reported, this field is not present.

This object should have the same structure as DeviceState

metadata

Object with string properties

The metadata key-value pairs assigned to the device. This metadata is not interpreted or indexed by Cloud IoT Core. It can be used to add contextual information for the device.

Keys must conform to the regular expression [a-zA-Z][a-zA-Z0-9-_.+~%]+ and be less than 128 bytes in length.

Values are free-form strings. Each value must be less than or equal to 32 KB in size.

The total size of all keys and values must be less than 256 KB, and the maximum number of key-value pairs is 500.

See also

google.cloud.iot.v1.Device definition in proto format

DeviceConfig

static

The device configuration. Eventually delivered to devices.

Properties

Parameter

version

number

[Output only] The version of this update. The version number is assigned by the server, and is always greater than 0 after device creation. The version must be 0 on the CreateDevice request if a config is specified; the response of CreateDevice will always have a value of 1.

cloudUpdateTime

Object

[Output only] The time at which this configuration version was updated in Cloud IoT Core. This timestamp is set by the server.

This object should have the same structure as Timestamp

deviceAckTime

Object

[Output only] The time at which Cloud IoT Core received the acknowledgment from the device, indicating that the device has received this configuration version. If this field is not present, the device has not yet acknowledged that it received this version. Note that when the config was sent to the device, many config versions may have been available in Cloud IoT Core while the device was disconnected, and on connection, only the latest version is sent to the device. Some versions may never be sent to the device, and therefore are never acknowledged. This timestamp is set by Cloud IoT Core.

This object should have the same structure as Timestamp

binaryData

string

The device configuration data.

See also

google.cloud.iot.v1.DeviceConfig definition in proto format

DeviceCredential

static

A server-stored device credential used for authentication.

Properties

Parameter

publicKey

Object

A public key used to verify the signature of JSON Web Tokens (JWTs). When adding a new device credential, either via device creation or via modifications, this public key credential may be required to be signed by one of the registry level certificates. More specifically, if the registry contains at least one certificate, any new device credential must be signed by one of the registry certificates. As a result, when the registry contains certificates, only X.509 certificates are accepted as device credentials. However, if the registry does not contain a certificate, self-signed certificates and public keys will be accepted. New device credentials must be different from every registry-level certificate.

This object should have the same structure as PublicKeyCredential

expirationTime

Object

[Optional] The time at which this credential becomes invalid. This credential will be ignored for new client authentication requests after this timestamp; however, it will not be automatically deleted.

This object should have the same structure as Timestamp

See also

google.cloud.iot.v1.DeviceCredential definition in proto format

DeviceRegistry

static

A container for a group of devices.

Properties

Parameter

id

string

The identifier of this device registry. For example, myRegistry.

name

string

The resource path name. For example, projects/example-project/locations/us-central1/registries/my-registry.

eventNotificationConfigs

Array of Object

The configuration for notification of telemetry events received from the device. All telemetry events that were successfully published by the device and acknowledged by Cloud IoT Core are guaranteed to be delivered to Cloud Pub/Sub. If multiple configurations match a message, only the first matching configuration is used. If you try to publish a device telemetry event using MQTT without specifying a Cloud Pub/Sub topic for the device's registry, the connection closes automatically. If you try to do so using an HTTP connection, an error is returned. Up to 10 configurations may be provided.

This object should have the same structure as EventNotificationConfig

stateNotificationConfig

Object

The configuration for notification of new states received from the device. State updates are guaranteed to be stored in the state history, but notifications to Cloud Pub/Sub are not guaranteed. For example, if permissions are misconfigured or the specified topic doesn't exist, no notification will be published but the state will still be stored in Cloud IoT Core.

This object should have the same structure as StateNotificationConfig

mqttConfig

Object

The MQTT configuration for this device registry.

This object should have the same structure as MqttConfig

httpConfig

Object

The DeviceService (HTTP) configuration for this device registry.

This object should have the same structure as HttpConfig

credentials

Array of Object

The credentials used to verify the device credentials. No more than 10 credentials can be bound to a single registry at a time. The verification process occurs at the time of device creation or update. If this field is empty, no verification is performed. Otherwise, the credentials of a newly created device or added credentials of an updated device should be signed with one of these registry credentials.

Note, however, that existing devices will never be affected by modifications to this list of credentials: after a device has been successfully created in a registry, it should be able to connect even if its registry credentials are revoked, deleted, or modified.

This object should have the same structure as RegistryCredential

See also

google.cloud.iot.v1.DeviceRegistry definition in proto format

DeviceState

static

The device state, as reported by the device.

Properties

Parameter

updateTime

Object

[Output only] The time at which this state version was updated in Cloud IoT Core.

This object should have the same structure as Timestamp

binaryData

string

The device state data.

See also

google.cloud.iot.v1.DeviceState definition in proto format

EventNotificationConfig

static

The configuration for forwarding telemetry events.

Properties

Parameter

subfolderMatches

string

If the subfolder name matches this string exactly, this configuration will be used. The string must not include the leading '/' character. If empty, all strings are matched. This field is used only for telemetry events; subfolders are not supported for state changes.

pubsubTopicName

string

A Cloud Pub/Sub topic name. For example, projects/myProject/topics/deviceEvents.

See also

google.cloud.iot.v1.EventNotificationConfig definition in proto format

GetDeviceRegistryRequest

static

Request for GetDeviceRegistry.

Property

Parameter

name

string

The name of the device registry. For example, projects/example-project/locations/us-central1/registries/my-registry.

See also

google.cloud.iot.v1.GetDeviceRegistryRequest definition in proto format

GetDeviceRequest

static

Request for GetDevice.

Properties

Parameter

name

string

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

fieldMask

Object

The fields of the Device resource to be returned in the response. If the field mask is unset or empty, all fields are returned.

This object should have the same structure as FieldMask

See also

google.cloud.iot.v1.GetDeviceRequest definition in proto format

HttpConfig

static

The configuration of the HTTP bridge for a device registry.

Property

Parameter

httpEnabledState

number

If enabled, allows devices to use DeviceService via the HTTP protocol. Otherwise, any requests to DeviceService will fail for this registry.

The number should be among the values of HttpState

See also

google.cloud.iot.v1.HttpConfig definition in proto format

ListDeviceConfigVersionsRequest

static

Request for ListDeviceConfigVersions.

Properties

Parameter

name

string

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

numVersions

number

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.

See also

google.cloud.iot.v1.ListDeviceConfigVersionsRequest definition in proto format

ListDeviceConfigVersionsResponse

static

Response for ListDeviceConfigVersions.

Property

Parameter

deviceConfigs

Array of Object

The device configuration for the last few versions. Versions are listed in decreasing order, starting from the most recent one.

This object should have the same structure as DeviceConfig

See also

google.cloud.iot.v1.ListDeviceConfigVersionsResponse definition in proto format

ListDeviceRegistriesRequest

static

Request for ListDeviceRegistries.

Properties

Parameter

parent

string

The project and cloud region path. For example, projects/example-project/locations/us-central1.

pageSize

number

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.

pageToken

string

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.

See also

google.cloud.iot.v1.ListDeviceRegistriesRequest definition in proto format

ListDeviceRegistriesResponse

static

Response for ListDeviceRegistries.

Properties

Parameter

deviceRegistries

Array of Object

The registries that matched the query.

This object should have the same structure as DeviceRegistry

nextPageToken

string

If not empty, indicates that there may be more registries that match the request; this value should be passed in a new ListDeviceRegistriesRequest.

See also

google.cloud.iot.v1.ListDeviceRegistriesResponse definition in proto format

ListDevicesRequest

static

Request for ListDevices.

Properties

Parameter

parent

string

The device registry path. Required. For example, projects/my-project/locations/us-central1/registries/my-registry.

deviceNumIds

Array of number

A list of device numerical ids. If empty, it will ignore this field. This field cannot hold more than 10,000 entries.

deviceIds

Array of string

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.

fieldMask

Object

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.

This object should have the same structure as FieldMask

pageSize

number

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.

pageToken

string

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.

See also

google.cloud.iot.v1.ListDevicesRequest definition in proto format

ListDevicesResponse

static

Response for ListDevices.

Properties

Parameter

devices

Array of Object

The devices that match the request.

This object should have the same structure as Device

nextPageToken

string

If not empty, indicates that there may be more devices that match the request; this value should be passed in a new ListDevicesRequest.

See also

google.cloud.iot.v1.ListDevicesResponse definition in proto format

ListDeviceStatesRequest

static

Request for ListDeviceStates.

Properties

Parameter

name

string

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

numStates

number

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.

See also

google.cloud.iot.v1.ListDeviceStatesRequest definition in proto format

ListDeviceStatesResponse

static

Response for ListDeviceStates.

Property

Parameter

deviceStates

Array of Object

The last few device states. States are listed in descending order of server update time, starting from the most recent one.

This object should have the same structure as DeviceState

See also

google.cloud.iot.v1.ListDeviceStatesResponse definition in proto format

ModifyCloudToDeviceConfigRequest

static

Request for ModifyCloudToDeviceConfig.

Properties

Parameter

name

string

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

versionToUpdate

number

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.

binaryData

string

The configuration data for the device.

See also

google.cloud.iot.v1.ModifyCloudToDeviceConfigRequest definition in proto format

MqttConfig

static

The configuration of MQTT for a device registry.

Property

Parameter

mqttEnabledState

number

If enabled, allows connections using the MQTT protocol. Otherwise, MQTT connections to this registry will fail.

The number should be among the values of MqttState

See also

google.cloud.iot.v1.MqttConfig definition in proto format

PublicKeyCertificate

static

A public key certificate format and data.

Properties

Parameter

format

number

The certificate format.

The number should be among the values of PublicKeyCertificateFormat

certificate

string

The certificate data.

x509Details

Object

[Output only] The certificate details. Used only for X.509 certificates.

This object should have the same structure as X509CertificateDetails

See also

google.cloud.iot.v1.PublicKeyCertificate definition in proto format

PublicKeyCredential

static

A public key format and data.

Properties

Parameter

format

number

The format of the key.

The number should be among the values of PublicKeyFormat

key

string

The key data.

See also

google.cloud.iot.v1.PublicKeyCredential definition in proto format

RegistryCredential

static

A server-stored registry credential used to validate device credentials.

Property

Parameter

publicKeyCertificate

Object

A public key certificate used to verify the device credentials.

This object should have the same structure as PublicKeyCertificate

See also

google.cloud.iot.v1.RegistryCredential definition in proto format

StateNotificationConfig

static

The configuration for notification of new states received from the device.

Property

Parameter

pubsubTopicName

string

A Cloud Pub/Sub topic name. For example, projects/myProject/topics/deviceEvents.

See also

google.cloud.iot.v1.StateNotificationConfig definition in proto format

UpdateDeviceRegistryRequest

static

Request for UpdateDeviceRegistry.

Properties

Parameter

deviceRegistry

Object

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.

This object should have the same structure as DeviceRegistry

updateMask

Object

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.

This object should have the same structure as FieldMask

See also

google.cloud.iot.v1.UpdateDeviceRegistryRequest definition in proto format

UpdateDeviceRequest

static

Request for UpdateDevice.

Properties

Parameter

device

Object

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/device0or projects/p0/locations/us-central1/registries/registry0/devices/{num_id}.

This object should have the same structure as Device

updateMask

Object

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

This object should have the same structure as FieldMask

See also

google.cloud.iot.v1.UpdateDeviceRequest definition in proto format

X509CertificateDetails

static

Details of an X.509 certificate. For informational purposes only.

Properties

Parameter

issuer

string

The entity that signed the certificate.

subject

string

The entity the certificate and public key belong to.

startTime

Object

The time the certificate becomes valid.

This object should have the same structure as Timestamp

expiryTime

Object

The time the certificate becomes invalid.

This object should have the same structure as Timestamp

signatureAlgorithm

string

The algorithm used to sign the certificate.

publicKeyType

string

The type of public key in the certificate.

See also

google.cloud.iot.v1.X509CertificateDetails definition in proto format