跳到主要内容

API检索及调用

API 检索模块作为综合性工具，具备搜索、测试、订阅等核心功能，通过 API 目录树实现资源分类展示，帮助用户高效精准地管理和使用 API 资源；API 详情页面则针对单个 API，提供基本信息设置、后端及高级配置、参数定义、订阅信息查看等全方位配置与管理功能，便于用户深入精细地掌控 API。

一、功能介绍​

（一）API检索​

API 检索模块是一个综合性的 API 管理工具，涵盖搜索、测试、订阅等核心功能，同时通过 API 目录树实现资源分类展示，助力用户高效、精准地管理和使用 API 资源。

API门户-API检索-API检索

  • 搜索功能：用户能在 输入框中输入“API 名称、版本号、标签、目录状态、工作状态”关键字，借助 “搜索” 按钮快速查找目标 API 。“重置” 按钮可一键清除搜索条件，恢复 API 列表初始状态。

  • 批量订阅：“批量订阅” 按钮支持用户一次性勾选多个 API 进行统一订阅，大幅提升批量获取 API 使用权限的效率。

  • API 列表展示：以表格形式呈现丰富的 API 信息，包括名称、类型、版本号、标签、目录状态、工作状态、调用次数、订阅次数、创建时间等，便于用户全面掌握 API 的状态和使用情况。

  • 测试功能：每个 API 条目对应的 “测试” 按钮，可对 API 进行功能测试。当弹出 “测试成功” 提示，说明 API 当前运行正常，方便用户及时排查可用性。

    API门户-API检索-API检索-测试

  • 订阅功能：点击 “订阅” 按钮弹出订阅窗口，需选择关联应用系统，可输入不超 200 字的订阅描述，选择流控策略（如无限制等 ），并设置使用期限（无限期或指定截止日期 ），完成后提交即可订阅 API。

    API门户-API检索-API检索-订阅

  • API 目录树及目录检索：左侧的 API 目录树将 API 资源按类别或资源组进行分层展示，如 “默认资源组 - API 目录” 。用户可通过点击目录树节点快速筛选该类别下的 API ；同时，目录树上方的 “搜索资源组...” 输入框支持对目录树节点进行检索，输入关键字可快速定位到相关资源组或目录，让用户更便捷地在大量 API 资源中找到所需内容。

（二）API详情​

API 详情页面为用户提供了单个 API 全方位的配置与管理功能，涵盖基本信息设置、后端及高级配置、参数定义、订阅信息查看等，方便用户深入、精细地管理 API。

1）基本信息​

  • 类型与版本：可选择 API 类型（如 HTTP API ）及对应的 API 类型版本，明确 API 的技术类别和版本情况。
  • 名称与描述：显示或可编辑 API 名称，输入 API 描述，用于标识和介绍 API 功能用途。
  • 资源组归属：可选择 API 所属资源组，方便对 API 进行分类管理和资源定位。
  • 代理方式：可选择穿透代理等代理方式，决定 API 请求的代理处理模式。
  • 请求相关：能选择请求方法（如 ANY ），设置请求 URL，可勾选是否匹配全路径，界定 API 接收请求的方式和路径规则。
  • 优先级：可设置 API 的优先级，如默认等，用于在多个 API 处理时区分先后顺序。
  • 安全与有效期：可勾选 ssl 安全通道、WAF 防护等安全设置，保障 API 访问安全；能选择有效期为无限期或指定截止日期，控制 API 的使用期限。
API门户-API检索-API详情-基本信息

2）后端配置​

  • 后端服务类型选择：通过 “类型” 下拉菜单，可选择后端服务类型，如 “自定义服务” ，确定 API 后端对接的服务类别。
  • 安全与发布配置
    • ssl 安全通道：通过开关控制是否启用 ssl 安全通道，保障后端通信的安全性。
    • 是否使用灰度发布：开关可设置是否采用灰度发布，用于控制新功能逐步放量上线。
    • 是否使用注册中心：开关可决定是否借助注册中心来管理后端服务实例。
  • 后端路径设置：在 “后端路径” 输入框中，可定义 API 请求转发到后端服务的具体路径，如 “/get” 。
  • 超时时间设置：“超时时间” 输入框可设置 API 请求后端服务的超时时间（单位为秒 ），当前默认值为 30s，避免请求长时间等待。
  • 服务器配置
    • 服务器地址：“服务器配置” 输入框用于填写后端服务器地址 。
    • 端口：可设置后端服务器端口，当前默认值为 80 。
    • 权重：可设置服务器权重（当前默认值为 100 ），用于负载均衡场景下分配请求流量。
    • 添加与删除：点击 “+ 添加服务器” 可增加后端服务器配置；垃圾桶图标可删除对应服务器配置。
API门户-API检索-API详情-后端配置

3）高级配置​

  • 熔断配置

    • 最大连接数：限制 API 与后端服务建立的最大连接数量，当前默认值为 1024，防止连接过多耗尽资源 。

    • 最大待处理数：设定 API 等待处理的最大请求数量，默认值 1024 ，避免请求堆积。

    • 最大并行请求数：规定 API 同时处理的最大并行请求数量，默认 1024 ，保障系统处理能力稳定。

  • 负载均衡配置

    • 集群策略：可选择不同的集群策略（当前显示 “无” ），用于在多个后端服务器间分配请求，提升服务可用性和性能 。

    • 健康检查：能选择健康检查方式（当前显示 “无” ），定期检测后端服务器运行状态，及时剔除故障节点。

      API门户-API检索-API详情-高级配置-检查

      主动健康检查：配置主动健康检查时，每个固定时间去访问健康检查的接口，来确定upstream主机是否正常。健康检查定时会向健康检查接口发送请求，如果请求失败的次数，超过异常阈值所配置的值，则认为当前主机为不健康，并弹出该主机（不再向该主机转发任何请求）。过一段时间后，健康检查接口返回正常，正常的次数超过健康阈值所配置的值时，则认为该主机正常，之后加回该主机到负载均衡池。

      API门户-API检索-API详情-高级配置-主动检查

      被动健康检查：当请求的上游主机返回的响应码为5xx时，配置对应的失败次数。如果超过失败次数，将弹出主机。过一段时间后，再次请求该主机，如果主机正常将加回该主机。

      API门户-API检索-API详情-高级配置-被动检查

  • 功能开关配置

    • 重试：通过开关控制是否启用请求重试功能，失败时自动重新发送请求 。

      参数名称参数说明
      启用是否启用重试，启用后可选择重试条件，输入重试次数。
      重试条件支持多选：网关错误、5xx服务器错误、连接错误、409请求冲突错误、自定义重试策略l 网关错误：接收到502、503、504响应码时进行重试。l 5xx服务器错误：接收到上游主机的5xx响应码时进行重试。l 连接错误：出现连接错误（例如超时），包含在5xx内。l 409请求冲突错误：接收到可重试的4xx，当前仅支持409。l 自定义重试策略：自定义响应码重试策略。
      自定义错误码自定义响应码，多个使用“，”分隔；仅当“重试条件”中包含自定义重试策略时，才有该选项。
      重试次数最大重试次数，正整数。

    • 认证：开关决定是否开启 API 认证机制，保障访问安全 。

    • 客户端认证：控制是否对客户端进行身份验证，增强安全性 。

    • CORS 跨域访问：开关可设置是否允许跨域资源共享访问，满足不同网络环境调用需求 。

      API门户-API检索-API详情-高级配置-CORS
    参数名称参数说明
    启用是否启用CORS跨域访问。
    Access-Control-Allow-Orign指定允许的跨域请求的来源，即允许来自该域名下的请求访问该API；字符串，多个使用“，”分隔。该字段是必须的。值为请求时Origin字段的值；或一个*，表示接受任意域名的请求。*注意：*若“Access-Control-Allow-Credentials”允许发送Cookie，则当前参数不能设置为星号。
    Access-Control-Allow-Orign(正则表达式)指定允许的跨域请求的来源，即允许来自该域名下的请求访问该API；字符串，正则表达式，多个使用“，”分隔。
    Access-Control-Allow-Methods可选项GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS、TRACE
    Access-Control-Allow-Headers源域可以在CORS请求上指定的请求标头。
    Access-Control-Allow-Credentials是否允许发送Cookie。该字段可选。值为一个布尔值。默认情况下，Cookie不包括在CORS请求之中。该值只能设置为****T*****RUE*，即表示服务器明确许可，Cookie可以包含在请求中，一起发给服务器；如果服务器不需要浏览器发送Cookie，删除该字段即可。
    Access-Control-Expose-HeadersCORS响应中带的附加头域，给客户端提供额外的信息，不可出现空格。可以在CORS请求响应中发送并由浏览器向请求发出方公开的响应标头。
    Access-Control-Max-Age客户端可以缓存的CORS响应时间，以秒为单位。

    • 打印后端日志：开启后可记录后端处理日志，便于排查问题 。

      API门户-API检索-API详情-高级配置-开关配置

  • 流量控制规则

    • 流控规则：可选择流量控制规则（当前显示 “无限制” ），如限制单位时间内请求数量，防止流量过载 。

      API门户-API检索-API详情-高级配置-流控规则

  • 访问控制规则

    • 访问控制：可选择访问控制策略，如基于 IP、用户身份等限制访问，保障 API 安全 。

  • HTTP/REST API 数据处理规则

    • HTTP/REST API 数据处理规则：可选择针对 HTTP/REST 类型 API 的数据处理规则，如数据转换、过滤等，规范数据处理流程 。

4）请求参数定义​

API门户-API检索-API详情-请求参数
  • 路径选择：通过 “路径” 下拉菜单，可选择 API 请求对应的路径（如 any /http_demo_01 ），明确请求的目标地址。
  • 请求参数（Query）管理：以表格形式呈现查询参数相关信息，包括名称、是否必填、描述、默认值、示例等。虽当前暂无数据，但可添加参数，规范 URL 中查询字符串的格式和内容。
  • 请求参数（Header）管理：同样以表格展示头部参数信息，如名称、必填情况、描述等。可用于设置请求头内容，如认证信息、内容类型等，虽当前无数据，但支持后续添加配置。
  • 请求参数（Body）管理：提供文本编辑区域用于设置请求体内容，可手动输入或点击 “导入” 按钮导入相关数据，适用于 POST、PUT 等请求方法传递数据，支持JSON、XML和其他格式。
  • 请求示例展示：以多种编程语言（curl、Java、C#、PHP、Python ）展示 API 请求示例代码，帮助开发人员快速了解如何在不同语言环境下调用该 API 。

5）响应参数定义​

API门户-API检索-API详情-响应参数定义
  • 路径选择：通过 “路径” 下拉菜单，可选择 API 响应对应的路径（如 any /http_demo_01 ） ，明确响应关联的请求地址。
  • 响应参数（Header）管理：以表格形式展示响应头部参数，包括名称、是否必填、描述、示例等信息。虽当前暂无数据，但可添加配置，用于定义 API 响应头内容，如设置缓存控制、内容类型等响应头字段。
  • 响应参数（Body）管理：可选择响应体数据格式（当前默认 JSON ），通过文本编辑区域手动输入响应体内容，或点击 “导入” 按钮导入相关数据，规范 API 返回给调用方的数据结构和内容。
  • 返回示例展示
    • 正常返回示例：提供 API 正常调用时的响应数据示例，帮助调用方了解预期的返回格式和内容。
    • 异常返回示例：展示 API 调用出现异常情况时的返回数据示例，便于调用方提前做好异常处理准备。
  • 错误码定义
    • 导入描述文件：可通过导入描述文件的方式，批量定义错误码相关信息。
    • 错误码表格：以表格形式呈现错误码、信息、描述等内容，可进行添加、编辑等操作，用于规范 API 调用错误情况的反馈，方便调用方排查问题。

6）管理配置​

API门户-API检索-API详情-管理配置
  • 标签管理：可添加自定义标签，用于标识 API 的特性、用途或所属类别等，方便对 API 进行分类和检索。
  • 安全级别设置：提供 “公开”“内部”“秘密”“机密”“绝密” 等选项，用于定义 API 的安全等级，控制不同用户或应用对 API 的访问权限。
  • 应用系统关联：通过下拉菜单选择关联的应用系统名称，明确 API 所属的应用范畴，便于统一管理和权限分配。
  • 系统所属部门展示：显示 API 所属部门信息（如根机构 ），帮助了解 API 的组织归属。
  • 系统负责人与开发商信息：系统负责人和开发商名称字段虽显示自动获取，但可用于确认 API 的责任人和开发方信息，便于在需要时进行沟通和维护。

7）订阅信息​

API门户-API检索-API详情-订阅信息
  • 搜索与重置功能
    • 应用名称搜索：通过 “应用名称” 下拉菜单和输入框，可输入应用名称关键字，点击 “搜索” 按钮查找订阅该 API 的特定应用，方便快速定位相关应用信息。
    • 重置：点击 “重置” 按钮，可清空搜索条件，恢复订阅信息列表的初始显示状态。
  • 订阅信息展示：以表格形式呈现订阅该 API 的应用相关信息，包括应用 ID、应用名称、流控信息、授权有效期、订阅时间、审批时间、审批人、状态等。虽当前暂无数据，但这些字段用于全面记录和展示应用对 API 的订阅情况，便于管理和监控 API 的使用授权状态。

8）API版本​

API门户-API检索-API详情-版本
  • API 版本信息展示：以表格形式呈现同一 API 的不同版本相关信息，包括 API 名称、版本号、版本说明（当前无内容 ）、工作状态（如启用、停用 ）、测试状态（如测试失败、未测试 ）、审批状态（如变更待切换、变更审批通过 ），方便用户了解 API 各版本的运行和审核情况。
  • 关联信息展示：展示所属应用系统（如默认应用 ）、业务部门（如根机构 ），明确 API 的应用和组织归属。
  • 时间与人员信息展示：记录启动时间、更新时间、创建时间，以及更新人、创建人，便于追溯 API 版本的操作历史和责任主体。