EnOS API 快速入门¶

该教程通过一个例子带着你完成你的第一个EnOS API调用任务。

前提条件¶

调用EnOS API需完成以下准备：

获取服务账号

已获取用于调用API时，用于身份授权的服务账号。详细步骤，参考 API鉴权。

获取资源权限

服务账号已取得系统中相关资源的访问权限。详细信息，参考管理服务账号。

准备开发环境

准备调用API的基础环境。参考以下详细介绍：

使用Access Token调用EnOS API¶

使用Java SDK¶

使用SDK调用EnOS API服务，需要安装Java Core SDK (Poseidon)。Poseidon支持Java 7及以上版本。

使用SDK调用接入和资产等API服务，需要额外安装Device And Asset API Pojo SDK。

安装方法¶

Java Core SDK (Poseidon)

访问 Maven仓库，下载Poseidon Jar安装包，在应用中引入Jar安装包。如果应用使用 pom 工程，则在 pom.xml 文件中加入以下依赖（需适时更新其版本）：

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

Device and Asset API Pojo SDK

访问 Maven仓库，下载Jar安装包，在应用中引入Jar安装包。如果应用使用 pom 工程，则在 pom.xml 文件中加入以下依赖（需适时更新其版本）：

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

使用方法¶

同步请求

关闭API日志功能，调用API后仅返回调用结果。示例代码如下：

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();

开启API日志功能，调用API后返回带时间戳的调用参数和调用结果。示例代码如下：

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();

POST请求，示例代码如下：

Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
            .url("https://{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
            .method("POST")
            .header("Content-Type", "application/json")
            .requestBody(
                "{\n" + "  \"op\": \"pl\",\n" + "  \"offset\": 0,\n" + "  \"limit\": 10\n" + "}")
            .sync();

备注

Request header为可选，可按需将请求内容的类型等规范包含在header中。

异步请求

示例代码如下：

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
              }
            });

支持Request和Response

Request内置支持Header，Query，RequestBody，Path参数。Request和Response的使用方法，参考示例3和示例4。

异常处理

调用API的异常情况，可捕获PoseidonException异常查看具体问题。API服务报错，可根据错误码，参考各API的说明文档。

PoseidonException返回的常见报错信息和说明如下：

错误码	错误码描述	错误信息	错误原因
400	Bad Request	Cannot process request body	获取request body失败
401	Unauthorized	Invalid authentication credentials	身份验证失败
403	Forbidden	Your IP address is not allowed	IP地址不允许访问
413	Payload Too Large	Request size limit exceeded	超出请求大小限制
429	Too Many Requests	API rate limit exceeded	超出API请求次数限制
500	Internal Server Error	An unexpected error occurred	查询缓存失败
503	Service unavailable	Service unavailable	服务禁止访问

使用Python调用SDK¶

使用Python调用SDK，需要安装Python core SDK（Athena）V0.1.1及以上版本。Athena支持Python 3.6及以上版本。

安装方法¶

通过以下pip命令安装：

pip install aphrodite

使用方法¶

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)

调用EnOS API¶

开发环境准备完成后，参考各API接口文档中的参数说明和调用示例，调用API。

示例1 - 使用Java core SDK（GET方法）¶

以下示例为使用Java core SDK调用Get Asset API获取资产详细信息（关闭API日志功能）：

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);
        }
    }

以上示例代码运行完成后，返回数据示例为：

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

示例2 - 使用Java core SDK（POST方法）¶

以下示例为使用Java core SDK调用Update Asset API更新资产的名称、描述、属性、时区、标签信息（开启API日志功能）：

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);
    }
}

以上示例代码运行完成后，返回数据示例为：

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}

示例3 - 使用Java core SDK和Device and Asset API SDK（GET方法）¶

以下示例为使用Java core SDK和Device and Asset API Pojo SDK调用GET Asset API获取资产详细信息（开启API日志功能）：

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());
    }
}

以上示例代码运行完成后，返回数据示例为：

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

示例4 - 使用Java core SDK和Device and Asset API SDK（POST方法）¶

以下示例为使用Java core SDK和Device and Asset API Pojo SDK调用Update Asset API更新资产的描述、属性、时区信息（开启API日志功能）：

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);
    }
}

以上示例代码运行完成后，返回数据示例为：

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}