文档首页/ 数据治理中心 DataArts Studio/ 用户指南/ 数据服务/ 开发数据服务API/ 编排API/ 配置入口API算子
更新时间：2024-07-30 GMT+08:00
查看PDF
分享

配置入口API算子

入口API算子是API工作流的入口，工作流发布后可通过调用入口API来调用API工作流。在入口API算子内需定义API工作流的名称、URL、参数协议、请求方式、审核人、安全认证以及请求参数。

表1 入口API算子

参数

说明

API名称

入口API名称即API工作流名称。

支持中文、英文、数字、下划线，且只能以英文或中文开头，3-64个字符。

请求Path

入口API访问路径即API工作流访问路径，例如：/getUserInfo。

请求Path即完整的URL中，域名之后、查询参数之前的部分，如图1中的“/blogs/xxxx”。
图1 统一资源定位符URL说明

在请求Path中，可以使用大括号{}标识路径中的参数作为通配符。如“/blogs/{blog_id}”表示/blogs后可以携带任何参数，例如“/blogs/188138”和“/blogs/0”均会匹配至/blogs/{blog_id}，由此API统一处理。

此外，相同域名下，不允许重复的请求路径出现。路径参数作为通配符时，名称不具备唯一性，例如“/blogs/{blog_id}”和“/blogs/{xxxx}”，会被视作相同路径。

参数协议

用于传输请求的协议，专享版支持HTTPS协议。

推荐选择HTTPS协议，HTTPS是在HTTP协议上进行了SSL或TLS加密校验的协议，能够有效验证身份以及保护数据完整性。相对的，访问HTTPS的API，需要配置相关的SSL证书或跳过SSL校验，否则将无法访问。

请求方式
HTTP请求方式，表示请求什么类型的操作，包含GET、POST等，遵循resultful风格。
  • GET：请求服务器返回指定资源，推荐使用GET请求。
  • POST：请求服务器新增资源或执行特殊操作。POST请求当前不支持body体，而是直接透传。

描述

对API进行简要描述。

标签

对API设置标签。用于标记当前API的属性，创建后可以通过标签快速检索定位API。单个API最多可设置20个标签。

审核人

审核人拥有API的审核权限。可单击“添加”，进入“审核中心 > 审核人管理”页面，新建审核人。

安全认证
创建API时，有如下三种安全认证方式可选。三种方式的区别在于认证方式和调用方法不同，推荐使用安全性更高的APP认证。
  • APP认证：将APP认证方式的API授权给应用后，使用应用的密钥对（AppKey和AppSecret）进行安全认证，支持通过SDK或API调用工具调用，安全级别高，推荐使用。
  • IAM认证：将IAM认证方式的API授权给当前账号或其他账号后，借助从IAM服务获取的用户Token进行安全认证。支持通过API调用工具调用，安全级别中等。
  • 无认证：不需要认证，所有用户均可访问，建议仅在测试接口时使用，不推荐正式使用。使用无认证方式时，无需鉴权认证信息，安全级别低，通过API调用工具或浏览器即可直接调用。

服务目录可见性
发布后，所选范围内的用户均可以在服务目录中看到此API。
  • 当前工作空间可见
  • 当前项目可见
  • 当前租户可见

访问日志

勾选，则此API的查询结果将会产生记录并被保留7天，可以在“运营管理 > 访问日志”处通过选择“请求日期”的方式查看对应日期的日志。

最低保留期限

API发布状态预留的最低期限，单位为小时，0表示不设限制。

如果需要停用/下线/解除授权，则停用/下线/解除授权时间必须选择在发布后的最低保留期限时间之后。选择时间后，停用/下线/解除授权会通知已授权用户。如果所有已授权用户均完成审核中心通知列表消息处理，或在应用中解绑与API的绑定关系，API就会停用/下线/解除授权；否则会以待停用/待下线/待解除授权状态，等待达到停用/下线/解除授权时间，再强制停用/下线/解除授权。

例如，最低保留期限设置为24小时，则此API发布后需要停用时，停用时间必须选择在发布24小时后，即发布第二天之后。如果期间内已授权用户已完成审核中心通知列表消息处理或解绑应用与API的绑定关系，则会直接停用；如果未完成，则会以待停用状态等待达到停用时间，强制停用。

入参定义

配置调用API工作流需要输入的参数。

入参定义主要由参数位置、参数类型、是否必填、允许空值以及默认值等组成。
  • 参数位置主要包括Query、Header、Path、Body四大类，另外还支持Static静态参数。
    • Query是位于URL后的查询参数内容，以“?”开始，通过“&”连接多个参数。
    • Header参数是位于请求消息头中的参数，常用于传递当前信息。例如host，token等。
    • Path是位于请求路径中的请求参数，如果定义了Path参数，则需要在请求Path中也添加此参数，作为请求Path的一部分。
    • Body是位于请求体内的参数，一般使用json格式表示。
    • Static是不随API调用者的传值变化的静态参数，仅当安全认证为APP认证方式时支持。Static参数数值由API授权时确定（如果授权时未配置参数值，则SDK调用时会使用API入参默认值，API工具调用时会导致缺少Static参数值的报错）。
  • 参数类型分为数值型Number与字符型String两大类。Number参数对应数据库中int、double、long等数值数据类型，String参数对应数据库中char、vachar、text等文本数据类型。
  • 是否必填、允许空值以及默认值。
    • 如果设定为必填，则API在访问时，必须传入指定参数。
    • 如果设定为非必填，则在API访问时，未传入的参数会使用默认值进行代替；如果未传入参数，也没有默认值，则允许空值时会使用null替换，不允许空值时忽略该参数条件。
说明：

入参定义中，参数大小限制如下：

  • Query+Path，URL最大32KB
  • Header，最大128KB
  • Body， 最大128KB
实际配置中，需要根据所设计的调用API工作流时请求参数情况来设置入参。例如，设计工作流在多张表中根据用户ID查询用户信息时，请求Path设置为：/getUserInfo。可按照如下不同场景来配置入参：
  • API调用时请求参数为用户id，需要通过工作流返回对应id的用户信息。
    1. 单击“添加”，参数名配置为id。
    2. 参数位置选择Query。
    3. 类型设置为Number。
    4. 是否必填选择必填。
    5. 默认值保持默认，无需填写。
  • API调用时请求参数为用户id1和用户id2，需要通过工作流返回id1-id2范围内的用户信息：
    1. 单击“添加”，参数名配置为id1。
    2. 参数位置选择Query。
    3. 类型设置为Number。
    4. 是否必填选择必填。
    5. 默认值保持默认，无需填写。
    6. 再次单击“添加”，按照id1参数的配置信息再配置id2。
父主题： 编排API

相关文档