Application Helpers

The Cumulocity Python API (c8y_api.app module) is designed to be particularly useful for developing Cumulocity microservices. For this, the module provides two helper classes that take care of microservice specific authentication.

The SimpleCumulocityApp class should be used for single tenant microservices. It automatically reads the microservice's environment to determines the microservice access credentials.

The MultiTenantCumulocityApp class should be used for multi-tenant microservices which need to handle requests for arbitrary Cumulocity tenants. It reads the microservice's environment to determine the necessary bootstrap credentials and provides additional functions to dynamically obtain CumulocityApi instances for specific tenants.

`SimpleCumulocityApp`

Application-like Cumulocity API.

The SimpleCumulocityApp class is intended to be used as base within a single-tenant microservice hosted on Cumulocity. It evaluates the environment to the resolve the authentication information automatically.

Note: This class should be used in Cumulocity microservices using the PER_TENANT authentication mode only. It will not function in environments using the MULTITENANT mode.

The SimpleCumulocityApp class is an enhanced version of the standard CumulocityApi class. All Cumulocity functions can be used directly. Additionally, it can be used to provide CumulocityApi instances for specific named users via the get_user_instance function.

`MultiTenantCumulocityApp`

Multi-tenant enabled Cumulocity application wrapper.

The MultiTenantCumulocityApp class is intended to be used as base within a multi-tenant microservice hosted on Cumulocity. It evaluates the environment to the resolve the bootstrap authentication information automatically.

Note: This class is intended to be used in Cumulocity microservices using the MULTITENANT authentication mode. It will not function in PER_TENANT environments.

The MultiTenantCumulocityApp class serves as a factory. It provides access to tenant-specific CumulocityApi instances via the get_tenant_instance function. A special bootstrap CumulocityApi instance is available via the bootstrap_instance property.

`clear_tenant_cache(tenant_id: str) -> None`

Manually clean the tenant sessions cache.

Parameters:

Name	Type	Description	Default
`tenant_id`	`str`	Name of a specific tenant to remove or None to clean the cache completely	required

`get_subscribers() -> list[str]`

Query the subscribed tenants.

Returns:

Type	Description
`list[str]`	A list of tenant ID.

`get_tenant_instance(tenant_id: str = None, headers: Mapping[str, str] = None, cookies: Mapping[str, str] = None) -> CumulocityApi`

Provide access to a tenant-specific instance in a multi-tenant application setup.

Parameters:

Name	Type	Description	Default
`tenant_id`	`str`	ID of the tenant to get access to	`None`
`headers`	`Mapping`	Inbound request headers, the tenant ID is resolved from the Authorization header	`None`
`cookies`	`Mapping`	A dictionary of HTTP Cookie entries. The user access is based on an authorization cookie as provided by Cumulocity.	`None`

Returns:

Type	Description
`CumulocityApi`	A CumulocityApi instance authorized for a tenant user