Esper provides a Python client library to communicate with the Esper APIs to programmatically control and monitor your enterprise's Android-based Dedicated Devices using Esper Manage. To read more about the various capabilities of Esper Manage and Esper managed devices, please visit esper.io.
Current stable release versions are
API version: 1.0.0
SDK version: 0.0.9
See GitHub for code samples and the API documentation for request and response formats.
In this article:
Requirements
- Python: We recommend you use Python 3.4 or above.
- Access to the Esper Console: You'll need Enterprise Admin access to access API Key Management.
- Generate an API key: API key authentication is used for accessing the APIs You will have to generate a key. See Generating an API Key for more information.
Installation
Using pip install
From PyPI
pip install esperclient
or
From GitHub
pip install git+https://github.com/esper-io/esper-client-py.git
From source
Download/Clone the project and install via Setuptools.
$ git clone https://github.com/esper-io/esper-client-py.git
$ cd esper-client-py
$ python setup.py install
Usage
Import esperclient
package
import esperclient
Next, you need to configure your client to talk to APIs. For this you will need the SERVER URL
and the API KEY
as generated in the Requirements section.
configuration = esperclient.Configuration()
configuration.host = 'https://{esper_tenant_name}-api.esper.cloud/api'
configuration.api_key['Authorization'] = '{API KEY}'
configuration.api_key_prefix['Authorization'] = 'Bearer'
Now you can perform various operations as described below. To see the complete list of actions and code samples, visit SDK documentation. To see response formats, visit the API documentation
Some additional information you'll need in order to access Esper APIs is your enterprise ID
, which is a unique id assigned to your Esper Dev account. You can get your Enterprise ID from the web dashboard in Company Settings
tab. The Enterprise ID will be a string in UUID format i.e 595a6107-b137-448d-b217-e20cc58ee84d
.
Examples
Some of the frequently used examples are given below:
Get Token Information
Returns token information such as the Enterprise ID.
from esperclient import TokenApi, ApiClient
from esperclient.rest import ApiException
# create an instance of the API class
api_instance = TokenApi(ApiClient(configuration))
try:
api_response = api_instance.get_token_info()
print(api_response)
except ApiException as e:
print("Exception when calling TokenApi->get_token_info: %s\n" % e)
Output
python
{
"id": "string",
"enterprise": "string",
"user": "string",
"developer_app": "string",
"source_refresh_token": "string",
"token": "string",
"expires_on": "2019-08-29T11:06:03Z",
"scope": [
"string"
],
"created_on": "2019-08-29T11:06:03Z",
"updated_on": "2019-08-29T11:06:03Z"
}
Get Enterprise Information
Returns information about the Enterprise (also known as a tenant).
from esperclient import EnterpriseApi, ApiClient
from esperclient.rest import ApiException
# create an instance of the API class
api_instance = EnterpriseApi(ApiClient(configuration))
enterprise_id = '{enterprise_id}'
try:
api_response = api_instance.get_enterprise(enterprise_id)
print(api_response)
except ApiException as e:
print("Exception when calling EnterpriseApi->get_enterprise: %s\n" % e)
Output
python
{
"id": "string",
"name": "string",
"short_code": "string",
"registered_name": "string",
"registered_address": "string",
"location": "string",
"zipcode": "string",
"contact_person": "string",
"contact_number": "string",
"contact_email": "user@example.com",
"emm": {
"google_enterprise_id": "string"
},
"created_on": "2019-08-29T11:06:03Z",
"updated_on": "2019-08-29T11:06:03Z"
}
List All Devices
Returns a list of all devices in the tenant.
import esperclient
from esperclient.rest import ApiException
# Configure API key authorization: apiKey
configuration = esperclient.Configuration()
configuration.host = 'SERVER_URL'
configuration.api_key['Authorization'] = 'YOUR_API_KEY'
configuration.api_key_prefix['Authorization'] = 'Bearer'
# create an instance of the API class
api_instance = esperclient.DeviceApi(esperclient.ApiClient(configuration))
enterprise_id = 'enterprise_id_example' # str | ID of the enterprise
name = 'name_example' # str | Filter by device name (optional)
group = 'group_example' # str | Filter by group id (optional)
imei = 'imei_example' # str | filter by imei (optional)
state = 56 # int | filter by device state (optional)
brand = 'brand_example' # str | filter by branch (optional)
is_gms = True # bool | filter for gms devices (optional)
search = 'search_example' # str | A search term. Search by device name, imei or mac address (optional)
limit = 20 # int | Number of results to return per page. (optional) (default to 20)
offset = 0 # int | The initial index from which to return the results. (optional) (default to 0)
try:
# Fetch all devices in an enterprise
api_response = api_instance.get_all_devices(enterprise_id, name=name, group=group, imei=imei, state=state, brand=brand, is_gms=is_gms, search=search, limit=limit, offset=offset)
print(api_response)
except ApiException as e:
print("Exception when calling DeviceApi->get_all_devices: %s\n" % e)
Output
python
{
"count": 0,
"next": "string",
"previous": "string",
"results": [
{
"id": "string",
"url": "string",
"device_name": "string",
"policy_name": "string",
"status": 0,
"state": 0,
"current_command": "string",
"suid": "string",
"fcm_id": "string",
"enterprise": "string",
"policy": "string",
"user": "string",
"groups": [
"string"
],
"api_level": 0,
"template_name": "string",
"mqtt_id": "string",
"softwareInfo": {},
"hardwareInfo": {},
"displays": {},
"networkInfo": {},
"memoryInfo": {},
"audioConstraints": {},
"provisioned_on": "2019-05-09T13:28:41Z",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"emm_device": {
"id": 0,
"google_device_id": "string",
"managementType": "string",
"device": "string",
"google_user": 0,
"policy": 0,
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"is_active": true
},
"is_gms": true,
"is_active": true
}
]
}
List All Applications
List all applications in the tenant.
import esperclient
from esperclient.rest import ApiException
# Configure API key authorization: apiKey
configuration = esperclient.Configuration()
configuration.host = 'SERVER_URL'
configuration.api_key['Authorization'] = 'YOUR_API_KEY'
configuration.api_key_prefix['Authorization'] = 'Bearer'
# create an instance of the API class
api_instance = esperclient.ApplicationApi(esperclient.ApiClient(configuration))
enterprise_id = 'enterprise_id_example' # str | A UUID string identifying this enterprise.
application_name = 'application_name_example' # str | filter by application name (optional)
package_name = 'package_name_example' # str | filter by package name (optional)
is_hidden = true # bool | filter default Esper apps (optional)
limit = 20 # int | Number of results to return per page. (optional) (default to 20)
offset = 0 # int | The initial index from which to return the results. (optional) (default to 0)
try:
# List apps in enterprise
api_response = api_instance.get_all_applications(enterprise_id, application_name=application_name, package_name=package_name, is_hidden=is_hidden, limit=limit, offset=offset)
print(api_response)
except ApiException as e:
print("Exception when calling ApplicationApi->get_all_applications: %s\n" % e)
Output
python
{
"count": 0,
"next": "string",
"previous": "string",
"results": [
{
"id": "string",
"versions": [
{
"id": "string",
"version_code": "string",
"build_number": "string",
"hash_string": "string",
"min_sdk_version": "string",
"target_sdk_version": "string",
"download_url": "string"
}
],
"application_name": "string",
"package_name": "string",
"developer": "string",
"category": "string",
"content_rating": "string",
"compatibility": "string",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"is_active": true,
"is_hidden": true,
"enterprise": "string"
}
]
}
Upload an Application
Uploads an application to the Esper tenant. The path in app_file will need to be escaped.
import esperclient
from esperclient.rest import ApiException
api_instance = esperclient.ApplicationApi(esperclient.ApiClient(configuration))
enterprise_id = '{enterprise_id}' # str | A UUID string identifying this enterprise.
app_file = '/path/to/file.apk' # file | valid APK file
try:
# upload an application to enterprise
api_response = api_instance.upload(enterprise_id, app_file)
print(api_response)
except ApiException as e:
print("Exception when calling ApplicationApi->upload: %s\n" % e)
Output
python
{
"application": {
"id": "string",
"versions": [
{
"id": "string",
"version_code": "string",
"build_number": "string",
"hash_string": "string",
"min_sdk_version": "string",
"target_sdk_version": "string",
"download_url": "string"
}
],
"application_name": "string",
"package_name": "string",
"developer": "string",
"category": "string",
"content_rating": "string",
"compatibility": "string",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"is_active": true,
"is_hidden": true,
"enterprise": "string"
}
}
List App Versions
Lists all versions available for the application in that tenant. You will need an application ID (found in List All Applications).
import esperclient
from esperclient.rest import ApiException
api_instance = esperclient.ApplicationApi(esperclient.ApiClient(configuration))
application_id = '{application_id}' # str | A UUID string identifying this application.
enterprise_id = '{enterprise_id}' # str | A UUID string identifying enterprise.
version_code = 'version_code_example' # str | filter by version code (optional)
build_number = 'build_number_example' # str | filter by build number (optional)
limit = 20 # int | Number of results to return per page. (optional) (default to 20)
offset = 0 # int | The initial index from which to return the results. (optional) (default to 0)
try:
# List App versions
api_response = api_instance.get_app_versions(application_id, enterprise_id, version_code=version_code, build_number=build_number, limit=limit, offset=offset)
print(api_response)
except ApiException as e:
print("Exception when calling ApplicationApi->get_app_versions: %s\n" % e)
Output
python
{
"count": 0,
"next": "string",
"previous": "string",
"results": [
{
"id": "string",
"installed_count": 0,
"permissions": [
{
"id": "string",
"permission": "string",
"grant_state": "Default",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"is_active": true,
"enterprise": "string",
"app_version": "string"
}
],
"app_file": "string",
"app_icon": "string",
"version_code": "string",
"build_number": "string",
"size_in_mb": 0,
"hash_string": "string",
"release_name": "string",
"release_comments": "string",
"release_track": "Alpha",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"min_sdk_version": "string",
"target_sdk_version": "string",
"is_enabled": true,
"enterprise": "string",
"application": "string"
}
]
}
Deploy Application to Device
Install an application to a device. You will need the app version ID (found in List app version) and the device ID (found in List all Devices). The application will install once the device communicates with the Esper Cloud. It may take a while to install on the device. See Installing Apps During Provisioning for more information.
import esperclient
from esperclient.rest import ApiException
api_instance = esperclient.CommandsApi(esperclient.ApiClient(configuration))
command_args = esperclient.CommandArgs(app_version='{app_version}') # replace with valid uuid
command = esperclient.CommandRequest(command='INSTALL', command_args=command_args)
device_id = {device_id} # replace with valid uuid
enterprise_id = {enterprise_id} # replace with valid uuid
try:
api_response = api_instance.run_command(enterprise_id, device_id, command)
print(api_response)
except ApiException as e:
print("Exception when calling CommandsApi->run_command: %s\n" % e)
Output
{
"id": "string",
"current_base_uri": "string",
"command_args": {},
"action": "acknowledge",
"schedule": "string",
"group_schedule_id": "string",
"command": "INSTALL",
"state": "Command Initiated",
"details": "string",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"enterprise": "string",
"device": "string",
"group_command": "string",
"issued_by": "string"
}
Reboot a Device
Reboots a device. The device must be communicating with Esper to execute the command.
import esperclient
from esperclient.rest import ApiException
api_instance = esperclient.CommandsApi(esperclient.ApiClient(configuration))
command = esperclient.CommandRequest(command='REBOOT')
device_id = {device_id} # replace with valid uuid
enterprise_id = {enterprise_id} # replace with valid uuid
try:
api_response = api_instance.run_command(enterprise_id, device_id, command)
print(api_response)
except ApiException as e:
print("Exception when calling CommandsApi->run_command: %s\n" % e)
Output
python
{
"id": "string",
"current_base_uri": "string",
"command_args": {},
"action": "acknowledge",
"schedule": "string",
"group_schedule_id": "string",
"command": "REBOOT",
"state": "Command Initiated",
"details": "string",
"created_on": "2019-05-09T13:28:41Z",
"updated_on": "2019-05-09T13:28:41Z",
"enterprise": "string",
"device": "string",
"group_command": "string",
"issued_by": "string"
}
If you face any issue in SDK usage, we recommend you that you reach out to Esper Support.