API的导入导出

更新时间：2020-07-22

API网关支持API的导入导出，导出功能目前只支持API网关自定义的yaml格式导出，导入功能支持API网关自定义的yaml格式导入和swagger格式的导入。

下面针对API网关的导入导出功能进行说明。

导出功能

导出功能目前只支持API网关自定义的yaml格式导出。您可以在console界面中API管理界面选择想要导出的API后进行导出：

您也可以在分组管理界面中将整个分组的API全部导出：

导入功能

您可以在分组管理和API管理页面进行API的导入:

导入功能支持API网关自定义的yaml格式导入和swagger格式的导入，进行导入时可以选择导入模式，API网关导入功能支持三种模式，分别为：

新增模式：忽略冲突 API。用于在分组内新增 API，如果遇到与已有 API 冲突的情况，会忽略该 API 的导入。
覆盖模式：覆盖冲突 API。导入 API 时，如果遇到与已有 API 冲突的情况，则覆盖已有 API。可用于恢复分组 API 快照等场景。
更新模式：只更新已有 API。若有冲突则忽略对应 API 的导入。使用该模式，需要在将要导入的 API 定义中，为每个 API 指定其在分组中的 API ID。

您可以根据需要选择导入模式。

API网关自定义格式的导入

针对导入导出，API网关有一套自定义的yaml格式，您可以将API导出然后在另外一个分组进行导入，此时您不需要进行额外的配置或修改，直接导入即可，在导入界面将导入格式选择为yaml格式即为使用API网关自定义yaml进行导入，而分组名称表示您要将API导入的分组：

Swagger格式yaml导入

Swagger是一种用于描述API定义的规范，被广泛应用于定义和描述后端应用服务的API。现在，API网关支持导入Swagger 2.0的文件(目前只支持yaml格式)来导入API。为了适配API网关的API定义，我们对Swagger进行了扩展，API网关的Swagger扩展基于Swagger 2.0，可以创建API实体的Swagger定义，并将Swagger导入API网关用于批量创建或者更新API实体。

本章节主要对基于Swagger的API网关扩展进行介绍，并提供相应的示例来阐述用法。

Swagger扩展说明

API网关的Swagger扩展基于Swagger 2.0，可以创建API实体的Swagger定义，并将Swagger导入API网关用于批量创建或者更新API实体。

Swagger扩展主要是对于swagger原生Operation Object进行扩展，增加认证、参数映射以及后端服务等扩展。除此之外，增加处理any方法的扩展，用于捕获任意http(s)请求方法。所有扩展均以x-bce-apigw-开头，具体扩展内容如下：

必要扩展

该类配置是用户在API网关导入API时必须进行的配置。

x-bce-apigw-backend-services

应用于Operation Object。用于设置后端服务信息。根据后端服务类型，决定具体的属性。因为网关支持多个后端，所以可以配置相同type的多个后端服务。而后端services有着多个共同属性，比如path、type等，下面针对x-bce-apigw-backend-services进行说明

公共属性（非mock类型）：

属性名	类型	是否必填	说明
type	String	是	配置后端请求类型，分为HTTP、MOCK和WEBSOCKET(schemes请对应配置为ws)
path	String	是	配置后端请求的请求path，多个后端公用。
method	String	是	配置后端请求的请求方法，多个后端公用。
timeout	String	否	配置后端服务的超时时间，多个后端公用。
hosts	`List<SwaggerBackendServer>`	是	配置后端服务的具体内容。

公共属性（mock类型）：

属性名	类型	是否必填	说明
mockResult	String	是	mock的返回结果
mockStatusCode	String	否	mock的状态码
mockHeaders	`List<MockHeader>`	否	mock的返回头

下面针对SwaggerBackendServer和MockHeader进行说明

SwaggerBackendServer

属性名	类型	是否必填	说明
subType	String	是	后端服务具体类型类型： INSTANCE：HTTP(s)或websocket实例 VPC：vpc服务 BNS：bns服务 CFC：cfc服务
address	String	是	后端服务地址
region	String	否	区域，默认DEFAULT
weight	int	否	权重（默认值-1）
qps	int	否	qps限制（默认值-1）

MockHeader

属性名	类型	是否必填	说明
key	String	是	header的key
value	String	是	header的value

配置示例

x-bce-apigw-backend-services:
  path: '/a'
  timeout: 80000
  method: any
  type: HTTP
  hosts:
  - address: 'http://baidu.com'
    qps: 200
    region: DEFAULT
    subType: INSTANCE

非必要扩展

本部分扩展为非必须扩展，您可以根据自己的API配置进行增加，如果不填写，网关会有相应的默认值进行填充。

x-bce-apigw-auth

应用于Operation Object。用于指定该API的授权类型。

子配置项

取值

ANONYMOUS：无验证
APP：APP的ak、sk验证（默认）

示例

x-bce-apigw-auth:APP

x-bce-apigw-api-id

应用于Operation Object。API的uuid，当导入模式为更新时配置生效，用于指定更新的api。只在单个api配置中生效，不存在全局配置。

子配置项

取值

API uuid，需要修改的API的uuid

示例

x-bce-apigw-api-id:GWAI-pxCkY5sLyMm

x-bce-apigw-mkt-enable

应用于Operation Object。用于指定该API是否允许上架云市场。

子配置项

取值

false：不允许（默认）
true：允许

示例

x-bce-apigw-mkt-enable:true

x-bce-apigw-request-mode

应用于Operation Object。用于指定query参数与后端服务参数的映射关系。没有此配置时，当有参数配置，则默认为映射；没有参数配置，则默认为透传。三个自选项不是必须都存在，依据需要配置即可。

子配置项

path
query
header
body

取值

PASSTHROUGH：透传
MAPPING：映射

示例

x-bce-apigw-requestmode:
  query:PASSTHROUGH
  header:MAPPING

x-bce-apigw-request-type

应用于Operation Object。用于指定body参数与后端服务参数的映射关系。

子配置项

取值

FORM（默认）：表示请求体为“application/x-www-form-urlencoded”格式。
STREAM：表示请求题为非form格式。比如请求体是二进制文件等，网关不支持映射该格式的body参数。

示例

x-bce-apigw-requestmode:FROM

x-bce-apigw-backend-params

应用于Operation Object。用于定义后端服务的常量参数。

子配置项

constant-params：用于定义后端的常量参数
system-params：用于定义后端的系统参数

两个配置的详细说明 constant-params配置

属性名	类型	是否必填	说明
name	String	是	参数名
value	String	是	值
location	String	是	位置
type	String	是	参数类型

system-params配置

属性名	类型	是否必填	说明
name	String	是	参数名
location	String	是	位置
type	String	是	参数类型

取值

无

示例

x-bce-apigw-backend:
  constant-params:
    - name:constanttest
      value:5
      location:query
      type:String
  system-para:
    - name:systemtest
      location:head
      type:BceAppId

x-bce-apigw-backend-request-content-type

应用于Operation Object。用于定义后端请求值的content type。只有当body映射模式为MAPPING时生效。

子配置项

category
value

取值

category取值：
CLIENT（默认）：使用客户端的content type
CUSTOM：使用自定义的
DEFAULT：使用网关默认的
value：当category选择为自定义时，必填。

x-bce-apigw-backend-response-content-type

应用于Operation Object。用于定义后端返回值的content type。

子配置项

取值

JSON(默认)：application/json;chartset=utf-8
TEXT：text/plain;chartset=utf-8
BINARY：application/octet-stream;chartset=utf-8
XML：application/xml;chartset=utf-8
HTML：text/html;chartset=utf-8

示例

x-bce-apigw-backend-response-content-type: JSON

x-bce-apigw-backend-mapping

应用于Parameter Object。用于设置后端请求参数的映射。子配置根据需要进行配置，不需要都配置。

子配置项

location：该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数位置。取值为：path、header、query
name：该属性仅在 x-bce-apigw-requestmode的子配置项配置为MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。如果不设置，采用与请求参数相同的名字

取值

请见上方子配置项说明

示例

x-bce-apigw-backend-mapping:
  location:query
  name:newname

x-bce-apigw-request-param

应用于Parameter Object。用于设置网关请求参数的校验。子配置根据需要进行配置，不需要都配置。

子配置项

fixed：用于设置入参为固定值类型。与参数属性“required=true”不应该同时存在。true 表示为固定参数
fixed-value：用于设置入参的固定值。只有当x-bce-apigw-request-param的子配置项fixed为true时生效。该配置不应与默认值同时存在。
check：用于设置入参的参数检查。
json-check：用于设置入参的json校验。

取值

请见上方子配置项说明

示例

x-bce-apigw-request-param:
  fixed:true
  fixed-value:5

x-bce-apigw-any-method:

应用于Path Item Object，用于设置API可以接受任意类型的http请求。

子配置项

取值

示例

x-bce-apigw-any-method:

x-bce-apigw-backend-error-msg

应用于Response Object，由于网关要求错误的返回必须带有code，message和description。所以对于4xx和5xx的返回，必须配置该字段。

子配置项

取值

示例

x-bce-apigw-backend-error-msg: 400 error

说明

关于swagger自带字段的使用：参数的描述请使用swagger自带的description字段；参数默认值请使用swagger自带的enum字段。以上字段的使用请参考swagger2.0官方文档：swagger关于parameter说明。
网关仅支持form格式body参数进行映射，其他格式（json、二进制文件）等不支持映射，仅支持透传。当Swagger配置文件存在formdata类型参数时，需要配置consumes节点。API网关现在只支持application/x-www-form-urlencoded类型。其他类型body应适应swagger 的body进行标记并且body选择透传。
针对映射配置，没有具体的配置时，当有参数配置，则默认为映射；没有参数配置，则默认为透传。
暂时不支持全局的parameter和response配置，这两个配置请放在具体的api中。

类型转换说明

网关与Swagger规范在定义数据类型时存在一定差异性，包括：

swagger数据类型	网关数据类型
type:integer format:int32	int
type:integer format:int64	long
type:number format:float	float
type:number format:double	double
type:boolean format:Boolean	boolean
type:string	String

整体示例

为了能够完整说明各个扩展，现提供一个完整的API配置示例，您可以参考该示例使用扩展字段。

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: BCE Api Gateway Swagger Sample
schemes:
  - http
  - https
x-bce-apigw-auth: APP
x-bce-apigw-mkt-enable: false
x-bce-apigw-backend-services:
  path: '/a'
  timeout: 80000
  method: any
  type: HTTP
  hosts:
  - address: 'http://baidu.com'
    qps: 200
    region: DEFAULT
    subType: INSTANCE
paths:
  '/swagger/apigw/get/{userId}':
    get:
      operationId: swaggerget
      schemes:
        - http
        - https
      x-bce-apigw-request-mode:
        header: MAPPING
      x-bce-apigw-mkt-enable: true
      x-bce-apigw-api-id: GWAI-pxCkY5sLyMm
      x-bce-apigw-auth: APP
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-bce-apigw-request-param:
            fixed: true
            fixed-value: 12
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-bce-apigw-backend-mapping:
            location: query
            name: backendQuery
      x-bce-apigw-backend-params:
        constant-params:
          - name: swaggerConstant
            value: swaggerConstant
            location: header
            type: STRING
        system-params:
          - name: BceAppId
            location: header
            type: BceAppId
      x-bce-apigw-backend-response-content-type: JSON
      x-bce-apigw-backend-services:
        type: MOCK
        mockStatusCode: 200
        mockResult: 2
        mockHeaders:
        - name: mockHeader
          value: mock
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
          x-bce-apigw-backend-error-msg: 4XX error
  '/swagger/apigw/postany/{userId}':
    post:
      operationId: swaggerpost
      schemes:
        - http
        - https
      x-bce-apigw-request-mode:
        header: MAPPING
        query: MAPPING
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
          x-bce-apigw-backend-mapping:
            location: query
            name: path2query
        - name: swaggerQuery1
          in: query
          required: false
          default: '1'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          enum: [1,2,3]
        - name: swaggerQuery2
          in: query
          required: false
          type: string
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-bce-apigw-backend-mapping:
            location: query
            name: headtoquery
        - name: swaggerBody
          in: formData
          required: true
          type: string
          x-bce-apigw-backend-mapping:
            location: query
            name: bodytoquery
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
          x-bce-apigw-backend-error-msg: 4XX error
    x-bce-apigw-any-method:
      operationId: swaggerany
      x-bce-apigw-request-mode:
        header: MAPPING
      schemas:
        - http
        - https
      x-bce-apigw-backend-services:
        path: '/a/{userId}'
        timeout: 80000
        method: any
        type: HTTP
        hosts:
        - address: 'http://baidu.com'
          qps: 200
          region: DEFAULT
          subType: INSTANCE
      parameters:
        - name: userId
          in: path
          required: true
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-bce-apigw-backend-mapping:
            location: query
            name: anyheader
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
          x-bce-apigw-backend-error-msg: 4XX error
  '/swagger/apigw/vpc/{userId}':
    get:
      operationId: vpc
      schemes:
        - http
        - https
      x-bce-apigw-request-mode:
        header: MAPPING
      x-bce-apigw-mkt-enable: true
      x-bce-apigw-auth: APP
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-bce-apigw-request-param:
            fixed: true
            fixed-value: 12
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-bce-apigw-backend-mapping:
            location: query
            name: backendQuery
      x-bce-apigw-backend-params:
        constant-params:
          - name: swaggerConstant
            value: swaggerConstant
            location: header
            type: STRING
        system-params:
          - name: BceAppId
            location: header
            type: BceAppId
      x-bce-apigw-backend-response-content-type: JSON
      x-bce-apigw-backend-services:
        path: '/a/{userId}'
        timeout: 80000
        method: any
        type: HTTP
        hosts:
        - address: 'vpc-gk9p7gq8q6xf:192.168.1.1:8'
          qps: 200
          region: bj
          subType: VPC
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
          x-bce-apigw-backend-error-msg: 4XX error
  '/swagger/apigw/websocket/{userId}':
    get:
      operationId: swaggerwesocket
      schemes:
        - ws
      x-bce-apigw-backend-services:
        path: '/a'
        timeout: 80000
        method: get
        type: WEBSOCKET
        hosts:
        - address: 'ws://baidu.com'
          qps: 200
          region: DEFAULT
          subType: INSTANCE
      x-bce-apigw-request-mode:
        header: MAPPING
        query: MAPPING
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
          x-bce-apigw-backend-mapping:
            location: query
            name: path2query
        - name: swaggerQuery1
          in: query
          required: false
          default: '1'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          enum: [1,2,3]
        - name: swaggerQuery2
          in: query
          required: false
          type: string
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-bce-apigw-backend-mapping:
            location: query
            name: headtoquery
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
          x-bce-apigw-backend-error-msg: 400 error

后端密钥管理

调用指南