Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / dd49464a6262c0d1f71efcf11f131e2f591fe5f6 / . / docs / dyn / cloudiot_v1.projects.locations.registries.devices.html
blob: 187d03b8b18602b8f08636b428398b1a920a75d0 [file] [log] [blame]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="cloudiot_v1.html">Cloud IoT API</a> . <a href="cloudiot_v1.projects.html">projects</a> . <a href="cloudiot_v1.projects.locations.html">locations</a> . <a href="cloudiot_v1.projects.locations.registries.html">registries</a> . <a href="cloudiot_v1.projects.locations.registries.devices.html">devices</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
78 <code><a href="cloudiot_v1.projects.locations.registries.devices.configVersions.html">configVersions()</a></code>
79</p>
80<p class="firstline">Returns the configVersions Resource.</p>
81
82<p class="toc_element">
83 <code><a href="cloudiot_v1.projects.locations.registries.devices.states.html">states()</a></code>
84</p>
85<p class="firstline">Returns the states Resource.</p>
86
87<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]88 <code><a href="#create">create(parent, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]89<p class="firstline">Creates a device in a device registry.</p>
90<p class="toc_element">
91 <code><a href="#delete">delete(name, x__xgafv=None)</a></code></p>
92<p class="firstline">Deletes a device.</p>
93<p class="toc_element">
94 <code><a href="#get">get(name, fieldMask=None, x__xgafv=None)</a></code></p>
95<p class="firstline">Gets details about a device.</p>
96<p class="toc_element">
97 <code><a href="#list">list(parent, pageSize=None, fieldMask=None, deviceNumIds=None, x__xgafv=None, deviceIds=None, pageToken=None, gatewayListOptions_associationsGatewayId=None, gatewayListOptions_associationsDeviceId=None, gatewayListOptions_gatewayType=None)</a></code></p>
98<p class="firstline">List devices in a device registry.</p>
99<p class="toc_element">
100 <code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
101<p class="firstline">Retrieves the next page of results.</p>
102<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]103 <code><a href="#modifyCloudToDeviceConfig">modifyCloudToDeviceConfig(name, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]104<p class="firstline">Modifies the configuration for the device, which is eventually sent from</p>
105<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]106 <code><a href="#patch">patch(name, body=None, updateMask=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]107<p class="firstline">Updates a device.</p>
108<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]109 <code><a href="#sendCommandToDevice">sendCommandToDevice(name, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]110<p class="firstline">Sends a command to the specified device. In order for a device to be able</p>
111<h3>Method Details</h3>
112<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]113 <code class="details" id="create">create(parent, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]114 <pre>Creates a device in a device registry.
115
116Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]117 parent: string, Required. The name of the device registry where this device should be created.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]118For example,
119`projects/example-project/locations/us-central1/registries/my-registry`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]120 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]121 The object takes the form of:
122
123{ # The device resource.
124 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
125 # periodically collected and written to storage; they may be stale by a few
126 # minutes.
127 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
128 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
129 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]130 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]131 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
132 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]133 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]134 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]135 "name": "A String", # The resource path name. For example,
136 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
137 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
138 # When `name` is populated as a response from the service, it always ends
139 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]140 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
141 # periodically collected and written to storage; they may be stale by a few
142 # minutes.
143 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
144 # publish to Cloud Pub/Sub. This field is the timestamp of
145 # 'last_error_status'.
146 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
147 # more compact way to identify devices, and it is globally unique.
148 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
149 # applies only to devices connecting through MQTT. MQTT clients usually only
150 # send `PINGREQ` messages if the connection is idle, and no other messages
151 # have been sent. Timestamps are periodically collected and written to
152 # storage; they may be stale by a few minutes.
153 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
154 # was received from the device. This field is only for configurations
155 # sent through MQTT.
156 "logLevel": "A String", # **Beta Feature**
157 #
158 # The logging verbosity for device activity. If unspecified,
159 # DeviceRegistry.log_level will be used.
160 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
161 # has been reported, this field is not present.
162 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
163 # IoT Core.
164 "binaryData": "A String", # The device state data.
165 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]166 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
167 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]168 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
169 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
170 # field. If no errors have occurred, this field has an empty message
171 # and the status code 0 == OK. Otherwise, this field is expected to have a
172 # status code other than OK.
173 # different programming environments, including REST APIs and RPC APIs. It is
174 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
175 # three pieces of data: error code, error message, and error details.
176 #
177 # You can find out more about this error model and how to work with it in the
178 # [API Design Guide](https://cloud.google.com/apis/design/errors).
179 "message": "A String", # A developer-facing error message, which should be in English. Any
180 # user-facing error message should be localized and sent in the
181 # google.rpc.Status.details field, or localized by the client.
182 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
183 "details": [ # A list of messages that carry the error details. There is a common set of
184 # message types for APIs to use.
185 {
186 "a_key": "", # Properties of the object. Contains field @type with type URL.
187 },
188 ],
189 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]190 "credentials": [ # The credentials used to authenticate this device. To allow credential
191 # rotation without interruption, multiple device credentials can be bound to
192 # this device. No more than 3 credentials can be bound to a single device at
193 # a time. When new credentials are added to a device, they are verified
194 # against the registry credentials. For details, see the description of the
195 # `DeviceRegistry.credentials` field.
196 { # A server-stored device credential used for authentication.
197 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
198 # When adding a new device credential, either via device creation or via
199 # modifications, this public key credential may be required to be signed by
200 # one of the registry level certificates. More specifically, if the
201 # registry contains at least one certificate, any new device credential
202 # must be signed by one of the registry certificates. As a result,
203 # when the registry contains certificates, only X.509 certificates are
204 # accepted as device credentials. However, if the registry does
205 # not contain a certificate, self-signed certificates and public keys will
206 # be accepted. New device credentials must be different from every
207 # registry-level certificate.
208 "key": "A String", # The key data.
209 "format": "A String", # The format of the key.
210 },
211 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
212 # credential will be ignored for new client authentication requests after
213 # this timestamp; however, it will not be automatically deleted.
214 },
215 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]216 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
217 # Can be used to temporarily prevent the device from connecting if, for
218 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]219 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
220 # Cloud IoT Core to the device. If not present on creation, the
221 # configuration will be initialized with an empty payload and version value
222 # of `1`. To update this field after creation, use the
223 # `DeviceManager.ModifyCloudToDeviceConfig` method.
224 "version": "A String", # [Output only] The version of this update. The version number is assigned by
225 # the server, and is always greater than 0 after device creation. The
226 # version must be 0 on the `CreateDevice` request if a `config` is
227 # specified; the response of `CreateDevice` will always have a value of 1.
228 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
229 # Cloud IoT Core. This timestamp is set by the server.
230 "binaryData": "A String", # The device configuration data.
231 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
232 # acknowledgment from the device, indicating that the device has received
233 # this configuration version. If this field is not present, the device has
234 # not yet acknowledged that it received this version. Note that when
235 # the config was sent to the device, many config versions may have been
236 # available in Cloud IoT Core while the device was disconnected, and on
237 # connection, only the latest version is sent to the device. Some
238 # versions may never be sent to the device, and therefore are never
239 # acknowledged. This timestamp is set by Cloud IoT Core.
240 },
241 "id": "A String", # The user-defined device identifier. The device ID must be unique
242 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]243 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
244 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
245 # information for the device.
246 #
247 # Keys must conform to the regular expression a-zA-Z+ and
248 # be less than 128 bytes in length.
249 #
250 # Values are free-form strings. Each value must be less than or equal to 32
251 # KB in size.
252 #
253 # The total size of all keys and values must be less than 256 KB, and the
254 # maximum number of key-value pairs is 500.
255 "a_key": "A String",
256 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]257}
258
259 x__xgafv: string, V1 error format.
260 Allowed values
261 1 - v1 error format
262 2 - v2 error format
263
264Returns:
265 An object of the form:
266
267 { # The device resource.
268 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
269 # periodically collected and written to storage; they may be stale by a few
270 # minutes.
271 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
272 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
273 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]274 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]275 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
276 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]277 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]278 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]279 "name": "A String", # The resource path name. For example,
280 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
281 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
282 # When `name` is populated as a response from the service, it always ends
283 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]284 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
285 # periodically collected and written to storage; they may be stale by a few
286 # minutes.
287 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
288 # publish to Cloud Pub/Sub. This field is the timestamp of
289 # 'last_error_status'.
290 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
291 # more compact way to identify devices, and it is globally unique.
292 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
293 # applies only to devices connecting through MQTT. MQTT clients usually only
294 # send `PINGREQ` messages if the connection is idle, and no other messages
295 # have been sent. Timestamps are periodically collected and written to
296 # storage; they may be stale by a few minutes.
297 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
298 # was received from the device. This field is only for configurations
299 # sent through MQTT.
300 "logLevel": "A String", # **Beta Feature**
301 #
302 # The logging verbosity for device activity. If unspecified,
303 # DeviceRegistry.log_level will be used.
304 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
305 # has been reported, this field is not present.
306 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
307 # IoT Core.
308 "binaryData": "A String", # The device state data.
309 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]310 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
311 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]312 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
313 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
314 # field. If no errors have occurred, this field has an empty message
315 # and the status code 0 == OK. Otherwise, this field is expected to have a
316 # status code other than OK.
317 # different programming environments, including REST APIs and RPC APIs. It is
318 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
319 # three pieces of data: error code, error message, and error details.
320 #
321 # You can find out more about this error model and how to work with it in the
322 # [API Design Guide](https://cloud.google.com/apis/design/errors).
323 "message": "A String", # A developer-facing error message, which should be in English. Any
324 # user-facing error message should be localized and sent in the
325 # google.rpc.Status.details field, or localized by the client.
326 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
327 "details": [ # A list of messages that carry the error details. There is a common set of
328 # message types for APIs to use.
329 {
330 "a_key": "", # Properties of the object. Contains field @type with type URL.
331 },
332 ],
333 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]334 "credentials": [ # The credentials used to authenticate this device. To allow credential
335 # rotation without interruption, multiple device credentials can be bound to
336 # this device. No more than 3 credentials can be bound to a single device at
337 # a time. When new credentials are added to a device, they are verified
338 # against the registry credentials. For details, see the description of the
339 # `DeviceRegistry.credentials` field.
340 { # A server-stored device credential used for authentication.
341 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
342 # When adding a new device credential, either via device creation or via
343 # modifications, this public key credential may be required to be signed by
344 # one of the registry level certificates. More specifically, if the
345 # registry contains at least one certificate, any new device credential
346 # must be signed by one of the registry certificates. As a result,
347 # when the registry contains certificates, only X.509 certificates are
348 # accepted as device credentials. However, if the registry does
349 # not contain a certificate, self-signed certificates and public keys will
350 # be accepted. New device credentials must be different from every
351 # registry-level certificate.
352 "key": "A String", # The key data.
353 "format": "A String", # The format of the key.
354 },
355 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
356 # credential will be ignored for new client authentication requests after
357 # this timestamp; however, it will not be automatically deleted.
358 },
359 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]360 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
361 # Can be used to temporarily prevent the device from connecting if, for
362 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]363 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
364 # Cloud IoT Core to the device. If not present on creation, the
365 # configuration will be initialized with an empty payload and version value
366 # of `1`. To update this field after creation, use the
367 # `DeviceManager.ModifyCloudToDeviceConfig` method.
368 "version": "A String", # [Output only] The version of this update. The version number is assigned by
369 # the server, and is always greater than 0 after device creation. The
370 # version must be 0 on the `CreateDevice` request if a `config` is
371 # specified; the response of `CreateDevice` will always have a value of 1.
372 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
373 # Cloud IoT Core. This timestamp is set by the server.
374 "binaryData": "A String", # The device configuration data.
375 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
376 # acknowledgment from the device, indicating that the device has received
377 # this configuration version. If this field is not present, the device has
378 # not yet acknowledged that it received this version. Note that when
379 # the config was sent to the device, many config versions may have been
380 # available in Cloud IoT Core while the device was disconnected, and on
381 # connection, only the latest version is sent to the device. Some
382 # versions may never be sent to the device, and therefore are never
383 # acknowledged. This timestamp is set by Cloud IoT Core.
384 },
385 "id": "A String", # The user-defined device identifier. The device ID must be unique
386 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]387 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
388 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
389 # information for the device.
390 #
391 # Keys must conform to the regular expression a-zA-Z+ and
392 # be less than 128 bytes in length.
393 #
394 # Values are free-form strings. Each value must be less than or equal to 32
395 # KB in size.
396 #
397 # The total size of all keys and values must be less than 256 KB, and the
398 # maximum number of key-value pairs is 500.
399 "a_key": "A String",
400 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]401 }</pre>
402</div>
403
404<div class="method">
405 <code class="details" id="delete">delete(name, x__xgafv=None)</code>
406 <pre>Deletes a device.
407
408Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]409 name: string, Required. The name of the device. For example,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]410`projects/p0/locations/us-central1/registries/registry0/devices/device0` or
411`projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. (required)
412 x__xgafv: string, V1 error format.
413 Allowed values
414 1 - v1 error format
415 2 - v2 error format
416
417Returns:
418 An object of the form:
419
420 { # A generic empty message that you can re-use to avoid defining duplicated
421 # empty messages in your APIs. A typical example is to use it as the request
422 # or the response type of an API method. For instance:
423 #
424 # service Foo {
425 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
426 # }
427 #
428 # The JSON representation for `Empty` is empty JSON object `{}`.
429 }</pre>
430</div>
431
432<div class="method">
433 <code class="details" id="get">get(name, fieldMask=None, x__xgafv=None)</code>
434 <pre>Gets details about a device.
435
436Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]437 name: string, Required. The name of the device. For example,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]438`projects/p0/locations/us-central1/registries/registry0/devices/device0` or
439`projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. (required)
440 fieldMask: string, The fields of the `Device` resource to be returned in the response. If the
441field mask is unset or empty, all fields are returned.
442 x__xgafv: string, V1 error format.
443 Allowed values
444 1 - v1 error format
445 2 - v2 error format
446
447Returns:
448 An object of the form:
449
450 { # The device resource.
451 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
452 # periodically collected and written to storage; they may be stale by a few
453 # minutes.
454 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
455 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
456 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]457 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]458 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
459 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]460 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]461 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]462 "name": "A String", # The resource path name. For example,
463 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
464 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
465 # When `name` is populated as a response from the service, it always ends
466 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]467 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
468 # periodically collected and written to storage; they may be stale by a few
469 # minutes.
470 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
471 # publish to Cloud Pub/Sub. This field is the timestamp of
472 # 'last_error_status'.
473 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
474 # more compact way to identify devices, and it is globally unique.
475 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
476 # applies only to devices connecting through MQTT. MQTT clients usually only
477 # send `PINGREQ` messages if the connection is idle, and no other messages
478 # have been sent. Timestamps are periodically collected and written to
479 # storage; they may be stale by a few minutes.
480 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
481 # was received from the device. This field is only for configurations
482 # sent through MQTT.
483 "logLevel": "A String", # **Beta Feature**
484 #
485 # The logging verbosity for device activity. If unspecified,
486 # DeviceRegistry.log_level will be used.
487 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
488 # has been reported, this field is not present.
489 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
490 # IoT Core.
491 "binaryData": "A String", # The device state data.
492 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]493 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
494 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]495 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
496 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
497 # field. If no errors have occurred, this field has an empty message
498 # and the status code 0 == OK. Otherwise, this field is expected to have a
499 # status code other than OK.
500 # different programming environments, including REST APIs and RPC APIs. It is
501 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
502 # three pieces of data: error code, error message, and error details.
503 #
504 # You can find out more about this error model and how to work with it in the
505 # [API Design Guide](https://cloud.google.com/apis/design/errors).
506 "message": "A String", # A developer-facing error message, which should be in English. Any
507 # user-facing error message should be localized and sent in the
508 # google.rpc.Status.details field, or localized by the client.
509 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
510 "details": [ # A list of messages that carry the error details. There is a common set of
511 # message types for APIs to use.
512 {
513 "a_key": "", # Properties of the object. Contains field @type with type URL.
514 },
515 ],
516 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]517 "credentials": [ # The credentials used to authenticate this device. To allow credential
518 # rotation without interruption, multiple device credentials can be bound to
519 # this device. No more than 3 credentials can be bound to a single device at
520 # a time. When new credentials are added to a device, they are verified
521 # against the registry credentials. For details, see the description of the
522 # `DeviceRegistry.credentials` field.
523 { # A server-stored device credential used for authentication.
524 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
525 # When adding a new device credential, either via device creation or via
526 # modifications, this public key credential may be required to be signed by
527 # one of the registry level certificates. More specifically, if the
528 # registry contains at least one certificate, any new device credential
529 # must be signed by one of the registry certificates. As a result,
530 # when the registry contains certificates, only X.509 certificates are
531 # accepted as device credentials. However, if the registry does
532 # not contain a certificate, self-signed certificates and public keys will
533 # be accepted. New device credentials must be different from every
534 # registry-level certificate.
535 "key": "A String", # The key data.
536 "format": "A String", # The format of the key.
537 },
538 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
539 # credential will be ignored for new client authentication requests after
540 # this timestamp; however, it will not be automatically deleted.
541 },
542 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]543 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
544 # Can be used to temporarily prevent the device from connecting if, for
545 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]546 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
547 # Cloud IoT Core to the device. If not present on creation, the
548 # configuration will be initialized with an empty payload and version value
549 # of `1`. To update this field after creation, use the
550 # `DeviceManager.ModifyCloudToDeviceConfig` method.
551 "version": "A String", # [Output only] The version of this update. The version number is assigned by
552 # the server, and is always greater than 0 after device creation. The
553 # version must be 0 on the `CreateDevice` request if a `config` is
554 # specified; the response of `CreateDevice` will always have a value of 1.
555 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
556 # Cloud IoT Core. This timestamp is set by the server.
557 "binaryData": "A String", # The device configuration data.
558 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
559 # acknowledgment from the device, indicating that the device has received
560 # this configuration version. If this field is not present, the device has
561 # not yet acknowledged that it received this version. Note that when
562 # the config was sent to the device, many config versions may have been
563 # available in Cloud IoT Core while the device was disconnected, and on
564 # connection, only the latest version is sent to the device. Some
565 # versions may never be sent to the device, and therefore are never
566 # acknowledged. This timestamp is set by Cloud IoT Core.
567 },
568 "id": "A String", # The user-defined device identifier. The device ID must be unique
569 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]570 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
571 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
572 # information for the device.
573 #
574 # Keys must conform to the regular expression a-zA-Z+ and
575 # be less than 128 bytes in length.
576 #
577 # Values are free-form strings. Each value must be less than or equal to 32
578 # KB in size.
579 #
580 # The total size of all keys and values must be less than 256 KB, and the
581 # maximum number of key-value pairs is 500.
582 "a_key": "A String",
583 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]584 }</pre>
585</div>
586
587<div class="method">
588 <code class="details" id="list">list(parent, pageSize=None, fieldMask=None, deviceNumIds=None, x__xgafv=None, deviceIds=None, pageToken=None, gatewayListOptions_associationsGatewayId=None, gatewayListOptions_associationsDeviceId=None, gatewayListOptions_gatewayType=None)</code>
589 <pre>List devices in a device registry.
590
591Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]592 parent: string, Required. The device registry path. Required. For example,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]593`projects/my-project/locations/us-central1/registries/my-registry`. (required)
594 pageSize: integer, The maximum number of devices to return in the response. If this value
595is zero, the service will select a default size. A call may return fewer
596objects than requested. A non-empty `next_page_token` in the response
597indicates that more data is available.
598 fieldMask: string, The fields of the `Device` resource to be returned in the response. The
599fields `id` and `num_id` are always returned, along with any
600other fields specified.
601 deviceNumIds: string, A list of device numeric IDs. If empty, this field is ignored. Maximum
602IDs: 10,000. (repeated)
603 x__xgafv: string, V1 error format.
604 Allowed values
605 1 - v1 error format
606 2 - v2 error format
607 deviceIds: string, A list of device string IDs. For example, `['device0', 'device12']`.
608If empty, this field is ignored. Maximum IDs: 10,000 (repeated)
609 pageToken: string, The value returned by the last `ListDevicesResponse`; indicates
610that this is a continuation of a prior `ListDevices` call and
611the system should return the next page of data.
612 gatewayListOptions_associationsGatewayId: string, If set, only devices associated with the specified gateway are returned.
613The gateway ID can be numeric (`num_id`) or the user-defined string
614(`id`). For example, if `123` is specified, only devices bound to the
615gateway with `num_id` 123 are returned.
616 gatewayListOptions_associationsDeviceId: string, If set, returns only the gateways with which the specified device is
617associated. The device ID can be numeric (`num_id`) or the user-defined
618string (`id`). For example, if `456` is specified, returns only the
619gateways to which the device with `num_id` 456 is bound.
620 gatewayListOptions_gatewayType: string, If `GATEWAY` is specified, only gateways are returned. If `NON_GATEWAY`
621is specified, only non-gateway devices are returned. If
622`GATEWAY_TYPE_UNSPECIFIED` is specified, all devices are returned.
623
624Returns:
625 An object of the form:
626
627 { # Response for `ListDevices`.
628 "nextPageToken": "A String", # If not empty, indicates that there may be more devices that match the
629 # request; this value should be passed in a new `ListDevicesRequest`.
630 "devices": [ # The devices that match the request.
631 { # The device resource.
632 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
633 # periodically collected and written to storage; they may be stale by a few
634 # minutes.
635 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
636 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
637 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]638 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]639 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
640 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]641 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]642 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]643 "name": "A String", # The resource path name. For example,
644 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
645 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
646 # When `name` is populated as a response from the service, it always ends
647 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]648 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
649 # periodically collected and written to storage; they may be stale by a few
650 # minutes.
651 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
652 # publish to Cloud Pub/Sub. This field is the timestamp of
653 # 'last_error_status'.
654 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
655 # more compact way to identify devices, and it is globally unique.
656 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
657 # applies only to devices connecting through MQTT. MQTT clients usually only
658 # send `PINGREQ` messages if the connection is idle, and no other messages
659 # have been sent. Timestamps are periodically collected and written to
660 # storage; they may be stale by a few minutes.
661 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
662 # was received from the device. This field is only for configurations
663 # sent through MQTT.
664 "logLevel": "A String", # **Beta Feature**
665 #
666 # The logging verbosity for device activity. If unspecified,
667 # DeviceRegistry.log_level will be used.
668 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
669 # has been reported, this field is not present.
670 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
671 # IoT Core.
672 "binaryData": "A String", # The device state data.
673 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]674 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
675 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]676 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
677 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
678 # field. If no errors have occurred, this field has an empty message
679 # and the status code 0 == OK. Otherwise, this field is expected to have a
680 # status code other than OK.
681 # different programming environments, including REST APIs and RPC APIs. It is
682 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
683 # three pieces of data: error code, error message, and error details.
684 #
685 # You can find out more about this error model and how to work with it in the
686 # [API Design Guide](https://cloud.google.com/apis/design/errors).
687 "message": "A String", # A developer-facing error message, which should be in English. Any
688 # user-facing error message should be localized and sent in the
689 # google.rpc.Status.details field, or localized by the client.
690 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
691 "details": [ # A list of messages that carry the error details. There is a common set of
692 # message types for APIs to use.
693 {
694 "a_key": "", # Properties of the object. Contains field @type with type URL.
695 },
696 ],
697 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]698 "credentials": [ # The credentials used to authenticate this device. To allow credential
699 # rotation without interruption, multiple device credentials can be bound to
700 # this device. No more than 3 credentials can be bound to a single device at
701 # a time. When new credentials are added to a device, they are verified
702 # against the registry credentials. For details, see the description of the
703 # `DeviceRegistry.credentials` field.
704 { # A server-stored device credential used for authentication.
705 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
706 # When adding a new device credential, either via device creation or via
707 # modifications, this public key credential may be required to be signed by
708 # one of the registry level certificates. More specifically, if the
709 # registry contains at least one certificate, any new device credential
710 # must be signed by one of the registry certificates. As a result,
711 # when the registry contains certificates, only X.509 certificates are
712 # accepted as device credentials. However, if the registry does
713 # not contain a certificate, self-signed certificates and public keys will
714 # be accepted. New device credentials must be different from every
715 # registry-level certificate.
716 "key": "A String", # The key data.
717 "format": "A String", # The format of the key.
718 },
719 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
720 # credential will be ignored for new client authentication requests after
721 # this timestamp; however, it will not be automatically deleted.
722 },
723 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]724 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
725 # Can be used to temporarily prevent the device from connecting if, for
726 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]727 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
728 # Cloud IoT Core to the device. If not present on creation, the
729 # configuration will be initialized with an empty payload and version value
730 # of `1`. To update this field after creation, use the
731 # `DeviceManager.ModifyCloudToDeviceConfig` method.
732 "version": "A String", # [Output only] The version of this update. The version number is assigned by
733 # the server, and is always greater than 0 after device creation. The
734 # version must be 0 on the `CreateDevice` request if a `config` is
735 # specified; the response of `CreateDevice` will always have a value of 1.
736 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
737 # Cloud IoT Core. This timestamp is set by the server.
738 "binaryData": "A String", # The device configuration data.
739 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
740 # acknowledgment from the device, indicating that the device has received
741 # this configuration version. If this field is not present, the device has
742 # not yet acknowledged that it received this version. Note that when
743 # the config was sent to the device, many config versions may have been
744 # available in Cloud IoT Core while the device was disconnected, and on
745 # connection, only the latest version is sent to the device. Some
746 # versions may never be sent to the device, and therefore are never
747 # acknowledged. This timestamp is set by Cloud IoT Core.
748 },
749 "id": "A String", # The user-defined device identifier. The device ID must be unique
750 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]751 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
752 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
753 # information for the device.
754 #
755 # Keys must conform to the regular expression a-zA-Z+ and
756 # be less than 128 bytes in length.
757 #
758 # Values are free-form strings. Each value must be less than or equal to 32
759 # KB in size.
760 #
761 # The total size of all keys and values must be less than 256 KB, and the
762 # maximum number of key-value pairs is 500.
763 "a_key": "A String",
764 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]765 },
766 ],
767 }</pre>
768</div>
769
770<div class="method">
771 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
772 <pre>Retrieves the next page of results.
773
774Args:
775 previous_request: The request for the previous page. (required)
776 previous_response: The response from the request for the previous page. (required)
777
778Returns:
779 A request object that you can call 'execute()' on to request the next
780 page. Returns None if there are no more items in the collection.
781 </pre>
782</div>
783
784<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]785 <code class="details" id="modifyCloudToDeviceConfig">modifyCloudToDeviceConfig(name, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]786 <pre>Modifies the configuration for the device, which is eventually sent from
787the Cloud IoT Core servers. Returns the modified configuration version and
788its metadata.
789
790Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]791 name: string, Required. The name of the device. For example,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]792`projects/p0/locations/us-central1/registries/registry0/devices/device0` or
793`projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]794 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]795 The object takes the form of:
796
797{ # Request for `ModifyCloudToDeviceConfig`.
798 "versionToUpdate": "A String", # The version number to update. If this value is zero, it will not check the
799 # version number of the server and will always update the current version;
800 # otherwise, this update will fail if the version number found on the server
801 # does not match this version number. This is used to support multiple
802 # simultaneous updates without losing data.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]803 "binaryData": "A String", # Required. The configuration data for the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]804 }
805
806 x__xgafv: string, V1 error format.
807 Allowed values
808 1 - v1 error format
809 2 - v2 error format
810
811Returns:
812 An object of the form:
813
814 { # The device configuration. Eventually delivered to devices.
815 "version": "A String", # [Output only] The version of this update. The version number is assigned by
816 # the server, and is always greater than 0 after device creation. The
817 # version must be 0 on the `CreateDevice` request if a `config` is
818 # specified; the response of `CreateDevice` will always have a value of 1.
819 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
820 # Cloud IoT Core. This timestamp is set by the server.
821 "binaryData": "A String", # The device configuration data.
822 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
823 # acknowledgment from the device, indicating that the device has received
824 # this configuration version. If this field is not present, the device has
825 # not yet acknowledged that it received this version. Note that when
826 # the config was sent to the device, many config versions may have been
827 # available in Cloud IoT Core while the device was disconnected, and on
828 # connection, only the latest version is sent to the device. Some
829 # versions may never be sent to the device, and therefore are never
830 # acknowledged. This timestamp is set by Cloud IoT Core.
831 }</pre>
832</div>
833
834<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]835 <code class="details" id="patch">patch(name, body=None, updateMask=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]836 <pre>Updates a device.
837
838Args:
839 name: string, The resource path name. For example,
840`projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
841`projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
842When `name` is populated as a response from the service, it always ends
843in the device numeric ID. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]844 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]845 The object takes the form of:
846
847{ # The device resource.
848 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
849 # periodically collected and written to storage; they may be stale by a few
850 # minutes.
851 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
852 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
853 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]854 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]855 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
856 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]857 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]858 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]859 "name": "A String", # The resource path name. For example,
860 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
861 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
862 # When `name` is populated as a response from the service, it always ends
863 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]864 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
865 # periodically collected and written to storage; they may be stale by a few
866 # minutes.
867 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
868 # publish to Cloud Pub/Sub. This field is the timestamp of
869 # 'last_error_status'.
870 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
871 # more compact way to identify devices, and it is globally unique.
872 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
873 # applies only to devices connecting through MQTT. MQTT clients usually only
874 # send `PINGREQ` messages if the connection is idle, and no other messages
875 # have been sent. Timestamps are periodically collected and written to
876 # storage; they may be stale by a few minutes.
877 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
878 # was received from the device. This field is only for configurations
879 # sent through MQTT.
880 "logLevel": "A String", # **Beta Feature**
881 #
882 # The logging verbosity for device activity. If unspecified,
883 # DeviceRegistry.log_level will be used.
884 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
885 # has been reported, this field is not present.
886 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
887 # IoT Core.
888 "binaryData": "A String", # The device state data.
889 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]890 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
891 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]892 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
893 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
894 # field. If no errors have occurred, this field has an empty message
895 # and the status code 0 == OK. Otherwise, this field is expected to have a
896 # status code other than OK.
897 # different programming environments, including REST APIs and RPC APIs. It is
898 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
899 # three pieces of data: error code, error message, and error details.
900 #
901 # You can find out more about this error model and how to work with it in the
902 # [API Design Guide](https://cloud.google.com/apis/design/errors).
903 "message": "A String", # A developer-facing error message, which should be in English. Any
904 # user-facing error message should be localized and sent in the
905 # google.rpc.Status.details field, or localized by the client.
906 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
907 "details": [ # A list of messages that carry the error details. There is a common set of
908 # message types for APIs to use.
909 {
910 "a_key": "", # Properties of the object. Contains field @type with type URL.
911 },
912 ],
913 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]914 "credentials": [ # The credentials used to authenticate this device. To allow credential
915 # rotation without interruption, multiple device credentials can be bound to
916 # this device. No more than 3 credentials can be bound to a single device at
917 # a time. When new credentials are added to a device, they are verified
918 # against the registry credentials. For details, see the description of the
919 # `DeviceRegistry.credentials` field.
920 { # A server-stored device credential used for authentication.
921 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
922 # When adding a new device credential, either via device creation or via
923 # modifications, this public key credential may be required to be signed by
924 # one of the registry level certificates. More specifically, if the
925 # registry contains at least one certificate, any new device credential
926 # must be signed by one of the registry certificates. As a result,
927 # when the registry contains certificates, only X.509 certificates are
928 # accepted as device credentials. However, if the registry does
929 # not contain a certificate, self-signed certificates and public keys will
930 # be accepted. New device credentials must be different from every
931 # registry-level certificate.
932 "key": "A String", # The key data.
933 "format": "A String", # The format of the key.
934 },
935 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
936 # credential will be ignored for new client authentication requests after
937 # this timestamp; however, it will not be automatically deleted.
938 },
939 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]940 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
941 # Can be used to temporarily prevent the device from connecting if, for
942 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]943 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
944 # Cloud IoT Core to the device. If not present on creation, the
945 # configuration will be initialized with an empty payload and version value
946 # of `1`. To update this field after creation, use the
947 # `DeviceManager.ModifyCloudToDeviceConfig` method.
948 "version": "A String", # [Output only] The version of this update. The version number is assigned by
949 # the server, and is always greater than 0 after device creation. The
950 # version must be 0 on the `CreateDevice` request if a `config` is
951 # specified; the response of `CreateDevice` will always have a value of 1.
952 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
953 # Cloud IoT Core. This timestamp is set by the server.
954 "binaryData": "A String", # The device configuration data.
955 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
956 # acknowledgment from the device, indicating that the device has received
957 # this configuration version. If this field is not present, the device has
958 # not yet acknowledged that it received this version. Note that when
959 # the config was sent to the device, many config versions may have been
960 # available in Cloud IoT Core while the device was disconnected, and on
961 # connection, only the latest version is sent to the device. Some
962 # versions may never be sent to the device, and therefore are never
963 # acknowledged. This timestamp is set by Cloud IoT Core.
964 },
965 "id": "A String", # The user-defined device identifier. The device ID must be unique
966 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]967 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
968 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
969 # information for the device.
970 #
971 # Keys must conform to the regular expression a-zA-Z+ and
972 # be less than 128 bytes in length.
973 #
974 # Values are free-form strings. Each value must be less than or equal to 32
975 # KB in size.
976 #
977 # The total size of all keys and values must be less than 256 KB, and the
978 # maximum number of key-value pairs is 500.
979 "a_key": "A String",
980 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]981}
982
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]983 updateMask: string, Required. Only updates the `device` fields indicated by this mask.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]984The field mask must not be empty, and it must not contain fields that
985are immutable or only set by the server.
986Mutable top-level fields: `credentials`, `blocked`, and `metadata`
987 x__xgafv: string, V1 error format.
988 Allowed values
989 1 - v1 error format
990 2 - v2 error format
991
992Returns:
993 An object of the form:
994
995 { # The device resource.
996 "lastStateTime": "A String", # [Output only] The last time a state event was received. Timestamps are
997 # periodically collected and written to storage; they may be stale by a few
998 # minutes.
999 "gatewayConfig": { # Gateway-related configuration and state. # Gateway-related configuration and state.
1000 "lastAccessedGatewayTime": "A String", # [Output only] The most recent time at which the device accessed the gateway
1001 # specified in `last_accessed_gateway`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1002 "gatewayType": "A String", # Indicates whether the device is a gateway.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1003 "gatewayAuthMethod": "A String", # Indicates how to authorize and/or authenticate devices to access the
1004 # gateway.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1005 "lastAccessedGatewayId": "A String", # [Output only] The ID of the gateway the device accessed most recently.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1006 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1007 "name": "A String", # The resource path name. For example,
1008 # `projects/p1/locations/us-central1/registries/registry0/devices/dev0` or
1009 # `projects/p1/locations/us-central1/registries/registry0/devices/{num_id}`.
1010 # When `name` is populated as a response from the service, it always ends
1011 # in the device numeric ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1012 "lastEventTime": "A String", # [Output only] The last time a telemetry event was received. Timestamps are
1013 # periodically collected and written to storage; they may be stale by a few
1014 # minutes.
1015 "lastErrorTime": "A String", # [Output only] The time the most recent error occurred, such as a failure to
1016 # publish to Cloud Pub/Sub. This field is the timestamp of
1017 # 'last_error_status'.
1018 "numId": "A String", # [Output only] A server-defined unique numeric ID for the device. This is a
1019 # more compact way to identify devices, and it is globally unique.
1020 "lastHeartbeatTime": "A String", # [Output only] The last time an MQTT `PINGREQ` was received. This field
1021 # applies only to devices connecting through MQTT. MQTT clients usually only
1022 # send `PINGREQ` messages if the connection is idle, and no other messages
1023 # have been sent. Timestamps are periodically collected and written to
1024 # storage; they may be stale by a few minutes.
1025 "lastConfigAckTime": "A String", # [Output only] The last time a cloud-to-device config version acknowledgment
1026 # was received from the device. This field is only for configurations
1027 # sent through MQTT.
1028 "logLevel": "A String", # **Beta Feature**
1029 #
1030 # The logging verbosity for device activity. If unspecified,
1031 # DeviceRegistry.log_level will be used.
1032 "state": { # The device state, as reported by the device. # [Output only] The state most recently received from the device. If no state
1033 # has been reported, this field is not present.
1034 "updateTime": "A String", # [Output only] The time at which this state version was updated in Cloud
1035 # IoT Core.
1036 "binaryData": "A String", # The device state data.
1037 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1038 "lastConfigSendTime": "A String", # [Output only] The last time a cloud-to-device config version was sent to
1039 # the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1040 "lastErrorStatus": { # The `Status` type defines a logical error model that is suitable for # [Output only] The error message of the most recent error, such as a failure
1041 # to publish to Cloud Pub/Sub. 'last_error_time' is the timestamp of this
1042 # field. If no errors have occurred, this field has an empty message
1043 # and the status code 0 == OK. Otherwise, this field is expected to have a
1044 # status code other than OK.
1045 # different programming environments, including REST APIs and RPC APIs. It is
1046 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
1047 # three pieces of data: error code, error message, and error details.
1048 #
1049 # You can find out more about this error model and how to work with it in the
1050 # [API Design Guide](https://cloud.google.com/apis/design/errors).
1051 "message": "A String", # A developer-facing error message, which should be in English. Any
1052 # user-facing error message should be localized and sent in the
1053 # google.rpc.Status.details field, or localized by the client.
1054 "code": 42, # The status code, which should be an enum value of google.rpc.Code.
1055 "details": [ # A list of messages that carry the error details. There is a common set of
1056 # message types for APIs to use.
1057 {
1058 "a_key": "", # Properties of the object. Contains field @type with type URL.
1059 },
1060 ],
1061 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1062 "credentials": [ # The credentials used to authenticate this device. To allow credential
1063 # rotation without interruption, multiple device credentials can be bound to
1064 # this device. No more than 3 credentials can be bound to a single device at
1065 # a time. When new credentials are added to a device, they are verified
1066 # against the registry credentials. For details, see the description of the
1067 # `DeviceRegistry.credentials` field.
1068 { # A server-stored device credential used for authentication.
1069 "publicKey": { # A public key format and data. # A public key used to verify the signature of JSON Web Tokens (JWTs).
1070 # When adding a new device credential, either via device creation or via
1071 # modifications, this public key credential may be required to be signed by
1072 # one of the registry level certificates. More specifically, if the
1073 # registry contains at least one certificate, any new device credential
1074 # must be signed by one of the registry certificates. As a result,
1075 # when the registry contains certificates, only X.509 certificates are
1076 # accepted as device credentials. However, if the registry does
1077 # not contain a certificate, self-signed certificates and public keys will
1078 # be accepted. New device credentials must be different from every
1079 # registry-level certificate.
1080 "key": "A String", # The key data.
1081 "format": "A String", # The format of the key.
1082 },
1083 "expirationTime": "A String", # [Optional] The time at which this credential becomes invalid. This
1084 # credential will be ignored for new client authentication requests after
1085 # this timestamp; however, it will not be automatically deleted.
1086 },
1087 ],
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1088 "blocked": True or False, # If a device is blocked, connections or requests from this device will fail.
1089 # Can be used to temporarily prevent the device from connecting if, for
1090 # example, the sensor is generating bad data and needs maintenance.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1091 "config": { # The device configuration. Eventually delivered to devices. # The most recent device configuration, which is eventually sent from
1092 # Cloud IoT Core to the device. If not present on creation, the
1093 # configuration will be initialized with an empty payload and version value
1094 # of `1`. To update this field after creation, use the
1095 # `DeviceManager.ModifyCloudToDeviceConfig` method.
1096 "version": "A String", # [Output only] The version of this update. The version number is assigned by
1097 # the server, and is always greater than 0 after device creation. The
1098 # version must be 0 on the `CreateDevice` request if a `config` is
1099 # specified; the response of `CreateDevice` will always have a value of 1.
1100 "cloudUpdateTime": "A String", # [Output only] The time at which this configuration version was updated in
1101 # Cloud IoT Core. This timestamp is set by the server.
1102 "binaryData": "A String", # The device configuration data.
1103 "deviceAckTime": "A String", # [Output only] The time at which Cloud IoT Core received the
1104 # acknowledgment from the device, indicating that the device has received
1105 # this configuration version. If this field is not present, the device has
1106 # not yet acknowledged that it received this version. Note that when
1107 # the config was sent to the device, many config versions may have been
1108 # available in Cloud IoT Core while the device was disconnected, and on
1109 # connection, only the latest version is sent to the device. Some
1110 # versions may never be sent to the device, and therefore are never
1111 # acknowledged. This timestamp is set by Cloud IoT Core.
1112 },
1113 "id": "A String", # The user-defined device identifier. The device ID must be unique
1114 # within a device registry.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1115 "metadata": { # The metadata key-value pairs assigned to the device. This metadata is not
1116 # interpreted or indexed by Cloud IoT Core. It can be used to add contextual
1117 # information for the device.
1118 #
1119 # Keys must conform to the regular expression a-zA-Z+ and
1120 # be less than 128 bytes in length.
1121 #
1122 # Values are free-form strings. Each value must be less than or equal to 32
1123 # KB in size.
1124 #
1125 # The total size of all keys and values must be less than 256 KB, and the
1126 # maximum number of key-value pairs is 500.
1127 "a_key": "A String",
1128 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1129 }</pre>
1130</div>
1131
1132<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1133 <code class="details" id="sendCommandToDevice">sendCommandToDevice(name, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1134 <pre>Sends a command to the specified device. In order for a device to be able
1135to receive commands, it must:
11361) be connected to Cloud IoT Core using the MQTT protocol, and
11372) be subscribed to the group of MQTT topics specified by
1138 /devices/{device-id}/commands/#. This subscription will receive commands
1139 at the top-level topic /devices/{device-id}/commands as well as commands
1140 for subfolders, like /devices/{device-id}/commands/subfolder.
1141 Note that subscribing to specific subfolders is not supported.
1142If the command could not be delivered to the device, this method will
1143return an error; in particular, if the device is not subscribed, this
1144method will return FAILED_PRECONDITION. Otherwise, this method will
1145return OK. If the subscription is QoS 1, at least once delivery will be
1146guaranteed; for QoS 0, no acknowledgment will be expected from the device.
1147
1148Args:
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1149 name: string, Required. The name of the device. For example,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1150`projects/p0/locations/us-central1/registries/registry0/devices/device0` or
1151`projects/p0/locations/us-central1/registries/registry0/devices/{num_id}`. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1152 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1153 The object takes the form of:
1154
1155{ # Request for `SendCommandToDevice`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]1156 "binaryData": "A String", # Required. The command data to send to the device.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1157 "subfolder": "A String", # Optional subfolder for the command. If empty, the command will be delivered
1158 # to the /devices/{device-id}/commands topic, otherwise it will be delivered
1159 # to the /devices/{device-id}/commands/{subfolder} topic. Multi-level
1160 # subfolders are allowed. This field must not have more than 256 characters,
1161 # and must not contain any MQTT wildcards ("+" or "#") or null characters.
1162 }
1163
1164 x__xgafv: string, V1 error format.
1165 Allowed values
1166 1 - v1 error format
1167 2 - v2 error format
1168
1169Returns:
1170 An object of the form:
1171
1172 { # Response for `SendCommandToDevice`.
1173 }</pre>
1174</div>
1175
1176</body></html>