当您自己的云端(web应用或服务)需要调用生活物联网平台提供的云端API时,您需要先了解调用的使用说明、云云交互流程、获取云端唯一身份AppKey的方法、以及调用云端API的示例。

使用说明

  • 云端API使用的AppKey与App端使用的AppKey不一致,但是访问环境一致。获取云端AppKey的方法参见本文档下方内容。
  • 基于安全考虑,所有云端API调用请使用HTTPS方式,不推荐HTTP方式。
  • 所有的API均为POST调用。

云端调用流程介绍

您自己的云端(web应用或服务)调用生活物联网平台提供的云端API时,与阿里云IoT云端(服务端)之间的交互流程如下图所示。

流程

流程说明如下。

  1. 您的云端通过调用获取云端资源token向阿里云IoT云端请求资源令牌(Cloud Token);阿里云IoT云端收到请求后向您返回Cloud Token,及其对应的失效时间。

    阿里云IoT云端以项目(Project)维度授予Cloud Token,即不同项目的Cloud Token不同。申请Cloud Token时,需携带项目ID。

  2. 您的云端使用获取到的Cloud Token调用阿里云IoT云端某个具体的API;阿里云IoT云端向您返回请求的处理结果。
  3. 在Cloud Token失效前,您的云端通过调用刷新云端资源token接口对当前Cloud Token进行续期。

    如果Cloud Token已经失效,则需重新调用获取云端资源token接口来获取新的Cloud Token及其对应的失效时间。

获取云端Appkey

请您根据以下操作获取云端唯一身份AppKey。

  1. 登录生活物联网控制台
  2. 选择项目名称,单击项目设置
    项目设置
  3. 在弹出的权限授权许可对话框中,单击确认
    权限授权
  4. 单击同意授权
    云资源访问授权
  5. 选择设置数据同步。在云端接口调用区域中,显示了线上环境的AppKeyAppSecret
    设备数据同步

调用示例

生活物联网平台提供了多种语言的云端API调用示例,其他语言请参照示例中的逻辑和加签机制自行实现。

  • Java调用示例
    // https://github.com/aliyun/iotx-api-gateway-client
    public static void main(String[] args) throws UnsupportedEncodingException {
        IoTApiClientBuilderParams ioTApiClientBuilderParams = 
          new IoTApiClientBuilderParams();
        ioTApiClientBuilderParams.setAppKey("你的<AppKey>");
        ioTApiClientBuilderParams.setAppSecret("你的<AppSecret>");
        SyncApiClient syncClient = new SyncApiClient(ioTApiClientBuilderParams)    ;
    
        IoTApiRequest request = new IoTApiRequest();
        //设置API的版本
        //调用/cloud/token接口时,不需要传CloudToken,请参见云端资源服务/cloud/token接口的代码示例
        //调用其他接口(除/cloud/token接口外),都需要先调用/cloud/token接口获取到token,再传入ApiVer和CloudToken,才可以正常调用
        request.setApiVer("1.0.0");
        request.setCloudToken("CloudTokenXXXXX");
    
        //设置接口的参数
        request.putParam("grantType", "project");
        request.putParam("res", "xxxxx");
    
        //请求参数域名、path、request
        //host地址  中国站:api.link.aliyun.com     新加坡:ap-southeast-1.api-iot.aliyuncs.com     美国(弗吉尼亚):us-east-1.api-iot.aliyuncs.com     德国(法兰克福):eu-central-1.api-iot.aliyuncs.com
        ApiResponse response = syncClient.postBody("api.link.aliyun.com",
            "/cloud/token", request, true);
        System.out.println( "response code = " + response.getCode() 
                           + " response = " + new String(response.getBody(), "UTF-8"));
    }
    					
  • PHP调用示例
    //https://github.com/aliyun/api-gateway-demo-sign-php (第三方php库)
    
    <?php
    include_once 'Util/Autoloader.php';
    
    //host地址  中国站:api.link.aliyun.com     新加坡:ap-southeast-1.api-iot.aliyuncs.com     美国(弗吉尼亚):us-east-1.api-iot.aliyuncs.com     德国(法兰克福):eu-central-1.api-iot.aliyuncs.com
    function example() {
        $path      = "/cloud/token";
        $host      = "https://api.link.aliyun.com";
        $appKey    = "你的<AppKey>";
        $appSecret = "你的<AppSecret>"; 
    
        $request = new HttpRequest($host, $path, HttpMethod::POST, $appKey, $appSecret);
        //设置api版本和参数
        $body = '{"id":"xxx","version":"1.0","request":{"apiVer":"1.0.0"},' . 
                '"params":{"grantType":"project","res":"xxx"}}';
    
        //设定Content-Type
        $request->setHeader(HttpHeader::HTTP_HEADER_CONTENT_TYPE, 
                            ContentType::CONTENT_TYPE_JSON);
    
        //设定Accept
        $request->setHeader(HttpHeader::HTTP_HEADER_ACCEPT, 
                            ContentType::CONTENT_TYPE_JSON);
    
        if (strlen($body) > 0) {
            $request->setHeader(HttpHeader::HTTP_HEADER_CONTENT_MD5, 
                                base64_encode(md5($body, true)));
            $request->setBodyString($body);
        }
    
        //指定参与签名的header
        $request->setSignHeader(SystemHeader::X_CA_TIMESTAMP);
    
        $response = HttpClient::execute($request);
        var_dump($response);    
    }
    
    example();
    					
  • Python调用示例
    # https://github.com/aliyun/api-gateway-demo-sign-python/
    # -*- coding: utf-8 -*-
    from com.aliyun.api.gateway.sdk import client
    from com.aliyun.api.gateway.sdk.http import request
    from com.aliyun.api.gateway.sdk.common import constant
    
    host = "https://api.link.aliyun.com"
    url = "/cloud/token"
    
    cli = client.DefaultClient(app_key="appKey", app_secret="appSecret")
    
    # construct request
    req_post = request.Request(host=host, protocol=constant.HTTP, url=url, method="POST", time_out=30000)
    body = '{"id":"xxx","version":"1.0","request":{"apiVer":"1.0.0"},"params":{"grantType":"project","res":"xxx"}}'
    req_post.set_body(bytearray(body, encoding="utf8"))
    req_post.set_content_type(constant.CONTENT_TYPE_STREAM)
    print cli.execute(req_post)
  • .NET调用示例

    调用示例请参见调用示例

  • Node.js调用示例

    调用示例请参见调用示例