Esper SDK for Python

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 verions are

API version: 1.0.0
SDK version: 0.0.6

Note: Esper plans to release SDK support for Kotlin, Java, and JavaScript. If you are using a language other than Python and would like to immediately work with the Esper APIs, please consider calling the APIs directly. You can refer to the Esper API documentation here.

Pre-requisites

  1. Python: We recommend you use Python 3.4 or above.
  2. Access to Esper Dev console: Sign up for the Esper Dev Trial to obtain access to the Esper Dev Console with a private Esper Cloud account. During that process you will set your environment name. Once your environment is set up you can login to your account on foo.shoonyacloud.com where “foo” is your chosen environment name giving you access to both the Esper Dev Console and the Esper Manage Dashboard. Your SERVER URL will be https://foo-api.shoonyacloud.com/api. See Requesting an Esper Dev Trial account.
  3. Generate an API key: API key authentication is used for accessing APIs. You will have to generate this from the Esper Manage Dashboard. Web Dashboard for your account can be accessed at https://foo.shoonyacloud.com. See Generating an API Key

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

You do not need to install setuptools separately since they are packaged along with the downloaded library

Usage

Import esperclient package

import esperclient

Next, you need to configure your client to talk to APIs. For this you will need SERVER URL and API KEY as generated in pre-requisites section.

configuration = esperclient.Configuration()
configuration.host = 'https://myapp-api.shoonyacloud.com/api'
configuration.api_key['Authorization'] = 'LpDriKp7MWJiRGcwc8xzREeUj8OEFa'
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 API documentation

Some additional information you'll need in order to access Esper APIs is your enterprise ID, which is a unique id assinged to your Esper Dev account. You can get your Enteprise ID from the web dashboard in Enterprise 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 entperise information

from esperclient import EnterpriseApi, ApiClient
from esperclient.rest import ApiException

# create an instance of the API class
api_instance = EnterpriseApi(ApiClient(configuration))
enterprise_id = '595a6107-b137-448d-b217-e20cc58ee84d'
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

{
  "id": "string",
  "url": "string",
  "name": "string",
  "display_name": "string",
  "short_code": "string",
  "mdm_service": 1,
  "details": {
    "id": "string",
    "registered_name": "string",
    "registered_address": "string",
    "location": "string",
    "zipcode": "string",
    "contact_person": "string",
    "contact_number": "string",
    "contact_email": "user@example.com",
    "created_on": "2019-05-09T13:28:41Z",
    "updated_on": "2019-05-09T13:28:41Z",
    "is_active": true
  },
  "default_policy": 0,
  "emm": {
    "id": 0,
    "google_enterprise_id": "string",
    "name": "string",
    "state": 1,
    "callback_url": "string",
    "signup_url": "string",
    "completion_token": "string",
    "enterprise_token": "string",
    "is_active": true,
    "created_on": "2019-05-09T13:28:41Z",
    "updated_on": "2019-05-09T13:28:41Z",
    "enterprise": "string"
  },
  "created_on": "2019-05-09T13:28:41Z",
  "updated_on": "2019-05-09T13:28:41Z",
  "is_active": true
}

List all devices

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

{
  "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

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

{
  "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

import esperclient
from esperclient.rest import ApiException

api_instance = esperclient.ApplicationApi(esperclient.ApiClient(configuration))
enterprise_id = '595a6107-b137-448d-b217-e20cc58ee84d' # 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

{
  "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

import esperclient
from esperclient.rest import ApiException

api_instance = esperclient.ApplicationApi(esperclient.ApiClient(configuration))
application_id = '222a6107-b237-248d-c117-e20cc58ee74e' # str | A UUID string identifying this application.
enterprise_id = '595a6107-b137-448d-b217-e20cc58ee84d' # 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

{
  "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 app to device

import esperclient
from esperclient.rest import ApiException

api_instance = esperclient.CommandsApi(esperclient.ApiClient(configuration))
command_args = esperclient.CommandArgs(app_version='2f81b955-4a30-4b1b-a99f-b4016ba24854')  # replace with valid uuid
command = esperclient.CommandRequest(command='INSTALL', command_args=command_args)
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

import esperclient
from esperclient.rest import ApiException

api_instance = esperclient.CommandsApi(esperclient.ApiClient(configuration))
command = esperclient.CommandRequest(command='REBOOT')
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": "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"
}

We are always in active development and we try our best to keep all of our documentation up to date. However, if you have time you can check our latest documentation on Github for code samples and API documentation as well as request and response formats.

If you face any issue in SDK usage, we recommend you that you reach out to Esper Dev Support