• Documentation
• Get Started with EnOS Edge API

Get Started with EnOS Edge API

This tutorial helps you complete your first EnOS Edge API request with examples.

Prerequisites

The following preparations are required to invoke the EnOS Edge API:

Get the service account

Get the service account that can be used for identity authorization when invoking the API. For detailed steps, see API Authentication.

Get resource permissions

The service account has the permissions to access to related resources in the system. For details, see Managing Service Accounts.

Prepare the development environment

Install the EnOS SDK and prepare the basic environment for API request. Refer to the following details:

Invoking SDK with Java

To invoke the SDK using Java, install the Java core SDK (Poseidon). Poseidon supports Java 7 and newer versions.

To invoke APIs of the Connection Service and Asset Service, install the Device and Asset API Pojo SDK V0.2.3 or newer versions.

Installation Method

Java core SDK (Poseidon)

Open the Maven Repository of the SDK, download the installation package, and import it to your development environment. If your application uses the pom project, add the following dependencies to the pom.xml file:

<dependency>
  <groupId>com.envisioniot</groupId>
  <artifactId>apim-poseidon</artifactId>
  <version>0.1.8</version>
</dependency>

Device and Asset API Pojo SDK

Open the Maven Repository of the SDK, download the installation package, and import it to your development environment. If your application uses the pom project, add the following dependencies to the pom.xml file:

<dependency>
  <groupId>com.envisioniot</groupId>
  <artifactId>enos-dm-api-pojo</artifactId>
  <version>0.2.3</version>
</dependency>

Request Method

Synchronous Request

1. With the API logging feature disabled, returns the result only after calling the API. The sample code is as follows:

   Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
        .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
        .method("GET")
        .sync();
   

2. With the API logging feature enabled, returns both the request parameters with time stamp and response after calling the API. The sample code is as follows:

   Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
        .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
        .method("GET")
        .sync();
   

3. For POST method, the sample code is as follows:

   Poseidon.config(PConfig.init().accessKey(accessKey).secretKey(secretKey).debug())
               .url("https://{apigw-address}/lily/0.0.1/getPublic")
               .method("POST")
               .header("Content-Type", "application/json")
               .header("Cookie", "global_id=IAM_S_S7Yd5WXssqEBCququgzeR9JLNBnWr99S")
               .requestBody(
                   "{\n" + "  \"op\": \"pl\",\n" + "  \"offset\": 0,\n" + "  \"limit\": 10\n" + "}")
               .sync();
   

Note

Request header is optional. Specifications such as the type of request content can be included in the header as needed.

Asynchronous Request

The sample code is as follows:

Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
        .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
        .method("GET").async( new PoseidonListener() {
              @Override
              public void onFailure(String errorMessage) {
                // TODO
              }

              @Override
              public void onResponse(String body) {
                // TODO
              }
            });

Support for Request and Response

Request provides the built-in support for the Header, Query, RequestBody, and Path parameters. For how to use Request and Response, see Sample 3 and Sample 4.

Exception Handling

Capture the PoseidonException to view specific API exception issues. For API service error, refer to the API documentation.

Common error messages and description returned from PoseidonException are as follows：：

Code	Description	Message	Cause
401	Unauthorized	Invalid authentication credentials	Failed to authenticate the identification.
400	Bad Request	Cannot process request body	Failed to get request body.
403	Forbidden	Your IP address is not allowed	The IP address is not allowed to access.
413	Payload Too Large	Request size limit exceeded	The request size exceeded the limit.
429	Too Many Requests	API rate limit exceeded	The number of requests exceeded the API request limit.
500	Internal Server Error	An unexpected error occurred	Failed to search cache.
503	Service unavailable	Service unavailable	The service is not allowed to access.

Invoking SDK with Python

To invoke the SDK using Python, install the Python core SDK (Athena) V0.1.4 or later. Athena supports Python 3.6 and new versions.

Installation Method

Install it by the following pip command:

pip install aphrodite

Request Method

Query

from poseidon import poseidon

accessKey = 'accessKey'
secretKey = 'secretKey'

url = 'https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}'

req = poseidon.urlopen(accessKey, secretKey, url)
print(req)

Header

from poseidon import poseidon

accessKey = 'accessKey'
secretKey = 'secretKey'

url = 'https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}'

header={}

req = poseidon.urlopen(accessKey, secretKey, url, None, header)
print(req)

Body

from poseidon import poseidon

accessKey = 'accessKey'
secretKey = 'secretKey'

url = 'https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}'

data = {"username": "abc", "password": "123"}

req = poseidon.urlopen(accesskey, secretkey, url, data)
print(req)

Invoking EnOS Edge API

After the development environment is ready, refer to the parameter descriptions and invocation examples in the API documentation to invoke the API.

Sample 1 - Using Java core SDK (GET Method)

The following sample shows how to get the asset details using Java core SDK to invoke the Get Asset API (with API logging feature disabled):

import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;

public class GetAsset {
    public static void main(String[] args) {

        String accessKey = "{access_key_of_the_application}";
        String secretKey = "{secret_key_of_the_application}";

        String response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
                .url("https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId={org_id}&assetId={asset_id}")
                .method("GET")
                .sync();
        System.out.println(response);
        }
    }

The sample of returned data is as follows:

{
  "msg": OK,
  "code": 0,
  "data": {
    "modelId": "model_id",
    "assetId": "asset_id",
    "timezone": "+08:00",
    "name": {
      "i18nValue": {},
      "defaultValue": "asset_name"
    },
    "attributes": {
      "system": "System"
    },
    "modelIdPath": null,
    "orgId": "yourOrgId",
    "desc": null,
    "tags": {}
  },
  "requestId": "9a5cfbac-b2f8-4a37-b38d-8bccdd77d073"
}

Sample 2 - Using Java core SDK (POST Method)

The following sample shows how to update the name, description, attributes, timezone, and tags of an asset using Java core SDK to invoke the Update Asset API (with API logging feature enabled):

import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;

public class UpdateAsset {
    public static void main(String[] args) {

        String accessKey = "{access_key_of_the_application}";
        String secretKey = "{secret_key_of_the_application}";

        String data = "{\"asset\":{\"assetId\":\"{asset_id}\",\"name\":{\"defaultValue\":\"Device_Name\",\"i18nValue\":{\"en_US\":\"Device_Name\",\"zh_CN\":\"Chinese name\"}},\"description\":\"Device_Description\",\"attributes\":{\"Brand\":\"Brand_Name\"},\"timezone\":\"+07:00\",\"tags\":{\"year\":\"2019\",\"site\":\"Site_Name\"}}}";

        String response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
                .url("https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId={org_id}")
                .method("POST")
                .requestBody(data)
                .sync();
        System.out.println(response);
    }
}

The sample of returned data is as follows:

2019-7-10 16:35:12 [Poseidon] url: https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId={org_id}
2019-7-10 16:35:12 [Poseidon] method: POST
2019-7-10 16:35:12 [Poseidon] headers: {}
2019-7-10 16:35:12 [Poseidon] requestBody: {"asset":{"assetId":"{asset_id}","name":{"defaultValue":"Device_Name","i18nValue":{"en_US":"Device_Name","zh_CN":"Chinese name"}},"description":"Device_Description","attributes":{"Brand":"Brand_Name"},"timezone":"+07:00","tags":{"year":"2019","site":"Site_Name"}}}
2019-7-10 16:35:13 [Poseidon] responseBody: {"code":0,"msg":"OK","requestId":"9d6b9869-4ffd-4964-a8ff-d150a0d1a91f","data":null}

Sample 3 - Using Java core SDK and Device and Asset API Pojo SDK (GET Method)

The following sample shows how to get the asset details using Java core SDK and Device and Asset API Pojo SDK to invoke the Get Asset API (with API logging feature enabled):

import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.asset_service.v2_1.GetAssetRequest;
import com.envisioniot.enos.asset_service.v2_1.GetAssetResponse;

public class GetAsset {
    private static String accessKey = "{access_key_of_the_application}";
    private static String secretKey = "{secret_key_of_the_application}";
    private static String orgId = "{org_id}";
    private static String url = "https://{apigw-address}";

    public static void main(String[] args) {
        GetAssetRequest request = new GetAssetRequest();
        request.setOrgId(orgId);
        request.setAssetId("{asset_id}");

        GetAssetResponse response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
                .url(url)
                .getResponse(request, request.getResponseClass());
        System.out.println(response.getCode());
    }
}

The sample of returned data is as follows:

2019-7-10 11:02:27 [Poseidon] url: https://{apigw-address}/asset-service/v2.1/assets?action=get&assetId={asset_id}&orgId={org_id}
2019-7-10 11:02:27 [Poseidon] method: GET
2019-7-10 11:02:27 [Poseidon] headers: {}
2019-7-10 11:02:27 [Poseidon] requestBody: null
2019-7-10 11:02:29 [Poseidon] responseBody:{
  "msg": OK,
  "code": 0,
  "data": {
    "modelId": "model_id",
    "assetId": "asset_id",
    "timezone": "+08:00",
    "name": {
      "i18nValue": {},
      "defaultValue": "asset_name"
    },
    "attributes": {
      "system": "System"
    },
    "modelIdPath": null,
    "orgId": "yourOrgId",
    "desc": null,
    "tags": {}
  },
  "requestId": "39346a7e-1da8-42ec-9620-d44ef6e2e2b6"
}

Sample 4 - Using Java core SDK and Device and Asset API Pojo SDK (POST Method)

The following sample shows how to update the description, attributes, and timezone of an asset using the Java core SDK and the Device and Asset API Pojo SDK to invoke the Update Asset API (with API logging feature enabled):

import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.asset_service.v2_1.UpdateAssetRequest;
import com.envisioniot.enos.asset_service.v2_1.UpdateAssetResponse;
import com.envisioniot.enos.asset_service.vo.AssetUpdateVo;

import java.util.HashMap;
import java.util.Map;

public class UpdateAsset {
    private static String accessKey = "{access_key_of_the_application}";
    private static String secretKey = "{secret_key_of_the_application}";
    private static String orgId = "{org_id}";
    private static String url = "https://{apigw-address}";

    public static void main(String[] args) {
        UpdateAssetRequest request = new UpdateAssetRequest();
        request.setOrgId(orgId);

        AssetUpdateVo asset = new AssetUpdateVo();
        asset.setAssetId("{asset_id}");
        Map<String, Object> newAttrs = new HashMap<>();
        newAttrs.put("Brand","Brand_Name");
        asset.setAttributes(newAttrs);
        asset.setDescription("Device_Description");
        asset.setTimezone("+08:00");

        request.setAsset(asset);
        request.setIsPatchUpdate(true);

        UpdateAssetResponse response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
                .url(url)
                .getResponse(request, request.getResponseClass());
        System.out.println(response);
    }
}

The sample of returned data is as follows:

2019-7-10 16:45:00 [Poseidon] url: https://{apigw-address}/asset-service/v2.1/assets?action=update&isPatchUpdate=true&orgId={org_id}
2019-7-10 16:45:00 [Poseidon] method: POST
2019-7-10 16:45:00 [Poseidon] headers: {}
2019-7-10 16:45:00 [Poseidon] requestBody: {"asset":{"assetId":"{asset_id}","attributes":{"Brand":"Brand_Name"},"description":"Device_Description","timezone":"+08:00"}}
2019-7-10 16:45:01 [Poseidon] responseBody: {"code":0,"msg":"OK","requestId":"4c1a6da8-bd89-4001-b8fd-5fa65ab816f2","data":null}