文档首页/ API网关 APIG/ API参考（巴黎区域）/ 共享版API/ API管理/ 注册API

更新时间：2022-02-21 GMT+08:00

查看PDF

注册API

功能介绍

添加一个API，API即一个服务接口，具体的服务能力。

API分为两部分，第一部分为面向API使用者的API接口，定义了使用者如何调用这个API。第二部分面向API提供者，由API提供者定义这个API的真实的后端情况，定义了API网关如何去访问真实的后端服务。

API的真实后端服务目前支持三种类型：传统的HTTP/HTTPS形式的web后端、函数工作流、MOCK。

URI

HTTP/HTTPS请求方法以及URI如下表所示。

表1 HTTP/HTTPS请求方法以及URI
请求方法	URI
POST	/v1.0/apigw/apis

请求消息

表2 参数说明
参数	是否必选	类型	说明
group_id	是	String	API所属的分组编号
name	是	String	API名称长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以英文或中文开头。说明：中文字符必须为UTF-8或者unicode编码。
type	是	Integer	API类型： 1：公有API
version	否	String	API的版本字符长度不超过16
req_protocol	否	String	API的请求协议： HTTP HTTPS BOTH：同时支持HTTP和HTTPS 默认：HTTPS
req_method	是	String	API的请求方式： GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	是	String	API的访问地址说明：需要服从URI规范。
match_mode	否	String	API的匹配方式： SWA：前缀匹配 NORMAL：正常匹配（绝对匹配）默认：NORMAL
remark	否	String	API描述字符长度不超过255 说明：中文字符必须为UTF-8或者unicode编码。
auth_type	是	String	API的认证方式： NONE：无认证 APP：APP认证 IAM：IAM认证 AUTHORIZER：自定义认证
auth_opt	否	AuthOpt object	认证方式参数
authorizer_id	否	String	前端自定义认证对象的ID
backend_type	是	String	后端类型： HTTP：web后端 FUNCTION：函数工作流 MOCK：模拟的后端
tag	否	String	服务名称标签待废弃字段
tags	否	Array of string	标签包含一个服务名称标签和若干其它标签服务名称标签非必填，必须以APIG-SN-开头其它标签非必填，且不能以APIG-SN-开头
cors	否	Bool	是否支持跨域 TRUE：支持 FALSE：不支持默认：FALSE
body_remark	否	String	API请求体描述，可以是请求体示例、媒体类型、参数等信息字符长度不超过20480 说明：中文字符必须为UTF-8或者unicode编码。
result_normal_sample	否	String	正常响应示例，描述API的正常返回信息字符长度不超过20480 说明：中文字符必须为UTF-8或者unicode编码。
result_failure_sample	否	String	失败返回示例，描述API的异常返回信息字符长度不超过20480 说明：中文字符必须为UTF-8或者unicode编码。
response_id	否	String	分组自定义响应ID
backend_api	backend_type = HTTP时必填	字典数据类型	web后端详情
mock_info	backend_type = MOCK时必填	字典数据类型	mock后端详情
func_info	backend_type = FUNCTION时必填	字典数据类型	函数工作流后端详情
req_params	否	字典数据类型	API的请求参数列表
backend_params	否	字典数据类型	API的后端参数列表
policy_https	backend_type = HTTP时选填	字典数据类型	web策略后端列表。
policy_mocks	backend_type = MOCK时选填	字典数据类型	mock策略后端列表
policy_functions	backend_type = FUNCTION时选填	字典数据类型	函数工作流策略后端列表

表3 backend_api参数说明
参数	是否必选	类型	说明
url_domain	后端服务不使用VPC通道时，必选	String	后端服务的地址。由域名（或IP地址）和端口号组成，总长度不超过255。格式为域名:端口（如：apig.example.com:7443）。如果不写端口，则HTTPS默认端口号为443， HTTP默认端口号为80。支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。
version	否	String	web后端版本字符长度不超过16
req_protocol	是	String	请求协议： HTTP HTTPS
req_method	是	String	请求方式： GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	是	String	请求地址总长度不超过512，且满足URI规范。支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。说明：需要服从URI规范。
timeout	是	Integer	API网关请求后端服务的超时时间，最大60000，最小为1 单位：毫秒
remark	否	String	描述字符长度不超过255 说明：中文字符必须为UTF-8或者unicode编码。
vpc_status	否	Integer	是否使用VPC通道： 1 : 使用VPC通道 2 : 不使用VPC通道
vpc_info	如果vpc_status=1，则这个字典类型为必填信息	字典类型	VPC通道详情
authorizer_id	否	String	后端自定义认证对象的ID

表4 VPC通道参数说明
参数	是否必选	类型	说明
vpc_id	是	String	VPC通道编号
vpc_proxy_host	否	String	代理主机

表5 mock_info参数说明
参数	是否必选	类型	说明
result_content	否	String	返回结果
version	否	String	版本字符长度不超过64
remark	否	String	描述信息长度不超过255个字符说明：中文字符必须为UTF-8或者unicode编码。

表6 func_info参数说明
参数	是否必选	类型	说明
function_urn	是	String	函数URN
invocation_type	是	String	调用类型:async\|sync （异步\|同步）
timeout	是	Integer	API网关请求函数服务的超时时间，最大60000，最小为1 单位：毫秒
version	否	String	版本信息字符长度不超过64
remark	否	String	描述信息长度不超过255个字符说明：中文字符必须为UTF-8或者unicode编码。

表7 req_params参数说明
参数	是否必选	类型	说明
name	是	String	参数名称长度为1 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”、“.”组成，且只能以英文开头。
type	是	String	参数类型： STRING NUMBER
location	是	String	参数位置： PATH QUERY HEADER
default_value	否	String	参数默认值
sample_value	否	String	参数示例值
required	否	Integer	是否必须： 1：是 2：否 lacation为PATH时，required默认为1，其他场景required默认为2
valid_enable	否	Integer	是否开启校验： 1：开启校验 2：不开启校验默认为2
remark	否	String	描述字符长度不超过255 说明：中文字符必须为UTF-8或者unicode编码。
enumerations	否	String	参数枚举值
min_num	否	Integer	参数最小值（参数类型为NUMBER时有效）
max_num	否	Integer	参数最大值（参数类型为NUMBER时有效）
min_size	否	Integer	参数最小长度
max_size	否	Integer	参数最大长度
regular	否	String	正则校验规则（暂不支持）
json_schema	否	String	JSON校验规则（暂不支持）

表8 backend_params参数说明
参数	是否必选	类型	说明
name	是	String	参数名称长度为1 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”、“.”组成，且只能以英文开头。
location	是	String	参数位置： PATH QUERY HEADER
origin	是	String	参数类别： REQUEST CONSTANT SYSTEM
value	是	String	参数值字符长度不超过255 类别为REQUEST时，值为req_params中的参数名称；类别为CONSTANT时，值为参数真正的值；类别为SYSTEM时，值为网关参数名称
remark	否	String	描述字符长度不超过255 说明：中文字符必须为UTF-8或者unicode编码。

表9 policy_https参数说明
参数	是否必选	类型	说明
name	是	String	策略后端名称长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。
url_domain	后端服务不使用VPC通道时，必选	String	策略后端的Endpoint。由域名（或IP地址）和端口号组成，总长度不超过255。格式为域名:端口（如：apig.example.com:7443）。如果不写端口，则HTTPS默认端口号为443， HTTP默认端口号为80。支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。
req_protocol	是	String	请求协议： HTTP HTTPS
req_method	是	String	请求方式： GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	是	String	请求地址总长度不超过512，且满足URI规范。支持环境变量，使用环境变量时，每个变量名的长度为3 ~ 32位的字符串，字符串由英文字母、数字、“_”、“-”组成，且只能以英文开头。说明：需要服从URI规范。
timeout	否	Integer	API网关请求后端服务的超时时间，最大60000，最小为1 单位：毫秒
vpc_status	否	Integer	是否使用VPC通道： 1 : 使用VPC通道 2 : 不使用VPC通道
vpc_info	如果vpc_status=1，则这个字典类型为必填信息	字典类型	VPC通道详情
effect_mode	是	String	关联的策略组合模式 ALL ANY
conditions	是	字典数据类型	策略条件列表
backend_params	否	字典数据类型	后端参数列表

**表10** policy_mocks参数说明
参数	是否必选	类型	说明
name	是	String	策略后端名称长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。
result_content	否	String	返回结果
effect_mode	是	String	关联的策略组合模式 ALL ANY
conditions	是	字典数据类型	策略条件列表
backend_params	否	字典数据类型	后端参数列表

**表11** policy_functions参数说明
参数	是否必选	类型	说明
name	是	String	策略后端名称长度为3 ~ 64位的字符串，字符串由中文、英文字母、数字、“_”组成，且只能以中文或英文开头。
function_urn	是	String	函数URN
invocation_type	是	String	调用类型: async（异步） sync （同步）
timeout	否	Integer	API网关请求函数服务的超时时间，最大60000，最小为1 单位：毫秒
version	否	String	版本信息字符长度不超过64
effect_mode	是	String	关联的策略组合模式 ALL ANY
conditions	是	字典数据类型	策略条件列表
backend_params	否	字典数据类型	后端参数列表

**表12** conditions参数说明
参数	是否必选	类型	说明
condition_type	策略类型为param时必选	String	策略条件： exact：绝对匹配 enum：枚举 pattern：正则
condition_value	是	String	策略值
condition_origin	是	String	策略类型： param：参数 source：源IP
req_param_name	策略类型为param时必选	String	关联的请求参数对象名称

**表13** AuthOpt
参数	是否必选	类型	说明
app_code_auth_type	否	String	AppCode简易认证类型，仅在auth_type为APP时生效，默认为DISABLE： DISABLE：不开启简易认证 HEADER：开启简易认证且AppCode位置在HEADER

请求消息样例：

{
  "auth_type": "app",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "backend_api": {
    "req_method": "get",
    "req_protocol": "http",
    "req_uri": "/test",
    "timeout": 1000,
    "url_domain": "xxxxxxxxxxx"
  },
  "backend_params": [
    {
      "location": "query",
      "name": "project_id",
      "origin": "request",
      "value": "project_id"
    },
    {
      "location": "query",
      "name": "city",
      "origin": "request",
      "value": "city"
    }
  ],
  "backend_type": "http",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "name": "test",
  "req_method": "get",
  "req_params": [
    {
      "location": "path",
      "name": "project_id",
      "required": 1,
      "type": "string"
    },
    {
      "location": "query",
      "name": "city",
      "required": 2,
      "type": "string"
    }
  ],
  "req_uri": "/test/{project_id}",
  "tags": ["APIG-SN-test", "test"],
  "type": 1,
  "result_normal_sample": "hello world!"
}

响应消息

**表14** 参数说明
参数	类型	说明
id	String	API编号
name	String	API名称
group_id	String	API所属分组的编号
group_name	String	API所属分组的名称
status	Integer	API的状态
type	Integer	API类型
version	String	API版本
req_protocol	String	API访问协议
req_method	String	API请求方式
req_uri	String	API访问地址
auth_type	String	API认证方式
auth_opt	字段数据类型	API认证方式参数
match_mode	String	API匹配方式
register_time	Timestamp	API注册时间
update_time	Timestamp	API修改时间
remark	String	API描述
bakend_type	String	后端类型
arrange_necessary	Integer	是否需要编排
tag	String	服务名称标签，待废弃字段
tags	[]String	标签
cors	Bool	是否支持跨域访问
body_remark	String	API请求体描述，可以是请求体示例、媒体类型、参数等信息
result_normal_sample	String	正常响应示例，描述API的正常返回信息
result_failure_sample	String	失败返回示例，描述API的异常返回信息
response_id	String	分组自定义响应ID
backend_api	字典数据类型	后端服务：web后端详情
mock_info	字典数据类型	后端服务：MOCK详情
func_info	字典数据类型	后端服务：函数工作流后端详情
req_params	字典数据类型	API的请求参数列表
backend_params	字典数据类型	API的后端参数列表
policy_https	字典数据类型	web策略后端列表
policy_mocks	字典数据类型	mock策略后端列表
policy_functions	字典数据类型	函数工作流策略后端列表

**表15** backend_api参数说明
参数	类型	说明
id	String	编号
status	Integer	状态
url_domain	String	后端endpoint
version	String	版本
req_protocol	String	访问协议
req_method	String	访问方式
req_uri	String	访问地址
timeout	Integer	访问超时时间，单位：毫秒
register_time	Timestamp	注册时间
update_time	Timestamp	修改时间
remark	String	描述
vpc_status	String	是否使用VPC通道
vpc_info	String	VPC通道信息

**表16** mock_info参数说明
参数	类型	说明
id	String	编号
status	Integer	状态
version	String	版本
result_content	String	返回结果
register_time	Timestamp	注册时间
update_time	Timestamp	修改时间
remark	String	描述

**表17** func_info参数说明
参数	类型	说明
id	String	编号
status	Integer	状态
version	String	版本
function_urn	String	函数URN
invocation_type	String	调用类型:async\|sync
register_time	Timestamp	注册时间
update_time	Timestamp	更新时间
timeout	Integer	超时时间，单位：毫秒
remark	String	描述

**表18** req_params参数说明
参数	类型	说明
id	String	参数编号
name	String	参数名称
type	String	参数类型
location	String	参数位置
default_value	String	参数默认值
sample_value	String	参数示例值
required	Integer	是否必须
valid_enable	Integer	是否开启校验
remark	String	描述
enumerations	String	参数枚举值
min_num	Integer	参数最小值（参数类型为NUMBER时有效）
max_num	Integer	参数最大值（参数类型为NUMBER时有效）
min_size	Integer	参数最小长度
max_size	Integer	参数最大长度
regular	String	正则校验规则（暂不支持）
json_schema	String	JSON校验规则（暂不支持）

**表19** backend_params参数说明
参数	类型	说明
id	String	参数编号
req_param_id	String	对应的请求参数编号
name	String	参数名称
location	String	参数位置
origin	String	参数类别
value	String	参数值
remark	String	描述

**表20** policy_https参数说明
参数	类型	说明
id	String	编号
name	String	策略后端名称
url_domain	String	策略后端endpoint
req_protocol	String	访问协议
req_method	String	访问方式
req_uri	String	访问地址
timeout	Integer	访问超时时间，单位：毫秒
vpc_status	String	是否使用VPC通道
vpc_info	String	VPC通道信息
effect_mode	String	关联的策略组合模式
conditions	字典数据类型	策略条件列表
backend_params	字典数据类型	后端参数列表

**表21** policy_mocks参数说明
参数	类型	说明
id	String	编号
name	String	策略后端名称
result_content	String	返回结果
effect_mode	String	关联的策略组合模式
conditions	字典数据类型	策略条件列表
backend_params	字典数据类型	后端参数列表

**表22** policy_functions参数说明
参数	类型	说明
id	String	编号
name	String	策略后端名称
version	String	版本
function_urn	String	函数URN
invocation_type	String	调用类型:async\|sync
timeout	Integer	超时时间，单位：毫秒
effect_mode	String	关联的策略组合模式
conditions	字典数据类型	策略条件列表
backend_params	字典数据类型	后端参数列表

**表23** conditions参数说明
参数	类型	说明
id	String	编号
condition_type	String	策略条件
condition_value	String	策略值
condition_origin	String	策略类型
req_param_name	String	关联的请求参数对象名称
req_param_id	String	关联的请求参数对象编号
req_param_location	String	关联的请求参数对象位置

**表24** auth_opt参数说明
参数	类型	说明
app_code_auth_type	String	AppCode简易认证类型

响应消息样例：

{
  "name": "test",
  "type": 1,
  "version": "V0.0.1",
  "req_protocol": "HTTPS",
  "req_method": "GET",
  "req_uri": "/test/{tenant_id}",
  "auth_type": "APP",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "tags": ["APIG-SN-test", "test"],
  "cors": false,
  "match_mode": "NORMAL",
  "backend_type": "HTTP",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "result_normal_sample": "hello world!",
  "id": "81efcfd94b8747a0b21e8c04144a4e8c",
  "status": 1,
  "arrange_necessary": 2,
  "register_time": "2018-08-15T03:41:11.0239936Z",
  "update_time": "2018-08-15T03:41:11.0239936Z",
  "group_name": "group0002",
  "backend_api": {
    "url_domain": "xxxxxxxxxxx",
    "req_protocol": "HTTP",
    "req_method": "GET",
    "req_uri": "/test",
    "timeout": 1000,
    "vpc_status": 2,
    "id": "3442ffd031814e3a8f133a9f1ea08453",
    "status": 1,
    "register_time": "2018-08-15T03:41:11.1019236Z",
    "update_time": "2018-08-15T03:41:11.1019236Z"
  },
  "req_params": [
    {
      "name": "tenant_id",
      "type": "STRING",
      "location": "PATH",
      "required": 1,
      "valid_enable": 2,
      "id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "type": "STRING",
      "location": "QUERY",
      "required": 2,
      "valid_enable": 2,
      "id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "backend_params": [
    {
      "name": "tenant_id",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "tenant_id",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "city",
      "id": "b60fbcb5b86f4f5c8705c445b9bd6325",
      "req_param_id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "policy_https": [{
    "conditions": [{
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "condition_type": "pattern",
      "condition_value": "^[0-9]$",
      "condition_origin": "param",
      "req_param_name": "project_id",
      "req_param_id": "b60fbcb5b86f4f5c8705c445b9sda325",
      "req_param_location": "PATH"
    }],
    "backend_params": [{
      "name": "project_id",
      "value": "bbbb",
      "location": "QUERY",
      "origin": "REQUEST",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    }],
    "effect_mode": "ANY",
    "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
    "name": "policy001",
    "req_method": "GET",
    "req_protocol": "http",
    "req_uri": "/test/policy",
    "timeout": 10000,
    "url_domain": "xxxxxxxxxxx",
    "vpc_status": 2
  }]
}

状态码

**表25** 返回消息说明
状态码	说明
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Server Internal Error

父主题： API管理

上一篇：对象模型

下一篇：修改API

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消