通过 EnOS SDK 调用 EnOS API¶

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

前提条件¶

调用 EnOS API 前，需确保已获取应用服务账号，并为应用分配 API 调用权限和资源访问权限。详细步骤，参考 API 鉴权。

使用 Java SDK¶

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

安装方法¶

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

<dependency>
  <groupId>com.enos-iot</groupId>
  <artifactId>apim-poseidon</artifactId>
  <version>0.2.4</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();

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) 函数方法之前调用。

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 参数。

异常处理¶

调用 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.	服务禁止访问。

调用示例¶

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

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

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

import com.enosiot.apim.poseidon.config.PConfig;
import com.enosiot.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.enosiot.apim.poseidon.config.PConfig;
import com.enosiot.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}