Invoking EnOS APIs Using EnOS SDKs¶

This tutorial will guide you in your first EnOS API request using EnOS SDKs, with the help of examples.

Prerequisites¶

Before calling EnOS APIs, ensure that you have obtained an application service account and assigned API calling permissions and resource access permissions to the application. For more details, refer to API Authentication.

Using Java SDK¶

To invoke EnOS APIs using Java SDK, you need to install the Java Core SDK (Poseidon). Poseidon supports Java 7 and onwards.

Note

To invoke the Connection Service and Asset Service APIs, additionally install the Device and Asset API Pojo SDK.

Installation Method¶

Java core SDK (Poseidon)¶

Open the EnOS SDKs & Tools, 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 (you may need to change the version number):

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

Device and Asset API Pojo SDK¶

Open the EnOS SDKs & Tools, 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 (you may need to change the version number):

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

Request Method¶

Synchronous Request¶

For the GET method, if the API logging feature is disabled, only the result is returned 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();

For the GET method, if the API logging feature is enabled, both the request parameters with time stamp and response are returned 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();

For the GET method, supports independent path setting. The sample code is as follows:

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

Note

.path(xxx) must be called before .queryParam(xxx,xxx).

For the 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 below.

Exception Handling¶

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

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

Code	Description	Message	Cause
400	Bad Request	Cannot process request body	Failed to get request body.
401	Unauthorized	Invalid authentication credentials	Failed to authenticate the identification.
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 from cache.
503	Service unavailable	Service unavailable	The service is not allowed to access.

Using Python SDK¶

To invoke EnOS Cloud APIs using Python SDK, install the Python core SDK (Athena) V0.1.4 or newer versions. Athena supports Python 3.6 and onwards.

Note

EnOS Edge APIs do not support Python SDK.

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)

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)

Using Go SDK¶

To invoke EnOS Cloud APIs or EnOS Edge APIs using Go SDK, you need to install the Go SDK, which supports Go 1.13 and newer versions.

Installation Method¶

Import the Go SDK in the go.mod file of applications by the following commands:

require poseidon-sdk-go v0.0.0-20210421031313-9a8294f797c1

replace poseidon-sdk-go v0.0.0-20210421031313-9a8294f797c1 => git.envisioncn.com/edge/poseidon-sdk-go v0.0.0-20210421031313-9a8294f797c1

Request Method¶

For the GET method, if the API logging feature is disabled, only the result is returned after calling the API. The sample code is as follows:

var header map[string]string
res, err := poseidon.NewPoseidon().
     AppKey("accessKey").
     AppSecret("secretKey").
     Url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}").
     Header(header).
     Method(poseidon.MethodGet).
     Sync()

For the GET method, if the API logging feature is enabled, both the request parameters with time stamp and response are returned after calling the API. The sample code is as follows:

var header map[string]string
res, err := poseidon.NewPoseidon().
     AppKey("accessKey").
     AppSecret("secretKey").
     Url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}").
     Header(header).
     Method(poseidon.MethodGet).
     Debug().
     Sync()

For the GET method, supports independent path setting. The sample code is as follows:

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

Note

.path(xxx) must be called before .queryParam(xxx,xxx).

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

type Testbody struct {
 Name string
}

var testbody Testbody
testbody.Name = "UserName"
var body interface{} = testbody
var header map[string]string
res, err := poseidon.NewPoseidon().
     AppKey("accessKey").
     AppSecret("secretKey").
     Url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}").
     Body(body).
     Header(header).
     Method(poseidon.MethodPost).

For uploading files request, the sample code is as follows:

var bodyMap = make(map[string]string)
bodyMap["file"] = "D:\\data\\file\\test.txt"
var body interface{} = bodyMap
var header = make(map[string]string)
header["Content-Type"] = "multipart/form-data"
res, err := poseidon.NewPoseidon().
     AppKey("accessKey").
     AppSecret("secretKey").
     Url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}").
     Body(body).
     Header(header).
     Method(poseidon.MethodPost).
     Sync()

For downloading files request, the sample code is as follows:

var header = make(map[string]string)
res, err := poseidon.NewPoseidon().
     AppKey("accessKey").
     AppSecret("secretKey").
     Url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}").
        Header(header).
        Method(poseidon.MethodPost).
        FilePath("D://data//file//").
        FileName("test.txt").
        Sync()

For exception handling, the Poseidon struct supports Header, Body, and Debug parameters, and it currently supports the Get, Post, Put, and Delete methods. Refer to err in Sync() to view specific API exception issues.

Invoking Samples¶

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 by using the 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 returned data sample 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 by using the 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 returned data sample 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 by using the Java core SDK and the 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 returned data sample 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 by 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 returned data sample 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}

Invoking EnOS APIs Using EnOS SDKs¶

Prerequisites¶

Using Java SDK¶

Installation Method¶

Java core SDK (Poseidon)¶

Device and Asset API Pojo SDK¶

Request Method¶

Synchronous Request¶

Asynchronous Request¶

Support for Request and Response¶

Exception Handling¶

Using Python SDK¶

Installation Method¶

Request Method¶

Query¶

Header¶

Body¶

Using Go SDK¶

Installation Method¶

Request Method¶

Invoking Samples¶

Sample 1 - Using Java core SDK (GET Method)¶

Sample 2 - Using Java core SDK (POST Method)¶

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

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