文档首页/ 数据治理中心 DataArts Studio/ 用户指南/ 数据服务/ 开发数据服务API/ 创建API/ 配置方式生成API
更新时间：2024-10-18 GMT+08:00
查看PDF
分享

配置方式生成API

本节介绍如何通过配置方式生成API。

使用配置方式生成数据API简单且容易上手，您不需编写任何代码，通过产品界面进行勾选配置即可快速生成API。推荐对API功能的要求不高或者无代码开发经验的用户使用。

前提条件

已在“管理中心 > 数据连接”页面，完成数据源的配置。

约束与限制

API生成暂不支持Hive数据源的中文表和中文列场景。

新建API目录

API目录是按一定次序编排记录的API索引，是反映类别、指导使用、检索API的工具，帮助API开发者对API服务进行有效的分类和管理。

  1. 参考访问DataArts Studio实例控制台，登录DataArts Studio管理控制台。
  2. 在DataArts Studio控制台首页，选择对应工作空间的“数据服务”模块，进入数据服务页面。
  1. 在左侧导航栏选择服务版本（例如：专享版），进入总览页。
  2. 进入“开发API > > API目录”页面，单击。

    输入新建API目录名称，可新建API目录。

  3. 对于已成功创建的API目录，在API目录上右键单击，可选择编辑或删除API目录。

配置API基本信息

  1. 在DataArts Studio控制台首页，选择对应工作空间的“数据服务”模块，进入数据服务页面。
  1. 在左侧导航选择服务版本（例如：专享版），进入总览页。
  2. 进入“API管理”页面，单击“新建”，填写API基本信息。
    表1 API基本信息

    配置

    说明

    API名称

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

    API目录

    一个特定功能或场景的API集合，类似文件夹，指定当前API保存的位置，后续可以在指定的API目录中检索当前API。

    API目录是数据服务中API的最小组织单元。您可以选择新建API目录已创建的目录。

    请求Path

    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协议，HTTP安全性欠佳，可能会存在安全风险。

    • HTTP属于基础的网络传输协议，无状态、无连接、简单、快速、灵活、使用明文传输，在使用上较为便捷，但是安全性欠佳。
    • 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。
  3. 配置好API基本信息后，单击“下一步”，即可进入API取数逻辑页面。

配置取数逻辑

“取数方式”选择“配置方式”：
  1. 选择数据源、数据连接、数据库和数据表，获取到需要配置的表。

    数据服务仅支持部分数据源，详情请参见DataArts Studio支持的数据源。您需提前在DataArts Studio管理中心中配置好数据源，数据表支持表名搜索。

  2. 配置参数字段。

    选择好数据表之后，单击“参数设置”后的“添加”，添加参数页面自动列出这个表的所有字段，分别勾选需要设置为请求参数、返回参数和排序参数的字段，分别添加到请求参数、返回参数和排序参数列表当中。

    另外，专享版数据服务支持返回总条数，开启后可返回取值脚本执行结果数据的总条数。

    图2 添加参数

  3. 编辑请求参数信息。
    请求参数主要分为三部分，绑定参数、绑定字段、操作符。在请求参数列表中，需要设置绑定参数和操作符。
    • 绑定参数对外开放，选择为基本配置中定义的入参，是用户访问API时直接使用的参数。
    • 绑定字段对外不可见，是所选的数据表中的字段，为API调用时实际访问的内容。
    • 操作符则是用户访问API时，对绑定字段和绑定参数的处理方式。操作符左边为绑定字段，右边为绑定参数。当前支持的操作符及含义如下：
      表2 支持的操作符

      操作符

      描述

      =

      检查两个操作数的值是否相等。

      如果绑定字段和绑定参数相等则条件为真。

      <>

      检查两个操作数的值是否相等。

      如果绑定字段和绑定参数不相等则条件为真。

      >

      检查左操作数的值是否大于右操作数的值。

      如果绑定字段大于绑定参数，则条件为真。

      >=

      检查左操作数的值是否大于等于右操作数的值。

      如果绑定字段大于等于绑定参数，则条件为真。

      <

      检查左操作数的值是否小于右操作数的值。

      如果绑定字段小于绑定参数，则条件为真。

      <=

      检查左操作数的值是否小于等于右操作数的值。

      如果绑定字段小于等于绑定参数，则条件为真。

      %like%

      %like%表示忽略前后缀，进行字符匹配。

      如果绑定字段忽略前后缀，能匹配绑定参数，则条件为真。

      %like

      %like表示忽略前缀，进行字符匹配。

      如果绑定字段忽略前缀，能匹配绑定参数，则条件为真。

      like%

      like%表示忽略后缀，进行字符匹配。

      如果绑定字段忽略后缀，能匹配绑定参数，则条件为真。

      in

      in运算符用于把某个值与一系列指定列表的值进行比较。

      如果绑定字段能匹配多个绑定参数中的值，则条件为真。

      not in

      in运算符的对立面，用于把某个值与不在一系列指定列表的值进行比较。

      如果绑定字段无法匹配多个绑定参数中的值，则条件为真。

    值得注意的是，请求参数可以通过复制并设置操作符，实现多个输入的绑定参数条件匹配绑定字段。

    以图3为例，即为访问API时输入两个入参id1和id2，匹配id1和id2数值范围之间的x列值。

    图3 请求参数

  4. 编辑返回参数信息。

    返回参数主要分为三部分，参数名、绑定字段、参数类型。

    • 参数名对外开放，可自定义，是API返回时最终展示给用户的参数名称。
    • 绑定字段对外不可见，是所选的数据表中的字段，是API调用时实际返回的内容。
    • 参数类型则是API调用时，数据的呈现格式，分为数值型和字符型两类。
      图4 返回参数

  5. 编辑排序参数信息。

    排序参数主要分为四部分，参数名、字段名称、是否可选以及排序方式，支持多个排序参数。

    • 参数名可自定义，用于与字段名称关联。
    • 字段名称对外不可见，是所选的数据表中的字段，是API调用时实际访问的内容。
    • 是否可选决定了调用API时此排序参数是否必选，勾选则表示此参数可以不传，可以通过排序参数描述pre_order_by的值配置是否参与排序；不勾选则此参数必传，即使排序参数描述pre_order_by的值未配置此参数，依然会参与排序。
    • 排序方式表示了当前参数允许使用的排序形式，分为升序、降序以及自定义。自定义排序参数默认为升序排序，可通过排序参数描述pre_order_by的值进行调整；而升序或降序的排序参数，不支持通过pre_order_by的值调整排序方式，如果pre_order_by的值与此处设置排序方式不符，则会导致配置调试或调用报错。
    • 多个排序参数时，表示当第一个排序参数相等时，再逐一用后续排序参数去排序。参数的排序顺序不支持通过排序参数描述pre_order_by的值进行调整，如需调整可通过“参数设置”的“添加”进入添加参数界面，调整排序参数勾选顺序，可重新调整排序参数的顺序。
    图5 排序参数

  6. 单击“下一步”，进行API测试页面。

测试API

  1. 填写入参取值。
    如果单个参数需要传多个值时，写法如下：
    • 字符串：'a','b','c'
    • 数值：1,2
    • 字段：a,b,c
    图6 填写入参取值

  2. （可选）调整排序参数描述pre_order_by的值。

    系统根据5中已配置的所有排序参数已给出pre_order_by的默认值，自定义排序默认为升序。排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”，其中ASC表示升序，DESC表示降序，多个排序参数描述以“英文分号”进行分隔。勾选“是否传值”后，测试结果将按照pre_order_by的值排序。

    对于pre_order_by的值，您可以进行如下修改：
    • 删掉某可选的排序参数，则此排序参数不再参与排序。
    • 修改自定义排序方式的排序参数为升序或降序方式，则此排序参数按照修改后的排序方式排序。
    pre_order_by的值，不支持进行如下修改，否则会修改不生效或导致调用报错。
    • 删掉某必选的排序参数，则此排序参数依然会正常参与排序，删除不生效。
    • 调整排序参数的前后顺序，则排序依然以配置排序参数时的排序参数顺序为准。调整不生效。
    • 修改升序或降序的排序参数为其他排序方式，则会调用失败，不允许修改。
    图7 调整排序参数描述pre_order_by的值

  3. （可选）调整分页参数值。

    系统会对返回数据进行分页，pageSize表示分页后的页面大小，pageNum表示页码。API调试时默认按100的大小分页，返回第1页数据。

    API调试时，page_size (系统默认) 最大为100，当page_size值大于100时，默认查出的数据仍为100条。

    图8 调整分页参数值

  4. 完成API参数的配置并保存后，单击左下角的“开始测试”，可进入API测试环节。
    填写参数值，单击“开始测试”，即可在线发送API请求，在右侧可以看到API请求详情及返回内容。
    • 测试过程中，如果数据服务API查询及返回数据的总时长超过默认60秒，会报超时错误。
    • 如果测试失败，请查看错误提示并做相应的修改重新测试。

完成API测试之后，单击“确定”，即成功生成了一个数据API。

修改API

生成API后，如果您需要修改API内容，可在“开发API > API目录”或“开发API > API管理”处选择对应API，单击“编辑”按钮进行修改API的相关操作。

仅当API处于已创建、已驳回、已下线、已停用的情况下才能进行API修改。

父主题： 创建API