注意:
由于 API 网关产品计划于2025年6月30日停止服务,云函数 SCF 和 Serverless 应用的 API 网关触发器将进行如下调整。具体内容请参见 云函数 SCF 与 Serverless 应用平台 API 网关触发器下线通知。
操作场景
API 网关组件是 serverless-tencent 组件库中的基础组件之一,您可以通过该组件快速且方便地创建、配置和管理腾讯云的 API 网关产品。
前提条件
已完成函数的创建,此处以在广州地域创建好的
myFuntion
函数为例。操作步骤
通过 API 网关组件,您可以对一个 API 服务/接口进行完整的创建、配置、部署和删除等操作。
安装
配置
1. 本地创建
serverless.yml
文件:touch serverless.yml
touch serverless.yml
echo. > serverless.yml
2. 在
serverless.yml
中进行如下配置: # serverless.ymlcomponent: apigateway # (必填) 组件名称,此处为 apigatewayname: apigwDemo # (必填) 实例名称app: appDemo # (可选) 该 next.js 应用名称stage: dev # (可选) 用于区分环境信息,默认值是 devinputs:region: ap-guangzhouprotocols:- http- httpsserviceName: serverlessenvironment: releaseendpoints:- path: /protocol: HTTPmethod: GETapiName: indexfunction:functionName: myFunction
注意:
1. 配置中的
region
需与前提条件中已创建好的函数地域相同。2. 配置中的
functionName
需与前提条件中创建好的函数名字相同。部署
执行以下命令进行扫码授权部署:
scf deploy
移除
执行以下命令移除部署的服务:
仅删除云函数相关的配置、代码。
关联的其他云资源(如 COS、CLS 等),平台均不会关联删除,您可以前往对应产品控制台删除,避免不必要的计费。
scf remove
账号配置(可选)
当前默认支持 CLI 扫描二维码登录,如您希望配置持久的环境变量/密钥信息,也可以本地创建
.env
文件:touch .env # 腾讯云的配置信息
在
.env
文件中配置腾讯云的 SecretId 和 SecretKey 信息并保存:# .envTENCENT_SECRET_ID=123TENCENT_SECRET_KEY=123
配置详情
完整配置
# serverless.ymlorg: orgDemo #(可选) 用于记录组织信息,默认值为您的腾讯云账户 appidapp: appDemo #(可选) 该应用名称stage: dev #(可选) 用于区分环境信息,默认值为 devcomponent: apigateway # (必填) 组件名称,此处为 apigatewayname: apigwDemo # (必填) 实例名称inputs:serviceId: service-8dsikiq6region: ap-shanghaiprotocols:- http- httpsserviceName: serverlessserviceDesc: the serverless serviceenvironment: releasenetTypes:- OUTER- INNERcustomDomains:- domain: abc.com# 如要添加https,需先行在腾讯云-SSL证书进行认证获取cettificateIdcertificateId: abcdefgisForcedHttps: true # 是否强制https,如果为true,必须配置 certificateId (SSL证书 ID)# 如要设置自定义路径映射,请设置为 falseisDefaultMapping: falsepathMappingSet:- path: /environment: releaseprotocols:- http- httpsendpoints:# 前端类型: WEBSOCKET, 后端类型: SCF- path: /method: GETprotocol: WEBSOCKETfunction:# 前端类型为WEBSOCKET且后端为SCF时, transportFunctionName 为是transportFunctionName: myFunctionregisterFunctionName: myFunctioncleanupFunctionName: myFunction# 前端类型: WEBSOCKET, 后端类型: HTTP- path: /wsprotocol: WEBSOCKETapiName: 'test-ws'method: GETserviceType: WEBSOCKETserviceConfig:url: 'ws://www.test.com'path: /method: GET# 前端类型: HTTP, 后端类型: SCF- path: /test/{abc}/{cde}apiId: api-idapiDesc: Serverless REST APImethod: GETenableCORS: trueresponseType: HTMLserviceTimeout: 10isBase64Encoded: falseisBase64Trigger: falsebase64EncodedTriggerRules:- name: Acceptvalue:- image/jpeg- name: Content_Typevalue:- image/jpegparam:- name: abcposition: PATHrequired: 'TRUE'type: stringdefaultValue: abcdesc: mytest- name: cdeposition: PATHrequired: 'TRUE'type: stringdefaultValue: abcdesc: mytestfunction:isIntegratedResponse: truefunctionQualifier: $LATESTfunctionName: myFunctionusagePlan:usagePlanId: 1111usagePlanName: slscmpusagePlanDesc: sls createmaxRequestNum: -1maxRequestNumPreSec: 1000auth:secretName: secretsecretIds:- xxx# 前端类型: HTTP, 后端类型: MOCK- path: /moprotocol: HTTPmethod: GETapiName: 'mock-api'serviceType: MOCKserviceMockReturnMessage: 'mock response content'# 前端类型: HTTP, 后端类型: HTTP- path: /restprotocol: HTTPapiName: 'test-http'method: GETserviceType: HTTPserviceConfig:url: 'http://www.test.com'path: /testmethod: GET# 下面两个为互相关联的 oauth2.0 接口示例# 参考文档 https://cloud.tencent.com/document/product/628/38393- path: '/oauth'protocol: 'HTTP'method: 'GET'apiName: 'oauthapi'authType: 'OAUTH'businessType: 'OAUTH'serviceType: 'HTTP'serviceConfig:method: 'GET'path: '/check'url: 'http://10.64.47.103:9090'oauthConfig:loginRedirectUrl: 'http://10.64.47.103:9090/code'publicKey: '{"e":"AQAB","kty":"RSA","n":"dkdd"}'tokenLocation: 'method.req.header.authorization'# // tokenLocation: 'method.req.header.cookie',- path: '/oauthwork'protocol: 'HTTP'method: 'GET'apiName: 'business'authType: 'OAUTH'businessType: 'NORMAL'authRelationApi:path: '/oauth'method: 'GET'serviceType: 'MOCK'serviceMockReturnMessage: 'helloworld'
配置说明
主要参数说明
参数 | 必选 | 参数类型 | 默认值 | 描述 |
serviceId | 否 | string | - | 网关服务 ID。 |
instanceId | 否 | string | - | 网关实例 ID,填写则使用独享型实例创建 API 网关,否则创建共享型实例。(该项只能在创建时指定,创建后无法修改) |
region | 是 | string | ap-guangzhou | 服务的部署区域。 |
protocols | 是 | string[] | ['http'] | 服务的前端请求类型,http 和 https。 |
serviceName | 否 | string | serverless | 用户自定义的服务名称。 如果该参数未传递,则由系统自动生成一个唯一名称。 |
netTypes | 否 | string[] | ['OUTER'] | 网络类型列表,用于指定支持的访问类型,INNER 为内网访问,OUTER 为外网访问。 |
serviceDesc | 否 | string | - | 用户自定义的服务描述说明。 |
environment | 是 | string | release | 服务要发布的环境的名称,支持三种环境: test、prepub、 release。 |
endpoints | 是 | - | - | |
customDomains | 否 | [] | 自定义域名。 |
Endpoint
API 参数说明:
参数 | 必选 | 类型 | 默认值 | 描述 |
apiId | 否 | string | - | API 的唯一 ID。 |
protocol | 否 | string | HTTP | 指定的前端 API 类型,支持 HTTP 、WEBSOCKET 。 |
path | 是 | string | - | API 路径。 |
method | 是 | string | - | 请求方法。 |
serviceType | 否 | string | SCF | 指定的后端类型,支持: SCF 、HTTP 、MOCK。 |
description | 否 | string | - | API 描述。 |
enableCORS | 否 | boolean | false | 是否启用跨域访问。 true:启用。 false:不启用。 |
function | 是 | - | 对应的 Serverless 云函数。 | |
usagePlan | 否 | - | 基于 API 维度的使用计划。 | |
auth | 否 | - | API 密钥鉴权设置。 | |
serviceTimeout | 否 | number | 15 | API 的后端服务超时时间,单位为秒。 |
responseType | 否 | string | - | 返回类型: HTML 、JSON 、TEST 、BINARY 、XML |
param | 否 | - | 前端请求参数。 | |
serviceConfig | 否 | - | API 的后端服务配置。 | |
serviceMockReturnMessage | 否 | string | - | Mock 接口类型返回结果,如果 serviceType 设置为 MOCK ,此参数必须。 |
authType | 否 | string | NONE | 鉴权类型,支持: NONE (免鉴权)、SECRET (密钥对),OAUTH (Oauth2.0),APP (应用鉴权) |
app | 否 | NONE | API 绑定 APP 配置 | |
businessType | 否 | string | NORMAL | 业务类型,支持: NORMAL 、OAUTH |
oauthConfig | 否 | - | Oauth2.0 鉴权,授业 API 后端配置,当 authType 为 OAUTH ,并且 businessType 为 OAUTH 时,此参数必选。 | |
authRelationApi | 否 | - | Oauth2.0 鉴权,业务 API 关联授业 API 配置,当 authType 为 OAUTH , 并且 businessType 为 NORMAL 时,此参数必选。 | |
isBase64Encoded | 否 | boolean | false | 是否开启 Base64 编码,只有后端为 scf 时才会生效。 |
isBase64Trigger | 否 | boolean | false | 是否开启 Base64 编码的 header 触发,只有后端为 scf 时才会生效。 |
base64EncodedTriggerRules | 否 | [] | Header 触发 Base64 编码规则,总规则数不能超过 10,只有 isBase64Trigger 设置为 true 才有效。 |
API 类型补充说明:
前端 API 类型 (参数:protocol) | 后端服务类型 (参数:serviceType) |
HTTP (默认) | SCF (默认) |
| HTTP |
| MOCK |
WEBSOCKET | SCF (默认) |
| WEBSOCKET |
Function
关联云函数参数配置:
说明:
此时
serviceType
必须为 SCF
。参数 | 必选 | 类型 | 默认值 | 描述 |
isIntegratedResponse | 否 | boolean | false | 是否开启响应集成,当前端类型为 HTTP 时生效。 |
functionQualifier | 否 | string | $DEFAULT | scf 函数版本。 |
functionName | 是 | string | - | 云函数的名称。 |
transportFunctionName | 否 | string | - | 传输函数的名称, protocol 为 WEBSOCKET 时必须。 |
registerFunctionName | 否 | string | - | 注册函数的名称, protocol 为 WEBSOCKET 时必须。 |
cleanupFunctionName | 否 | string | - | 清理函数的名称, protocol 为 WEBSOCKET 时必须。 |
ServiceConfig
API 的后端服务配置:
参数 | 必选 | 类型 | 默认值 | 描述 |
url | 是 | string | - | API 的后端服务 url,如果 serviceType 是 HTTP ,则此参数必传。 |
path | 是 | string | - | API 的后端服务路径,如果 serviceType 是 HTTP ,则此参数必传。 |
method | 是 | string | - | API 的后端服务请求方法,如果 serviceType 是 HTTP ,则此参数必传。 |
UsagePlan
使用计划参数说明:
参数 | 必选 | 类型 | 默认值 | 描述 |
usagePlanId | 是 | string | - | 用户自定义的基于 API 的使用计划 ID。 |
usagePlanName | 是 | string | - | 用户自定义的基于 API 的使用计划名称。 |
usagePlanDesc | 是 | string | - | 用户自定义的基于 API 的使用计划描述。 |
maxRequestNum | 是 | number | -1 | 允许的请求总数。默认情况下将使用 -1 ,表示禁用。 |
maxRequestNumPreSec | 是 | number | -1 | 每秒最大请求数。默认情况下将使用 -1 ,表示禁用。 |
SecretAuth
密钥鉴权参数说明:
参数 | 必选 | 类型 | 默认值 | 描述 |
secretName | 是 | string | - | 密钥名称。 |
secretIds | 否 | string[] | - | 密钥SecretId。 |
RequestParameter
前端请求参数说明:
参数 | 必选 | 类型 | 默认值 | 描述 |
name | 是 | string | - | 请求参数名称。 |
position | 是 | string | - | 参数位置,仅支持 PATH ,QUERY 和HEADER 类型。 |
type | 是 | string | - | 参数类型,如 String 和 int. |
defaultValue | 是 | string | - | 参数默认值。 |
required | 是 | boolean | - | 参数是否必填,TRUE:表示必填,FALSE:表示可选 |
desc | 是 | string | - | 参数备注/描述 |
CustomDomain
自定义域名:
参数 | 必选 | 类型 | 默认值 | 描述 |
domain | 是 | string | - | 需要绑定的自定义域名 |
certificateId | 否 | string | - | 自定义域名的证书,如果设置为 https,则为必需。 |
isDefaultMapping | 否 | boolean | true | 是否使用默认路径映射。 如果要自定义路径映射,请设为 false |
pathMappingSet | 否 | [] | 自定义路径映射, 当 isDefaultMapping 为 false 时,此参数必须 | |
protocols | 否 | string[] | ['http'] | 绑定自定义域协议类型,支持 http 和 https |
isForcedHttps | 否 | boolean | false | 是否强制 HTTPS。 |
PathMap
参数 | 必选 | 类型 | 默认值 | 描述 |
path | 是 | string | - | 自定义映射路径 |
environment | 是 | string | - | 自定义映射环境 |
OauthConfig
参数 | 必选 | 类型 | 默认值 | 描述 |
loginRedirectUrl | 是 | string | - | 重定向地址,用于引导用户登录操作 |
publicKey | 是 | string | - | 公钥,用于验证用户 token |
tokenLocation | 是 | string | - | token 传递位置,支持: method.req.header.authorization 、method.req.header.cookie |
AuthRelationApi
Oauth2.0 鉴权,业务 API 关联授业 API 配置,当
authType
为 OAUTH
,并且 businessType 为 NORMAL
时,此参数为必选。参数 | 必选 | 类型 | 默认值 | 描述 |
path | 是 | string | - | 关联授业 API 的请求路径 |
method | 是 | string | - | 关联授业 API 的请求路径 |
APP
参数名称 | 必选 | 类型 | 描述 |
name | 否 | string | 用户自定义 APP 名称 |
id | 否 | string | APP ID |
description | 否 | string | 用户自定义 APP 描述 |
Base64Rule
Header 触发 Base64 编码规则,总规则数不能超过10,只有
isBase64Trigger
设置为 true
才有效。参数名称 | 类型 | 描述 |
name | string | 进行编码触发的 header,可选值 "Accept" 和 "Content_Type" 对应实际数据流请求 header 中的 Accept 和 Content-Type |
value | string[] | 进行编码触发的 header 的可选值数组, 数组元素的字符串最大长度为 40,元素可以包括数字,英文字母以及特殊字符,特殊字符的可选值为: . + * - / _ |
例如
value
可以配置为:value:- application/zip
关于 API 网关 Base64 编码
说明:
开启 API 网关 Base64 编码的后端必须是云函数。
如果需要开启 API 网关 Base64 编码,必须配置
isBase64Encoded
为 true
,此时每次请求的请求内容都会被 Base64 编码后再传递给云函数。如果想要部分请求 Base64 编码,可以通过配置 isBase64Trigger
为 true
,配置 base64EncodedTriggerRules
Header 触发规则,此时 API 网关将根据触发规则对请求头进行校验,只有拥有特定 Content-Type 或 Accept 请求头的请求会被 Base64 编码后再传递给云函数,不满足条件的请求将不进行 Base64 编码,直接传递给云函数。详情见 Base64 编码。