Skip to main content

开放API

通过API网关,以API的形式将后端服务(平台容器服务、传统主机服务)开放出来,提供给各方使用。也可关联数据库数据,发布成数据服务API。

发布至同一环境的API具有相同的访问地址,调用者将根据环境中定义的环境地址或域名访问开放的API服务。

API分组管理

tip

API分组管理

  • 一个API仅能属于一个API组,一个API组能绑定多个API。
  • API选定分组后,不支持修改。
  • 支持后端服务协议包括:HTTP\HTTPS\Dubbo。
  • 创建API分组

    后端服务为HTTP/HTTPS时,操作步骤如下所示。

    (1) 在控制台上部导航栏中,单击[开放API/API分组],进入API分组页面。

    (2) 单击“创建API分组”, 进入“创建分组”页面,填写如下信息。

    info

  • API组名称:可由1-63个中文字符、英文字母、数字或中划线“-”组成。
  • 描述:自定义对分组的介绍。
  • API分组自定义logo:此处图片用于API组中的API发布至市场中显示图标,建议大小80px*80px或140px*140px。
  • 访问协议:选择后端服务协议,也就是与后端服务通信协议。支持HTTP\HTTPS\Dubbo,若选择HTTPS则后端服务必须有SSL证书。
  • 后端超时:即API网关调用API后端服务的最大响应时间,如果响应时间超过该值,API网关会放弃请求后端服务,并给用户返回相应的错误信息。取值范围1-600000ms,默认是60000ms。
  • 超时重试:默认关闭,关闭代表重试次数为0次;开启后可从选择1-5次中选择一个重试次数,开启后默认5次。
  • 后端服务源:网关后端业务系统的服务,可选的类型有代理或者负载均衡,选择负载均衡时,支持添加多个服务。
  • 灰度策略:当选择的后端服务源为负载均衡时,支持添加多个服务。调度策略支持启用灰度策略,若未启用灰度策略,多个后端服务按照随机方式进行调度;灰度发布的方式有两种,具体的说明如下所示。
  • 按权重:为绑定的后端服务分配相应的权重比例,主服务的权重缺省为100%。
  • 按内容:根据配置的key/value进行匹配。Key的位置支持ip、query、header、cookie,匹配规则的请求将分发到相应的服务中,不匹配规则的请求将分发到该监听器绑定的其他服务中(按原有权重比例)。
  • 后端服务类型:支持关联已有后端服务、自定义后端服务两种。
  • 后端服务:选择后端服务绑定在API分组上,需要注意的是一个k8s的service资源只能被一个API分组关联。
  • (3) 完成分组信息填写后,单击“确定”按钮,创建API分组,创建分组成功后,在“API分组”页面的列表中显示新创建的API分组,用户可查看分组列表。

    后端服务为Dubbo时,操作步骤如下所示。

    (1) 访问协议选择dubbo后,需要填写注册中心地址、服务名称、接口包。

    note

  • 注册中心:注册地址必须以host:port的URL格式。仅支持接入zookeeper注册中心的dubbo服务。当zookeeper是高可用时,需要将其所有地址都进行填写,多个用英文逗号隔开。并需要进行测试链接。
  • 接口包:支持.jar,最大100M,上传新接口包将覆盖选择的服务中定义的接口文件。
  • (2) 完成分组信息填写后,单击“确定”按钮,创建API分组,创建分组成功后,在“API分组”页面的列表中显示新创建的API分组。

    (3) API分组列表中,点击分组名称,跳转其详情页面,进入Dubbo Proxy,可查看其CPU使用率、内存使用量、网络吞吐量。

    • 筛选实例进行CPU使用率、内存使用量、网络吞吐量的查看
    • 支持水平扩展,调整实例数量,保存后系统将调整实例数量至设置预期。

    1643017742003.png

    添加域名&证书

    API组中添加的域名用于API组中的API 发布时选择使用,发布成功后,调用者可通过环境地址或域名访问开放的API服务。

    入口:API分组列表的操作中选择“添加域名&证书”,点击跳转API分组详情页面的“绑定域名”tab下,点击按钮“添加域名&证书”。进入如下所示的配置页面。

    note

  • 请确认要绑定的域名已解析到API组中相应API发布环境的IP,否则无法通过域名访问API。
  • 若添加证书,API分组中的HTTPS请求协议的API发布时可选择该域名/证书。
  • 证书等需要申请,如果只是用来测试使用可以申请一些免费证书,在此附上申请链接:https://csr.chinassl.net/free-ssl.html
  • 后端服务健康检查

    在实际的生产环境中,如果要使开发者提供的应用程序没有任何Bug,并且一直保持运行正常,这几乎是不可能完成的任务。

    那么,对运行的应用程序进行周期性的健康检查就是不可或缺的了,在某些特殊的场景下,例如一个程序发生“死锁”,Docker认为其容器进程一直在运行,会认为服务是健康的,但是从应用程序而言,该状态下的容器将不会正常响应用户的业务请求,因此需要业务级的健康检查。

    首先需要提供一个健康检查地址,按设定的探测策略主动去监测服务的状态;然后通过开启or关闭来控制是否进行主动探测。策略描述如下所示。

    • 健康探测策略:满足设定策略后,则标记服务状态为健康,可自定义成功返回码,默认值200,302。

    • 不健康探测策略:满足设定策略后,则标记服务状态为不健康。提供两种策略。

      a. HTTP(S)请求连续失败超过X次,则标记为不健康,可自定义失败返回码,默认值404、429、501、502、503、504、505。 b. HTTP(S)请求连续超时超过X次,则标记为不健康(超时时间即指API分组创建时指定的后端超时时间)。 c. 策略开启后,在API分组列表中会展示后端服务的健康状态,健康or不健康。

    健康计数器阈值策略所示。

    • 如果返回的状态码是配置为“健康”的状态码,它将为目标增加“成功”计数器,并清除其所有其他计数器。
    • 如果超时,它将增加目标的“超时”计数器,并清除“成功”计数器;
    • 如果返回的状态码是配置为“不健康”的状态码,它将为目标增加“HTTP失败”计数器,并清除“成功”计数器。
    • 如果“HTTP失败”或“超时”计数器中的任何一个达到其配置的阈值,则目标将被标记为不正常。
    • 如果“成功”计数器达到其配置的阈值,则目标将被标记为正常。

    查看API分组详情

    进入API分组列表,点击API分组名称跳转到分组详情页面。

    API分组基本信息

    顶部显示API分组基本信息,包括API分组名称、访问协议、后端服务源、后端超时时间、创建时间、描述,其中描述支持编辑。

    API列表:统计分组内API个数,展示每个API的名称、访问控制方式、协议、请求方法、路径、创建时间、操作(操作功能同API管理中各功能)。

    后端服务

    后端服务tab展示关联的后端服务地址、创建时间、操作(删除),API分组详情/API列表页签页面如下图所示。

    test

    后端服务源为代理类型,仅支持添加一个后端服务。

    编辑API分组

    操作步骤如下:

    (1) 在API组列表找到需要编辑的API组,在右侧的操作列中点击<编辑>按钮。

    (2) 在编辑API组对话框中编辑信息,API组名称不可修改。

    (3) 访问协议为dubbo的,不支持修改“访问协议”和“后端服务相关内容”。

    (4) 编辑完成后,点击<保存>按钮。

    删除API分组

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击开放API > API 分组,进入API分组页面。

    (2) 页面列表右侧操作列中选择需要删除的API分组,点击<删除>按钮。

    (3) 在弹出的确认框中点击<确定>按钮,即可删除。

    note

    若API分组中存在API,则需要将存在的API删除后,方可成功删除API分组。

    API管理

    创建API

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API管理页面。

    (2) 单击“创建API”,如图所示。填写如下信息。

    info

    API名称(必填)支持汉字,英文,数字,下划线,且只能以英文和汉字开头,3-64字符。

    描述(选填)支持1-128个中英文,用于描述作用、适用范围等信息。

    选择模式。

    路由模式:用户配置对应的路由访问当前的API。

    • 请求方式:自定义配置API请求的方式,支持标准的HTTP/HTTPS Method,可选择GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS等方式。
    • 网关路径:Path指相对于服务host,API的请求路径,用户可自定义配置网关对外暴露的API路径。
    • strip_path:支持勾选/取消勾选,配置转发请求时是否去掉访问路径。如果是Dubbo协议的API分组,此处默认勾选,置灰不可取消勾选。
    • API文档:支持富文本编写介绍API。
    test

    映射模式:用户自定义暴露当前API的访问方式。

    • 请求方式:自定义配置API请求的方式,支持标准的HTTP/HTTPS Method,可选择GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS等方式。
    • 访问路径:用户可自定义配置网关对外暴露的API路径。
    • strip_path:支持勾选/取消勾选,配置转发请求时是否去掉访问路径。
    • API文档:支持富文本编写介绍API。
    • 入参请求模式:表示API请求参数和后端服务接口真实参数的映射模式,支持三种,单选。
    info

  • 入参映射(过滤未知参数):支持设置参数映射,请求参数位置支持Query,Header,Body,网关会过滤未配置的参数(即请求入参信息中的没有的参数),不将其传给后端。
  • 入参映射(透传未知参数):支持设置参数映射,请求参数位置支持Query,Header,Body,网关除配置的请求参数外,不对其他位置的请求参数进行映射与校验,用户参数会透明传递给后端。

    入参透传:不支持设置参数映射,客户端传给网关的参数都会被网关透传给后端。

    选择“入参透传”后,下方“请求ContentType”、“请求入参信息”隐藏不显示;选择其他两项,则显示。请求ContentType:支持以下三种,单选。

    info

  • application/x-www-form-urlencoded:“入参位置”支持header、query。
  • multipart/form-data:“入参位置”支持选择header、query、body
  • application/json:“入参位置”支持header、query。
    • 请求入参信息:设置请求参数与后端服务真实参数的映射关系,包括Header参数、Query参数、Body参数,参数名称保证唯一,可支持多条。
    • 后端协议:API分组已配置的后端协议。
    • 后端服务地址:默认读出显示此API分组对应的后端服务;当是负载均衡时,显示全部服务。
    • 后端请求路径:路径是用户的API服务在后端服务器上的实际请求路径。若用户后端Path需要接收动态参数,则需要声明调用者需传入参数的具体位置和参数名,即声明映射关系。若有path参数,包含在[]中,例如/getUserInfo/[userId]
    • 后端请求方法:支持标准的HTTP/HTTPS Method,可选择PUT、GET、POST、DELETE、PATCH、HEAD、OPTIONS。
    • 后端参数配置:声明前后端API映射关系,不支持手动增加、删除。
    • 支持前后请求方法转换;方法转换暂无限制。
    • 支持前后参数位置不同的转换:后端参数位置支持header、query、body、path。
    • 常量参数配置:常支持header、query,不需要用户传入,但是用户后端始终需要接收的一个常量参数,对用户不可见。
    • 成功响应示例:定义正确响应后的显示示例。
    • 失败响应示例:定义未正确响应后的显示示例。

    (3) 所属API组(必选)选择一个分组,支持在此处新建API组,点击后打开新的标签页,支持刷新;每一个API都归属且仅归属一个API组。

    (4) 协议(必选)该协议为网关对外暴露的协议,包含http、https两种协议,API发布的环境需添加了HTTPS证书,方可支持发布HTTPS协议的API至该环境中。创建API页面如下图所示。

    test

    (5) 当所属API组选择的是Dubbo协议,访问路径下拉选择接口名、方法名。

    (6) 完成信息填写后,单击“确定”按钮,创建API,创建成功后,在“API管理”页面的列表中显示新创建的API。

    导入API

    Swagger是一种用于描述API定义的规范,被广泛应用于定义和描述后端服务的API。API网关支持导入Swagger 2.0的文件来创建API,并支持批量导入。

    入口:API分组详情页面中“API列表”页签,点击“导入API”按钮。操作步骤如下:

    (1) 进入API管理页面,点击导入API,弹出弹框。

    STEP

    a. 选择API分组,下拉列表展示已创建的API分组。不支持Dubbo协议的分组。

    b. 选择遇到API名称相同时的处理方式:跳过or覆盖。

    c. 选择模式:路由模式OR映射模式,Dubbo类型的API不能选择映射模式。

    d. 选择文本格式:YAML OR JSON。

    e.在swagger输入框中黏贴swagger信息(需符合swagger规范)或者上传文件(单次最多导入10个API,不能超过100KB;上传文件后会覆盖编辑器中的内容)。

    f. 点击“下载API示例”,即yaml格式或json格式的示例模板显示在YAML中。

    (2) 点击“导入”,先进行预检。

    STEP

    a. 预检是对导入格式,API访问路径唯一性等做检查。

    b. 预检成功,直接导入,导入完成后,右上角提示“导入成功”。

    c. 预检失败,提示“预检失败,内容格式不符合swagger规范,请结合示例进行检查后再重新导入!”或者“预检失败,以下API的访问路径(paths)已存在或重复,请检查后重新导入!”。

    (3) 查看导入成功的API,在其详情页面,增加“API文档”tab显示接口的请求header信息、请求body、响应结果(code、message)。

    STEP

    a. 不支持API文档编辑。

    b. 导入后,仅支持原有可编辑的项(即手动创建API后可编辑的选项)。

    (4) 导入的API不会自动发布到任何环境,需要您手动发布。

    (5) 应用已被授权API成功,查看“API文档”。

    STEP

    a. 进入“应用管理”页面,进入某应用详情页面,在“订购的API”tab中,点击“查看API文档”。

    b. 右侧弹出面板中展示API文档信息。

    tip

    Swagger文档必填对象说明

  • openapi/swagger:OpenAPI规范的版本号
  • Info:API的元数据。
  • Paths:API的请求路径与操作
  • Schemes:API服务支持协议
  • OpenAPI schemes数据和API网关对象的映射关系如下表所示。

    OpenAPI对象数据类型API网关对象备注
    schemesArray协议导入数据无此字段时,默认取值为[http,https]

    OpenAPI info数据和API网关对象的映射关系如下表所示。

    OpenAPI对象数据类型API网关对象
    info.titleString未使用
    info.descriptionStringAPI描述
    info.versionString未使用

    OpenAPI paths数据和API网关对象的映射关系如下表所示。

    OpenAPI对象数据类型API网关对象备注
    paths.pathObject访问路径path表示所有实际路径值
    paths.path.operationIdStringAPI名称(必填)多个Method operationId不同时,默认选择第一个
    paths.path.methodObject请求方法method这里代表所有 "get"、"post"、"put"等

    其它说明

    API网关对象说明
    访问控制无认证

    编辑API

    操作步骤如下:

    (1) 在API列表找到需要编辑的API,在右侧的操作列中下拉点击编辑按钮。

    (2) 在编辑API对话框中编辑信息,所属API组不可修改。

    (3) 编辑完成后,点击<保存>按钮。

    查看API详情

    操作步骤如下:

    (1) 在API列表找到需要查看的API,点击API名称进入API详情查看。

    (2) API详情页面可查看API的详细信息、监控信息、发布历史、授权应用、流量控制、调试API、调用日志、绑定插件。其中调试API、调用日志、绑定插件三个功能,待API发布后才支持使用。

    查看发布历史

    操作步骤如下:

    (1) API管理页面找到需要查看发布历史的API,点击“API名称”进入API详情页面。

    (2) 切换至“发布历史”页签,查看发布历史。

    (3) 操作列,单击“查看版本”,右侧面板弹出此版本详细信息对话框,查看发布的API 详细参数。

    (4) 若需要设置之前版本为当前版本,则在版本所在行,单击“切换至此版本”,弹出“切换至此版本”对话框。

    (5) 单击<确定>,完成版本的切换。此时版本号旁边显示“当前版本”,说明设置成功。

    (6) 切换版本后,API调用者调用此API时,API参数为“当前版本”设置的参数,不是最后一次编辑保存的API参数。

    调用监控

    API详情页面会统计一定时间范围API的调用数据,如:请求次数、出错次数、数据流量、调用延时、网关服务调用延时、源服务调用延时等统计。

    丰富的监控信息,通过最大延时观察在服务器压力最大或者网络波动时服务的处理能力;通过平均延时能说明服务的平均能力。

    操作步骤如下所示。

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API管理页面。

    (2) 通过以下任意一种方法,进入“监控信息”页面。

    STEP

    a. 在API列表找到需要查看的API,右侧操作列中下拉点击“管理”按钮。

    b. 点击API名称进入API详情页面,切换至“监控信息”页签 。

    调试API

    当API发布到某一环境,才能使用调试API功能。API创建后需要验证服务是否正常,通过调试功能,可以添加HTTP头部参数与body体参数,调试API接口。

    若API的访问控制方式为“需要认证”的方式,需要提供该API授权应用的对应试认证类型的凭证,才可正常调试API。

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API管理页面。

    (2) 通过以下任意一种方法,进入“发布API”页面。

    STEP

    a. 在API列表找到需要调试的API,右侧操作列中下拉点击“调试API”。

    b. 点击API名称进入API详情页面,切换至调试API页签。

    (3) 添加请求参数后,单击“发送请求”。右侧返回结果回显区域打印API调用的响应结果。调试API页面如下图所示。

    1643080067352.png

    note

  • 调试时支持默认显示任意环境URL,可选择环境,URL支持自定义。
  • 需要注意的是API调试的地址:点击调试API页签,页面会自动加载API的地址,默认地址为API网关的地址+API详情中的访问路径。
  • 发布API

    当您完成API的创建后,您可以将 API 发布到管理员自定义的环境中如测试,或者API市场。API只有在发布到环境后,才支持被调用。

    发布后,支持查看API发布历史(如版本、发布说明、发布时间和发布环境),并支持回滚到不同的API历史版本;也可以将发布到环境中的API下线。操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放AP/API管理],进入API管理页面。

    (2) 通过以下任意一种方法,进入“发布API”页面。

    STEP

    a. 在API列表找到需要调试的API,右侧操作列中下拉点击“发布API”。

    b. 点击API名称进入API详情页面,切换至“发布历史”页并点击“发布”按钮。

    (3) 选择API需要发布到的环境,并填写发布备注说明。

    (4) 选择域名&证书,此处为该API所属API组中添加的证书。

    (5) 单击“发布”,完成API发布。

    note

  • 当您要发布某个API时,如果该API在测试或者线上已经有版本在运行,您的此次发布将使测试或者线上的该API被覆盖,实时生效。但是历史版本及定义会有记录,您可以快速回滚。
  • 已发布的API,在修改信息后,需要重新发布才能将修改后的信息同步到环境中。
  • 上架到市场

    API创建完成后需要发布到对应的环境后,用户方可上架至云原生应用市场。

    tip

    前提条件

  • 服务商已具备容器云平台登录账号,且账号可正常使用。
  • 容器云平台平台已经上传对应的介质文件。
  • 服务商已注册时速云官网,且账号可正常使用。
  • (1) 服务商登录容器云平台,选择对应的集群项目,点击[API网关/开放API/API管理]菜单项,进入API列表页面。

    (2) 找到要上架到云原生应用市场的API,如果要上架的API尚未发布到环境,需要先执行发布操作,单击API操作列的<发布API>按钮,进入API发布配置页面,如下图所示。

    test

    API发布配置参数说明如下所示。

    • 选择发布环境:配置当前API要发布到API项目环境或者云原生应用市场(即云市场),发布到API项目环境的API不支持发布到云原生应用市场。
    • 填写发布备注:配置当前API发布的备注说明,帮助服务商更好管理API。
    • 选择域名&证书:配置当前API所属分组的域名&证书。

    (3) 发布完成后,点击[API网关/开放API/API管理]菜单项,找到已经发布到云市场环境的API,点击API名称链接,进入API详情页面。

    (4) 切换至“绑定插件”页面,根据插件类型,有以下两种配置情况。

    • 非JWT、Oauth2、HMAC、Basic Auth类插件。
    • 用户可按需绑定访问控制类型插件,例如:JWT、Oauth2、HMAC、Basic Auth等类型的插件。

    (5) 插件绑定完成后,单击<确定>按钮,插件绑定成功,单击<返回>按钮,返回API列表页面。

    (6) 找到已经绑定插件的API,单击操作列的<上架云市场>按钮,进入[云原生应用市场/资产管理]页面。

    (7) 在资产列表页面,找到要上架的API。单击<定义API>按钮,进入API配置页面。

    • 租户项目集群:API环境是基于集群-项目所做的配置,因此需要选择上架API所在的项目集群。
    • 选择API:选择要上架的API,此处列出所选项目集群下所有的API,支持搜索。
    • API访问前缀:配置访问API前缀,配置的前缀和域名组合成可访问的URL地址供用户访问。

    (8) API上架信息配置完成后,单击<确定>按钮,保存当前资产。

    tip

    前提条件

  • 已上架至云市场环境的访问控制类型插件不可解绑,下架后方可解绑。
  • API类型资产仅支持上架一次,不允许多次上架。
  • API分组变更后,不能直接生效,需要发布到相应环境后再环境中,并且重新上架到市场环境方可生效。
    • 资产创建成功后,用户可单击<申请上架>按钮,申请上架当前资产,操作页面如下图所示。
    • 资产创建成功后,单击<编辑>按钮,用户可编辑当前未上架的API资产。
    test

    从市场下架

    API类型的资产用户可以根据需要下架对应的资产。

    tip

    前提条件

  • 服务商已具备TCE PaaS登录账号,且账号可正常使用。
  • API类型资产版本状态是已上架且审批状态上架通过或者资产版本已上架且审批状态是下架未通过。
  • 服务商已注册时速云官网,且账号可正常使用。
  • 服务商申请资产下架的操作步骤如下所示。

    (1) 服务商登录时速云官网 https://www.tenxcloud.com/, 进入官网首页,点击“云市场”菜单项,进入“云市场”首页;或者已登录容器云平台的用户,点击导航的<云原生应用市场>按钮,进入云市场首页。

    (2) 切换至[云原生应用市场/资产管理]菜单项,找到要申请下架的API资产。

    (3) 点击资产名称链接,进入资产详情页面,找到对应版本的资产,单击<申请下架>按钮,进入资产下架确认页面。

    (4) 确认下架后,配置对应的下架原因,单击<确定>按钮,提交对应的资产下架申请。

    (5) 管理员登录容器云平台,找到要审批的资产下架申请,点击<通过/拒绝>按钮,资产下架申请审批成功。

    如果服务商想在容器云平台下线该类型资产,操作步骤如下所示。

    (1) 服务商登录容器云平台,选择对应的集群项目,点击[API网关/开放API/API管理]菜单项,进入API列表页面。

    (2) 找到要下线的API,该API已经从云原生应用市场下架,单击API操作列的<下线>按钮,进入API下线配置页面,如下图所示。

    test

    (2) 下线API信息确认完成后,单击<确定>按钮,API下线成功。

    授权应用

    此处的授权指的是主动授权某个API给应用,让指定的应用能够调用API。仅能授权给该API已经发布的环境,如果没有发布,则不能授权应用。操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API管理页面。

    (2) 通过以下任意一种方法,进入“授权应用”弹框。

    STEP

    a.在API列表找到需要授权的API,右侧操作列中下拉点击“授权应用”。

    b. 点击API名称进入API详情页面,切换至“授权应用”页签,点击“添加授权”按钮。

    (3) 选择API授权环境,查询并勾选应用后,单击<确定>。

    (4) 授权成功后,可以在[API详情/授权应用]中查看已授权的应用。在相应的应用详情中也可查看到该API。如需解除授权,在“API详情/授权应用”页签中,找到相应的应用,点击右侧的<解除授权>按钮,在弹出框中确定即可。

    下线API

    已发布的API因为需要暂停对外提供服务时,可以暂时将API从相关环境中下线。但是在某环境下线后将导致此API在指定的环境无法被访问,可能会影响相当一部分应用和用户,确保已经告知用户。

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API管理页面。

    (2) 找到需要下线的API,右侧操作列中下拉点击“下线API”按钮。

    (3) 在弹出框中选择选择要下线的环境,点击<确定>按钮下线。

    调用日志

    • 默认关闭日志功能。
    • 开启日志相关功能后,系统支持为某一发布环境开启调用日志采集,开启后可收集API的调用日志(仅显示开启后产生的日志)。

    调用日志查看

    前提条件:若在日志服务中查询API调用日志,需为每个API开启“调用日志”采集,进入每个API的详情页面,点击“调用日志”,分发布环境进行开启/关闭操作。

    平台支持API调用日志的原始查询。进入[应用监控/日志服务/查询分析]页面,在“原始日志查询”页签中,选择网关环境安装所在的项目集群,标准日志中搜索服务。例安装项目环境“test-env”,选择其 test-env应用下的 test-env-utvah-kong-proxy服务,查询历史调用日志。

    1643081245993.png

    平台支持API调用日志的结构化查询分析,需选择“结构化查询分析”页签,选择对应日志组、日志对象查询分析。前提需要为网关开启结构化处理,步骤如下所示。

    (1) 用户登录容器云平台,选择[应用监控/日志服务/日志管理]菜单,进入列表页面。

    (2) 添加日志组,添加日志对象,选择日志对象类型“API网关”,选择发布环境。

    (4) 确定后,即对此发布环境中采集的日志进行结构化处理。

    (5) 进入[应用监控/日志服务/查询分析]页面,在“结构化查询分析”页签中进行日志查询分析。

    (6) 结构化查询分析页面小问号帮助文档中,提供API网关常用查询分析语句示例(需要在API网关侧为发布环境开启调用日志,并在[日志组管理]中创建对应发布环境的日志对象,才可进行查询分析功能)帮助用户对业务日志进行分析查询。

    绑定插件

    此标签页中可查看API绑定的插件,显示插件名称、插件类型、配置内容、绑定环境、描述,并支持解绑。

    已经上架至市场的访问控制插件不允许解绑,且访问控制插件只能绑定一个,普通插件同一个类型的允许绑定一个,不同类型的可以绑定多个。

    点击<解绑>,二次提示是否确认解绑。

    删除API

    若API已经发布至某个环境,需要先从发布的环境中下线该API,方可删除,删除API会导致调用该API的用户无法继续使用,需谨慎操作。操作步骤如下。

    (1) 在控制台上部导航栏中,单击[开放API/API管理],进入API分组页面。

    (2) 页面列表选择需要删除的API组右侧操作列中下拉,点击<删除>按钮。

    (3) 在弹出的确认框中点击<确定>按钮,即可删除。

    WebSocket请求

    Ngnix原生支持 websocket,基于Nginx的Kong对websocket也支持,若服务类型是websocket,可以按照正常的API发布进行发布。

    在调用端的示例如下:谷歌浏览器中通过js请求测试:也可以通过在线测试工具进行测试,例如:http://ws.douqq.com/。F12可查看开发者工具页面。如下图所示。

    1643081402528.png

    流量控制

    流量控制可限制单位时间内API的被调用次数,从而保护后端服务。流量控制策略和API分别是独立管理的,操作两者绑定后,流控策略才会对已绑定的API起作用。

    同一个环境中一个API只能被一个流控策略绑定,一个流控策略可以绑定多个API。

    创建流控策略

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/流量控制],进入流控列表页面。

    (2) 单击“创建流控策略”,进入流控策略配置页面,填写如下信息。

    • 策略名称:可由1-63个中文字符、英文字母、数字或中划线“-”组成。
    • 描述:自定义对流控策略的介绍,支持1-128个汉字或字符。
    • 默认开启:若开启,添加成功后默认启用此规则;若关闭,添加成功后默认停用此规则。
    • 流控类型:支持三种流控策略,可以选择作用在API、凭证、应用上。
    • 请求计数限流:支持每1秒、每1分钟、每1小时、每1天四个维度设置请求次数。
    note

  • 如果作用在应用上,若应用创建了多个凭证,那多个凭证去调用API,总调用数不得超过流控设置阈值。
  • 如果作用在凭证上,若应用创建了多个凭证,单个凭证去调用API,不得超过流控设置阈值。基于凭证的流控策略,点击绑定API时,会过滤掉“无认证”的API
  • 如果作用在API上,若有多个应用订购此API,多个应用去调用API,总调用数不得超过流控设置阈值
  • (3) 完成信息填写后,单击“确定”按钮,创建成功,即可绑定相关API到该策略,以实现流量控制。

    test

    绑定API

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/流量控制],进入流控页面。

    (2) 通过以下任意一种方法,进入“绑定API”页面。

    STEP

    a.在待绑定的插件所在行,右侧操作列中下拉点击“绑定API”。

    b.点击插件名称进入插件详情页面,在“绑定的API列表”页签中点击“绑定API”按钮。

    (3) 选择“发布环境”、“API分组”、以及“API名称”,筛选所需的API。勾选API,单击“绑定”,完成API绑定策略。

    note

  • 若API上已经绑定了一个流控策略,选择该API则会被本策略覆盖。
  • 另外,在流控策略绑定API后,如果API不需要调用此策略,单击“解除”,解除绑定;或在相应的API详情页面的流量控制页签中解绑也可以。
  • 无认证的API不支持绑定基于应用或凭证的流控策略。
  • 编辑流控策略

    编辑后,对已绑定环境的API生效的流量控制即刻生效。操作步骤如下所示。

    (1) 在流量控制列表页面找到需要编辑的策略,在右侧的操作列中点击<编辑>按钮。

    (2) 在编辑API组对话框中编辑信息,API组名称不可修改。

    (3) 编辑完成后,点击<保存>按钮。

    删除流控策略

    当已经创建的流控策略无任何绑定的API ,可以将此流控策略删除。若存在绑定的API,需先为API解绑,再操作删除流控。操作步骤如下所示。

    (1) 在控制台上部导航栏中,单击[开放API/流量控制],进入流控页面。

    (2) 页面列表选择需要删除的流控策略右侧操作列中下拉,点击<删除>按钮。

    (3) 在弹出的确认框中点击<确定>按钮,即可删除。

    插件管理

    目前API网关支持下列7种插件:

    • OAuth 2访问控制插件
    • HMAC Auth插件
    • 降级插件(Request Termination)
    • 跨域插件(Cors)
    • IP访问控制
    • 报文大小限制
    • 爬虫插件

    插件管理页面存在四个默认的访问控制插件显示在页面中,分别是Oauth2、HMAC Auth、JWT、 Basic Auth插件。不支持删除和编辑。

    创建插件

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/插件管理],进入插件管理页面。

    (2) 单击“创建插件”,进入“创建”页面,填写如下信息。

    • 插件名称:由1-63个中文字符、英文字母、数字或中划线“-”组成。
    • 插件类型:选择以上4种插件。
    • 描述:自定义对不同插件的介绍,支持1-128个汉字或字符。
    • 配置内容:根据不同插件类型填写配置内容。

    OAuth2访问控制插件

    OAuth2访问控制插件创建页面如下图所示。

    test

    降级插件(Request Termination)

    临时阻止外界通过某API访问我们的服务,并向外界返回自定义信息。

    • 支持开启/关闭功能。
    • 配置内容默认显示code、body为503,“休息一下,马上回来。”
    • 支持按API业务内容自定义code、body。

    跨域插件(Cors)

    跨域是指从一个域名去请求另一个域名的资源,严格来说,只要域名,协议,端口任何一个不同,就视为跨域。

    出于安全原因,浏览器限制从页面脚本内发起的跨域请求,有些浏览器不会限制跨域请求的发起,但是会将结果拦截了。这意味着使用这些API的Web应用程序只能加载同一个域下的资源,除非使用CORS机制(Cross-Origin Resource Sharing跨源资源共享)获取目标服务器的授权来解决这个问题。CORS跨站资源共享,它是跨域的官方解决方案。原理是使用自定义的HTTP头部让浏览器与服务器进行沟通,从而决定请求或响应是应该成功还是失败;支持开启/关闭功能。

    配置选项介绍如下所示。

    • Access-Control-Allow-Origin头允许的域列表(必填项),使用 * 代表允许所有域,值可以是普通值;也可以是正则表达式,使用逗号隔开。
    • Access-Control-Allow-Headers头的值,允许的请求头,用逗号隔开。
    • Access-Control-Expose-Headers的值,允许暴露给XMLHTTPRequest对象的头,用逗号隔开。如果不指定,不暴露自定义的头。
    • 默认不选中,支持多选,Access-Control-Allow-Methods头的值,默认为GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS, TRACE。
    • 是否发送Access-Control-Allow-Credentials请求头,默认不勾选。

    IP访问控制

    访问控制是API网关提供的API安全防护组件之一,主要用来控制访问API的IP地址,您可以通过设置IP地址的黑白名单来允许/拒绝某个IP地址访问API。访问控制插件和API本身是相互独立的,只有将访问控制插件绑定API后,访问控制策略才对绑定的API生效。IP访问控制插件创建页面如下图所示。

    test

    报文大小限制

    用来控制请求的报文大小,可配合流控策略使用,多维度限流,避免突发高流量导致后端服务过载。IP访问控制插件创建页面如下图所示。

    test

    插件爬虫

    爬虫插件用来对发送请求的工具进行筛选。主要针对于机器人或者爬虫,配置参数详情如下所示。

    • User agent:首部包含了一个特征字符串,用来让网络协议的对端来识别发起请求的用户代理软件的应用类型、操作系统、软件开发商以及版本号。User-Agent: <product> / <product-version> <comment>,浏览器一般使用下面的格式 User-Agent: Mozilla/<version>(<system-information>)<platform>(<platform-details>) extensions>,例如“火狐Mozilla/5.0 (Windows NT 6.1;Win64; x64; rv:47.0) Gecko/20100101 Firefox/ 47.0”可以表示成:Chrome:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (K HTML, like Gecko)或者 Chrome/51.0.2704.103 Safari/537.36
    • 白名单:配置允许通过的请求,配置形式是以逗号分割的正则表达式数组,正则表达式根据User-Agent头部匹配。
    • 黑名单:配置不允许通过的请求,配置形式是以逗号分割的正则表达式数组,正则表达式根据User-Agent头部匹配。

    HMAC Auth认证

    通过将HMAC签名身份验证添加到服务或路由,以建立传入请求的完整性。插件将验证Proxy-Authorization或Authorization头中发送的数字签名(按此顺序)。

    通过HMAC Auth访问凭证去调用API,在Headers中添加Authorization认证信息,包括用户名、签名等,可防止请求内容被篡改。

    配置参数说明如下所示。

    • clock_skew:签名有效时间,单位s,默认填充300s。
    • enforce_headers:需要的请求头,可填写多个key,默认显示date,不可删除。
    • algorithms:选择允许的签名算法,共4种:hmac-sha1,hmac-sha256,hmac-sha384,hmac-sha512,支持多选。
    • hide_credentials:是否隐藏凭证。
    • validate_request_body:是否启用body验证。

    查看插件详情

    点击插件管理列表页面的插件名称,跳转其详情页面。

    • 顶部基本详情展示:插件名称、状态(开启or关闭)、插件类型、描述、创建时间、配置内容。
    • 绑定的API列表:未绑定时,显示暂无数据;绑定后显示绑定的API名称、所属分组、生效环境、描述、绑定时间。
    • 支持绑定和解绑API:点击“绑定API”进行绑定;点击“解绑”进行解绑API操作同流量控制/绑定API小节。

    绑定API

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/插件管理],进入管理页面。

    (2) 通过以下任意一种方法,进入“绑定API”页面。

    STEP

    a.在待绑定的插件所在行,右侧操作列中下拉点击“绑定API”。

    b.点击插件名称进入插件详情页面,在“绑定的API列表”页签中点击“绑定API”按钮。

    (3) 选择“环境”、“API分组”以及“API名称”,筛选所需的API。勾选API,单击“确定”,完成API绑定插件。

    (4) 已绑定插件:展示此API已绑定的同类型的插件,绑定的其他类型的插件不在此展示;若想查看此API绑定的所有插件,请进入API详情页面的“绑定插件”页签进行查看。

    note

    API发布后才能绑定插件,若API已经绑定了一个插件,再次选择绑定其他插件(前提是同一类型)时,原有的插件将被覆盖。

    编辑插件

    操作步骤如下所示。

    (1) 在插件列表找到需要编辑的插件,在右侧的操作列中点击<编辑>按钮。

    (2) 在编辑插件对话框中编辑信息,插件名称、插件类型不支持编辑。

    (3) 编辑完成后,点击<保存>按钮。

    删除插件

    操作步骤如下:

    (1) 在控制台上部导航栏中,单击[开放API/插件管理],进入插件管理页面。

    (2) 页面列表选择需要删除的插件右侧操作列,点击<删除>按钮。

    (3) 在弹出的确认框中点击<确定>按钮,即可删除。

    note

    删除时需要满足该插件未被任何API使用。