REST API Connector

The SDK module provides a convenience wrapper around the standard Cumulocity REST API (see also the OpenAPI documentation).

The CumulocityRestClient class provides the fundamental wrapping around authentication and basic get, post, put, delete commands. The CumulocityClient class is your entrypoint into higher level funct ions, grouped by contexts like inventory, users, and measurements. Each of these contexts is documented in detail within the main-api-classes section.

The DeviceRegistryClient class provides an additional entry point for devices, wrapping the entire bootstrap mechanism. See also the Device integration documentation at Cumulocity.

`CumulocityClient`

Main Cumulocity client.

Provides usage-centric access to a Cumulocity instance.

`init(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)`

`CumulocityRestClient`

`init(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)`

`authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str | None = None) -> tuple[Auth, str | None]` `async` `classmethod`

Authenticate a user using OAI Secure login method.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Cumulocity base URL, e.g. https://cumulocity.com	required
`tenant_id`	`str`	The ID of the tenant to connect to	required
`username`	`str`	Username	required
`password`	`str`	User password	required
`tfa_token`	`str`	Currently valid two-factor authorization token	`None`

Returns:

Type	Description
`tuple[Auth, str \| None]`	A ready to use Auth instance and optionally an XSRF token.

`close()` `async`

`delete(resource: str, params: Mapping[str, Any] | Sequence[tuple[str, Any]] = ()) -> dict` `async`

`get(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, accept: str | None = 'application/json') -> dict` `async`

`get_file(resource: str, params: dict | Sequence[tuple[str, str]] | None = None) -> bytes` `async`

Download a binary file.

Parameters:

Name	Type	Description	Default
`resource`	`str`	The resource path.	required
`params`	`dict \| Sequence[tuple]`	Additional request parameters	`None`

Returns:

Type	Description
`bytes`	The file content as bytes.

Raises:

Type	Description
`KeyError`	if the resource is not found (404)
`ValueError`	if the request cannot be processed (5xx or unexpected status)

`post(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict` `async`

`post_file(resource: str, file: str | os.PathLike | BinaryIO, filename: str | None = None, form_data: dict[str, str | bytes] | None = None, accept: str | None = None, content_type: str | None = None) -> dict` `async`

Upload a binary file using multipart/form-data.

Parameters:

Name	Type	Description	Default
`resource`	`str`	The resource path.	required
`file`	`str \| PathLike \| BinaryIO`	File path or file-like object to upload.	required
`filename`	`str`	The filename for the upload part. Derived from the path if not specified.	`None`
`form_data`	`dict`	Additional file metadata as JSON (nested dict) stored within Cumulocity.	`None`
`accept`	`str`	Accept header value; `application/json` is assumed/automatically inserted if omitted	`None`
`content_type`	`str`	The MIME type of the file; `application/octet-stream` is assumed/automatically inserted if omitted.	`None`

Returns:

Type	Description
`dict`	The JSON response (nested dict), {} if no response body is returned.

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`ValueError`	if the request cannot be processes (5xx) or cannot be processed for other reasons (only 2xx is accepted).

`put(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict` `async`

`put_file(resource: str, file: str | os.PathLike | BinaryIO, accept: str | None = None, content_type: str | None = None) -> dict` `async`

Update a binary file using multipart/form-data.

Parameters:

Name	Type	Description	Default
`resource`	`str`	Resource path	required
`file`	`str \| PathLike \| BinaryIO`	File path or file-like object to upload.	required
`accept`	`str \| None`	Custom Accept header to use (default is application/json).	`None`
`content_type`	`str`	Content type of the file sent (default is application/octet-stream)	`None`

Returns:

Type	Description
`dict`	The JSON response (nested dict), {} if no response body is returned.

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`ValueError`	if the request cannot be processes (5xx) or cannot be processed for other reasons (only 2xx is accepted).

`request(method: str, resource: str, params: Sequence[tuple[str, Any]] | Mapping[str, Any] = (), json: dict | None = None, accept: str | None = None, content_type: str | None = None) -> dict` `async`

Perform an HTTP request.

Parameters:

Name	Type	Description	Default
`method`	`str`	The HTTP method to use.	required
`resource`	`str`	The resource path.	required
`params`	`Sequence \| Mapping`	Additional request parameters	`()`
`json`	`dict`	JSON body (nested dict)	`None`
`accept`	`str`	Accept header value; `application/json` is assumed/automatically inserted if omitted	`None`
`content_type`	`str`	Content-Type header value; `application/json` is assumed/automatically inserted if omitted and `json` is provided.	`None`

Returns:

Type	Description
`dict`	The JSON response (nested dict), {} if no response body is returned.

Raises:

Type	Description
`KeyError`	if the resources is not found (404)
`ValueError`	if the request cannot be processes (5xx) or cannot be processed for other reasons (only 2xx is accepted).

`DeviceRegistryClient`

Cumulocity device registry client.

`await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials` `async`

Wait for device credentials.

The device must have requested credentials already. This function awaits the request confirmation and returns the device-specific credentials generated by the Cumulocity platform.

Parameters:

Name	Type	Description	Default
`device_id`	`str`	The external ID of the device (i.e. IMEI - NOT the Cumulocity ID)	required
`timeout`	`str`	How long to wait for the request to be confirmed. This is a formatted string in the form , accepted units are 'h' (hours), 'm' (minutes), 's' (seconds) and 'ms' (milliseconds). A reasonable value for this depends on application.	`'60m'`
`pause`	`str`	How long to pause between request confirmation checks This is a formatted string, see `timeout` parameter.	`'1s'`

Returns:

Type	Description
`Credentials`	Credentials object holding the device credentials

Raises:

Type	Description
`TimeoutError`	if the request was not confirmed in time.

See also: https://cumulocity.com/guides/users-guide/device-management/#connecting-devices

REST API Connector

CumulocityClient

__init__(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)

CumulocityRestClient

__init__(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)

authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str | None = None) -> tuple[Auth, str | None] async classmethod

close() async

delete(resource: str, params: Mapping[str, Any] | Sequence[tuple[str, Any]] = ()) -> dict async

get(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, accept: str | None = 'application/json') -> dict async

get_file(resource: str, params: dict | Sequence[tuple[str, str]] | None = None) -> bytes async

post(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict async

post_file(resource: str, file: str | os.PathLike | BinaryIO, filename: str | None = None, form_data: dict[str, str | bytes] | None = None, accept: str | None = None, content_type: str | None = None) -> dict async

put(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict async

put_file(resource: str, file: str | os.PathLike | BinaryIO, accept: str | None = None, content_type: str | None = None) -> dict async

request(method: str, resource: str, params: Sequence[tuple[str, Any]] | Mapping[str, Any] = (), json: dict | None = None, accept: str | None = None, content_type: str | None = None) -> dict async

DeviceRegistryClient

await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials async

`CumulocityClient`

`init(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)`

`CumulocityRestClient`

`init(base_url: str, tenant_id: str, auth: Auth, application_key: str | None = None, processing_mode: str | None = None, connector_factory: Callable[[], Awaitable[aiohttp.BaseConnector]] | None = None, semaphore: Semaphore | None = None)`

`authenticate(base_url: str, tenant_id: str, username: str, password: str, tfa_token: str | None = None) -> tuple[Auth, str | None]` `async` `classmethod`

`close()` `async`

`delete(resource: str, params: Mapping[str, Any] | Sequence[tuple[str, Any]] = ()) -> dict` `async`

`get(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, accept: str | None = 'application/json') -> dict` `async`

`get_file(resource: str, params: dict | Sequence[tuple[str, str]] | None = None) -> bytes` `async`

`post(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict` `async`

`post_file(resource: str, file: str | os.PathLike | BinaryIO, filename: str | None = None, form_data: dict[str, str | bytes] | None = None, accept: str | None = None, content_type: str | None = None) -> dict` `async`

`put(resource: str, *, params: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None, json: dict | None = None, accept: str | None = 'application/json', content_type: str | None = None) -> dict` `async`

`put_file(resource: str, file: str | os.PathLike | BinaryIO, accept: str | None = None, content_type: str | None = None) -> dict` `async`

`request(method: str, resource: str, params: Sequence[tuple[str, Any]] | Mapping[str, Any] = (), json: dict | None = None, accept: str | None = None, content_type: str | None = None) -> dict` `async`

`DeviceRegistryClient`

`await_credentials(device_id: str, timeout: str = '60m', pause: str = '1s') -> Credentials` `async`