通过API工具调用IAM认证方式的API

IAM认证方式的API调用前，需要调用IAM服务的获取用户Token接口获取Token，然后通过Token进行安全认证。

本章节以Postman工具为例，为您介绍如何使用API工具调用IAM认证方式的API，主要包含如下几步：

获取API信息：准备API关键信息，用于API调用。
获取Token：调用IAM服务的获取用户Token接口获取Token。
调用API：通过Postman工具调用API。

前提条件

已完成IAM认证方式的API或API工作流的发布，在服务目录中可以查看已发布的API。
已完成API授权，即API开发者已完成通过应用授权IAM认证方式API或通过白名单授权IAM认证方式API，或者API调用者已完成申请API授权。

本章以Postman工具为例，因此需要已安装Postman工具，如果未安装，请至Postman官方网站下载。

约束与限制

通过IAM应用授权的IAM认证方式API，仅支持通过当前账号及其归属用户的Token进行调用，不支持其他账号及其归属用户调用。如有需要可以通过白名单授权的方式授权给其他账号，详见通过白名单授权IAM认证方式API。
如需在本地调用专享版API，则需在创建专享版集群时绑定一个弹性公网IP，作为实例的公网入口。
Token的有效期为24小时，需要同一个Token鉴权时，可以先缓存起来，避免频繁调用。

调用数据服务API时，如果查询及返回数据的总时长超过默认60秒则会报超时错误。此时可通过访问日志中的API调用时长信息，根据超时阶段进一步优化API配置。

____________Duration information__________ 
duration: 60491ms //总耗时
url_duration: 0ms //URL匹配耗时
auth_duration: 70ms //鉴权耗时
befor_sql_duration: 402ms //执行SQL预处理耗时
sql_duration: 60001ms //SQL执行耗时
after_sql_duration:18ms //执行SQL后处理耗时

获取API信息

参考访问DataArts Studio实例控制台，登录DataArts Studio管理控制台。
在DataArts Studio控制台首页，选择对应工作空间的“数据服务”模块，进入数据服务页面。
在左侧导航栏选择服务版本（例如：专享版），进入总览页。
获取待调用API的调用地址、请求方法和入参信息。

在左侧导航栏中进入API管理，找到待调用的API，并单击API名称查看API的完整信息，保存调用地址、请求方法和入参信息。
- 调用地址：专享版支持内网地址和外网地址（外网地址需要您在创建集群时绑定弹性IP），如果需要在本地调用专享版API，需要使用外网地址，确保网络互通。
- 入参：本调用样例中创建了一个具备各类入参位置的API，以便为您介绍各类入参应如何在调用时输入。
  图1 保存调用地址、请求方法和入参信息

获取Token

打开Postman工具，新增一个API请求。
使用API工具调用接口获取Token。

Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择project，如下所示。
请求中的“POST https://IAM endpoint/v3/auth/tokens”为URL，“Content-Type: application/json”为消息头Header。{}内的内容为请求body体。

注意，请求中加粗的斜体字段需要根据实际值填写：
- IAM endpoint为IAM服务的终端节点。
  终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同。Endpoint您可以从地区和终端节点获取。
- username为用户名，domainname为用户所属的账号名，********为用户登录密码，xxxxxxxxxxxxxxxxxx为项目ID。用户名、账号名以及项目ID可以参考如下步骤进行获取：
  1. 注册并登录管理控制台。
  2. 在用户名的下拉列表中单击“我的凭证”。
  3. 在“API凭证”页面，查看账号名和账号ID、IAM用户名和IAM用户ID，在项目列表中查看项目和项目ID。
```
POST https://IAM endpoint/v3/auth/tokens
Content-Type: application/json
```
```
{ 
    "auth": { 
        "identity": { 
            "methods": [ 
                "password" 
            ], 
            "password": { 
                "user": { 
                    "name": "username", 
                    "password": "********", 
                    "domain": { 
                        "name": "domainname" 
                    } 
                } 
            } 
        }, 
        "scope": { 
            "project": { 
                "id": "xxxxxxxxxxxxxxxxxx" 
            } 
        } 
    } 
}
```
图2 调用接口获取Token
获取返回的响应消息头Header中“x-subject-token”值，此即为用户Token。有了Token之后，您就可以在调用API的时候将Token加到请求消息头，从而通过身份认证，获得调用API的权限。

图3 获取Token

调用API

打开Postman工具，新增一个API请求。
API请求配置如下。
- 请求方法和调用地址：参考获取API信息获取，注意如果入参中包含Path和Query参数，则需要将调用地址中的{path}变量修改为Path参数具体取值，Query参数取值可以通过“?Query参数名=Query参数值”的形式添加到调用地址的最后，如本例中为“?query=1”。
  图4 请求方法和调用地址
- Params：如果Query参数已经以“?Query参数名=Query参数值”的形式添加到调用地址的最后，则此处会自动生成Query Params的值，否则就需要手动输入。
  图5 Params
  如果您需要对调用结果进行自定义调整，则还可以配置如下Query参数：
  - （可选）分页配置：默认情况下，对于配置方式和默认分页的脚本/MyBatis方式API，系统将默认赋值返回量。如果需要获取特定分页数据，您可以修改如下参数设置分页，其中pageSize表示分页后的页面大小，pageNum表示页码。
    图6 分页参数设置
    
    自定义分页的脚本/MyBatis方式API是在创建API时将分页逻辑写到取数SQL中，因此不支持在调用时修改分页设置。
  - （可选）排序配置：默认情况下，系统会根据排序参数信息给出默认排序情况，自定义排序默认为升序。如果需要修改排序情况，您可以修改pre_order_by参数。其中排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”，其中ASC表示升序，DESC表示降序，多个排序参数描述以“英文分号”进行分隔。
    图7 排序参数设置
    对于pre_order_by的值，您可以进行如下修改：
    
    删掉某可选的排序参数，则此排序参数不再参与排序。
    
    修改自定义排序方式的排序参数为升序或降序方式，则此排序参数按照修改后的排序方式排序。
    pre_order_by的值，不支持进行如下修改，否则会修改不生效或导致调用报错。
    
    删掉某必选的排序参数，则此排序参数依然会正常参与排序，删除不生效。
    
    调整排序参数的前后顺序，则排序依然以配置方式API配置排序参数时的排序参数顺序或脚本/MyBatis方式API SQL中的排序参数顺序为准，调整不生效。
    
    修改升序或降序的排序参数为其他排序方式，则会调用失败，不允许修改。
  - （可选）“返回总条数”配置：在创建API时，如果已打开“返回总条数”开关，则当API对应的数据表数据量较大时，获取数据总条数将会比较耗时。此时，如果需要在调用时不计算并返回数据总条数，可以修改use_total_num参数。use_total_num参数用于控制是否计算并返回数据总条数，值为1返回数据总条数，值非1不返回数据总条数。
    图8 “返回总条数”参数配置
- Headers：将获取Token中保存的x-subject-token值填入X-Auth-Token的值中，并将Header参数的参数名和参数值填入其中。
  
  默认情况下，Postman工具会自动勾选Host并从URI中生成Host值，无需手动填写。
  
  图9 Headers
- Body：选择raw格式，使用大括号{}将“"Body参数名":Body参数值”形式的字符串包围在内，如本例中为“{"body":4}”。
  图10 Body
API请求配置完成后，单击“Send”发送请求到服务端，然后查看返回结果。返回"errCode":"DLM.0"即表示API调用成功。如果失败，则请根据报错信息进行修复。

如调用失败提示“Could not get any response”，可根据提示在Postman设置中关闭“SSL certificate verification”选项或关闭Proxy代理，然后再次尝试运行。

图11 调用API