API管理
所有文档

          API网关

          API管理

          API的完整生命周期包括:创建、修改、调试、发布、下线、删除等,API Gateway为用户提供了与之对应的功能。

          创建API

          创建API操作需要定义API的基本信息、请求信息、后端服务信息、返回结果信息。创建完成的API仅为一份API定义,无法直接调用,需要使用发布功能发布至具体环境后方可调用。

          image.png

          登录百度智能云控制台,在产品与服务中选择“API网关”,进入网关控制台。点击左侧导航栏中“API列表”,选择创建API开始配置API定义。

          配置API基本信息

          API基本信息是对API的概述。智能云用户在单个分组中最多创建1000个API,如需增加请提工单。

          image.png

          • 分组:指明API所属分组,请在创建API前完成所属分组的创建。API将使用所属分组的属性,包括:域名、环境变量等。
          • API名称:API名称在所属分组中不可重复。
          • 安全认证:

            • APP AK/SK:当API调用者发起请求时,通过请求中包含的APP信息判断当前调用者是否有权调用当前API。
            • 无认证:任何API调用者均可对当前API发起请求(安全性较差,若无特殊需求,不推荐使用)。无法使用APP、账号级别的流量控制功能。
          • 允许上架至云市场:勾选该选项,API可上线至云市场售卖,文档可被所有用户获取。
          • 描述:对API进行基本描述,内容会用于文档显示。

          配置API请求信息

          API请求信息描述了API的调用者如何对当前API发起请求,包括请求方式和请求参数。

          请求方式

          image.png

          • 协议:支持HTTP、HTTPS和WebSocket,前两项可多选,但如果选择WebSocket就只能单选。若通过分组自定义域名发起HTTPS请求,则需要在分组管理中上传对应证书,否则调用异常。
          • 请求Path:指名请求的接口路径,无字符限制,对url不支持的字符(如:中文、标点符号等)无需进行转义。若在Path中使用转义字符,则会被API Gateway反转义为原始字符保存、使用。

            • 匹配所有子路径:支持对当前Path的子路径的匹配。
          • HTTP Method:支持GET、POST、DELETE、PUT、HEAD、TRACE、PATCH、CONNECT、OPTIONS、ANY,ANY表示任意Method。当Method为POST、PUT、PATCH、ANY时需要配置请求Body相关内容。
          • Query转发模式:支持映射和透传。
          • Header转发模式:支持映射和透传。
          • Body转发模式:支持映射和透传。当前API Gateway仅支持对contentType为application/x-www-form-urlencoded的请求Body进行映射,其他类型请求Body请选择透传。
          • Body内容描述:对请求Body进行基本描述,内容会用于文档显示。
          • Body类型确认:确认请求Body是否contentType为application/x-www-form-urlencoded。

          注意:
          1.请求Path中形如“/[Path参数名]”用于表示Path参数,需要与请求参数中的Path参数一一对应。
          2.请求Path配置时请注意末尾的分割符,”/path“与”/path/“不等效。
          3.匹配子路径无法匹配子串,如:“/path”可匹配”/path/“、”/path/subPath“,但无法匹配”/pathAndSubPath“
          4.参数转发模式配置时,若选择参数映射,需要在请求参数中添加对应位置的参数,实际请求时未配置的请求参数会被丢弃;若选择参数透传,则请求参数中无法添加对应位置参数,实际请求时该位置参数会直接透传。
          5.API Gateway会通过API查重,规则为:同一分组中,不可出现Path、Method、必选Query参数均相同的两个API。

          请求参数

          image.png

          • 参数名称:发起API调用时需要使用的参数名称,不可重复。
          • 参数位置:支持PATH、QUERY、HEADER、BODY。
          • 参数类型:支持STRING、INT、LONG、FLOAT、DOUBLE、BOOLEAN。
          • 必填:参数是否必填。PATH位置参数一定为必填。
          • 默认值:非必填参数可设置默认值。
          • 示例:取值示例,内容会用于文档显示。
          • 描述:参数描述,内容会用于文档显示。
          • 高级设置:

            • 最大长度:当前参数允许的最大长度。
            • 最小长度:当前参数允许的最小长度。
            • 枚举:当前参数允许的取值,以枚举形式表示,不同取值用英文的逗号分隔。
            • 文档可见:当前参数在文档中是否可见。
            • 参数验证:使用正则表达式规定参数取值的形式,当前不做校验,仅用于文档显示。
            • JSON验证:使用JSON Schema规定参数取值的形式,当前不做校验,仅用于文档显示。

          注意: 1.位置为PATH的参数,必需在请求Path中进行配置,形如“/[Path参数名]”。
          2.位置为BODY的参数指contentType为application/x-www-form-urlencoded的Body中单个的取值,而非整个Body。
          3.当前API Gateway会根据请求参数的位置、类型、必填、最大长度、最小长度对实际请求中的参数做校验,其余配置项仅用于文档展示。

          定义WebSocket类型请求

          对于请求协议为WebSocket类型的请求,配置过程与上述过程类似,但仅有WebSocket相关配置。

          image.png

          配置API后端服务信息

          API后端服务信息描述了API开放者提供的服务相关信息,包括后端请求方式、后端请求参数、后端常量参数、后端系统参数。后端服务支持HTTP(S)和Mock两种类型,需要配置不同后端请求方式。

          HTTP(S)类型后端服务

          image.png

          • 后端服务地址:指名后端资源所在主机的地址,支持域名、IP形式,不可重复。

            • 类型:当前均为实例。
            • 权重:指名多后端地址轮询时,当前地址的权重,取值为1~100之间的整型值,默认为1。当具有多个后端地址时生效。
          • 后端请求Path:指名后端资源具体路径,无字符限制,对url不支持的字符(如:中文、标点符号等)无需进行转义。若在Path中使用转义字符,则会被API Gateway反转义为原始字符保存、使用。

            • 匹配所有子路径:仅当API请求信息中选择了子路径匹配后,此处才可勾选。
          • HTTP Method:支持GET、POST、DELETE、PUT、HEAD、TRACE、PATCH、CONNECT、OPTIONS、ANY,ANY表示任意Method。当Method为POST、PUT、PATCH、ANY时需要配置请求Body相关内容。
          • 后端超时时间:单位为毫秒,取值为1~300000之间的整型值,默认为90000。
          • ContentType:指名转发给后端的ContentType头字段取值策略,支持API网关默认、自定义、透传。若请求信息中Body转发模式为透传,则此处必需为透传。
          • ContentType取值:当ContentType策略为自定义时,指名ContentType取值。

          注意:
          1.在后端服务地址、后端请求Path中,可通过#环境变量名称#的方式使用环境变量。
          2.后端请求Path中形如“/[Path参数名]”用于表示Path参数,需要与后端请求参数中的Path参数一一对应。
          3.当API请求方式、后端请求方式中,同时勾选匹配子路径时,后端访问会透传请求路径。
          4.当API请求方式、后端请求方式中,同时使用ANY方法时,后端访问会透传请求Method。

          Mock类型后端服务

          image.png

          • Mock返回结果:指名当前接口的Mock结果。API Gateway返回的ContentType为“application/json”,因此建议填写JSON格式内容。
          • HTTP Status Code:指名返回请求码,默认为200。合法取值包括:200、201、202、203、204、205、206、300、301、302、303、304、305、307、400、401、402、403、404、405、406、407、408、409、410、411、412、413、414、415、416、417、450、451、500、501、502、503、504、505。
          • MOCK Header:指名当前API需要返回的Header。

          注意:Mock类型后端服务无需配置系统参数、常量参数。

          后端请求参数

          image.png

          参数名称:指名向后端转发的参数名称,在所有后端参数中不可重复。
          参数位置:支持PATH、QUERY、HEADER、BODY。

          注意:
          1.对应入参名称、对应入参位置、对应入参类型仅用于显示,无需配置。
          2.后端服务参数必需与入参定义中的参数一一对应,无法手工增加。
          3.位置为PATH的参数,必需在后端请求Path中进行配置,形如“/[Path参数名]”。
          4.位置为BODY的参数指KEY/VALUE类型Body中单个的取值,而非整个Body。

          后端请求常量参数

          image.png

          • 参数名称:指名常量参数名称,在所有后端参数中不可重复。
          • 参数值:不可为空。
          • 参数位置:支持PATH、QUERY、HEADER、BODY。
          • 参数类型:支持STRING、NUMBER、BOOLEAN。

          后端请求系统参数

          image.png

          • 参数名称:指名系统参数名称,在所有后端参数中不可重复。
          • 系统参数取值:指名当前系统参数需要的取值,见下表说明。
          • 参数位置:支持PATH、QUERY、HEADER、BODY。
          系统参数取值 说明
          BceClientIp 发送请求的客户端 IP
          BceDomain 发送请求的域名
          BceRequestHandleTime 请求时间(格林威治时间)
          BceAppId 请求的 APP 的 ID
          BceRequestId RequestId
          BceHttpSchema 用户调用 API 使用的协议,http 或者 https
          BceClientUa 发送请求时使用的User-Agent
          BceProxy 表示网关代理名称,固定为BceApiGateway

          定义WebSocket类型后端

          只有请求定义为WebSocket类型,才允许配置WebSocket类型后端。

          WebSocket的配置项含义与HTTP协议的配置项含义相同,可在上面找到相应描述。

          image.png

          配置返回结果信息

          目前,返回结果信息仅用于文档显示,对实际转发不造成影响,包括返回结果结果说明和错误码说明。

          后端返回结果

          image.png

          • 返回ContentType:支持JSON、TEXT、BINARY、XML、HTML格式。
          • 返回结果示例:描述访问当前API成功的返回结果。
          • 失败返回结果示例:描述访问当前API失败的返回结果。

          后端错误码说明

          image.png

          • 错误码:指名后端服务可能抛出的异常编码,支持英文、数字,只能以英文开头,1-180个字符。不同于HTTP Status。
          • 错误信息:错误码对应的描述信息。
          • 描述:关于当前错误码本身的备注信息。(待确定)

          修改API

          创建API后可按需对API进行修改。

          image.png

          1.进入网关控制台。点击左侧导航栏中“API列表”。
          2.找到需要修改的API,点击“详情”,进入详情页面。

          image.png

          3.点击页面上部“编辑”按钮对API进行修改,各配置项限制规则与创建API相同。

          注意:对API进行修改,不会对已发布的API版本造成影响。如需当前修改在API调用者请求时生效,则需在修改后进行再次发布。

          删除API

          image.png

          1.进入网关控制台。点击左侧导航栏中“API列表”。
          2.找到需要删除的API,点击“删除”。

          注意:在删除当前API之前需要确保所有环境中该API已下线。

          发布API

          API定义需要发布至具体环境中使定义生效,API调用者可在对应环境中调用该API。

          image.png

          1.进入网关控制台。点击左侧导航栏中“API列表”。
          2.找到需要发布的API,点击“发布”。

          image.png

          3.为API选择要发布到的环境,并填写发布描述。描述主要针对当前发布版本的修改。
          4.点击“发布”按钮,完成API发布。

          注意:一个API在一个环境中只能存在一个发布的版本,当多次发布时,最近一次发布版本会覆盖先前生效的版本。

          下线API

          当API需要停止对外提供服务时,可使用下线功能将API从指定环境中移除。API调用者无法继续在对应环境中使用API。

          image.png

          1.进入网关控制台。点击左侧导航栏中“API列表”。
          2.找到需要下线的API,点击“下线”。可以在“运行中环境”处查看各环境中已上线的API定义,确定需要下线的环境。

          image.png

          3.选择需要下线的环境,点击“下线”按钮,完成API下线。

          API历史版本切换

          当API进行发布操作时,会产生一份API历史版本,记录发布时API的详细定义。通过查看历史版本,可选择某个具体版本并进行切换,该版本的API定义会在对应环境中生效,替换该环境中之前发布的版本。

          image.png

          1.进入网关控制台。点击左侧导航栏中“API列表”。
          2.找到需要的API,点击“详情”,进入详情页面。

          image.png

          3.点击左侧导航栏“发布历史”,查看历史版本。
          4.选择“切换至此版本”进行历史版本切换。可选择“查看”按钮,查看具体API定义,明确要切换的版本。

          注意:API必须处于发布状态,才能进行历史版本切换。

          上一篇
          分组管理
          下一篇
          APP管理