• 文档
  • EnOS™ API 快速入门

EnOS™ API 快速入门


该教程通过若干示例，介绍如何通过 EnOS SDK 快速调用 EnOS API 服务。

前提条件

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


获取服务账号

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


获取资源权限

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


准备开发环境

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

使用 Java SDK

EnOS Cloud API 服务和 EnOS Edge API 服务都支持通过 EnOS 提供的 Java Core SDK (Poseidon) 进行调用。Poseidon 支持 Java 7 及以上版本。


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

安装方法

Java Core SDK (Poseidon)

访问 EnOS SDKs和工具 页面，在 API SDKs 一栏中，查看 Java Core SDK 的版本信息和下载链接。下载其 Jar 安装包，在应用中引入 Jar 安装包。如果应用使用 pom 工程，则在 pom.xml 文件中加入以下依赖（需适时更新其版本）：

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


Device and Asset API Pojo SDK

访问 EnOS SDKs 和工具 页面，在 API SDKs 一栏中，查看 Device And Asset API Pojo SDK 的版本信息和下载链接。下载其 Jar 安装包，在应用中引入 Jar 安装包。如果应用使用 pom 工程，则在 pom.xml 文件中加入以下依赖（需适时更新其版本）：

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

使用方法

同步请求

  1. 关闭 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();


  2. 开启 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();


  3. GET 请求，支持独立设置 path。示例代码如下：

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

    注解

    .path(xxx) 方法一定要保证在 .queryParam(xxx,xxx) 函数方法之前调用。


  4. 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

EnOS Cloud API 服务支持通过 EnOS 提供的 Python SDK 进行调用，需安装 Python Core SDK（Athena）V0.1.4 及以上版本。Athena 支持 Python 3.6 及以上版本。

注解

EnOS Edge API 服务暂不支持 Python SDK。

安装方法

通过以下 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)

使用 GO SDK

EnOS Cloud API 服务和 EnOS Edge API 服务都支持通过 EnOS 提供的 Go SDK 进行调用。该 SDK 支持 Go 1.13 及以上版本。

安装方法

通过以下命令，在应用的 go.mod 中导入 SDK 完成安装：

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

使用方法

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

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


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

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


  3. POST 请求，示例代码如下：

    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).


  4. 上传文件请求，示例代码如下：

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


  5. 下载文件请求，示例代码如下：

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


  6. 异常处理: Poseidon Struct 构造支持 Header、Body、和 Debug 参数。目前支持的请求方法为 Get、Post、Put、和 Delete。异常情况可由 Sync() 返回的 err 排查具体问题。

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