API的导入导出
所有文档

          API网关

          API的导入导出


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

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

          导出功能

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

          image.png

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

          image.png

          导入功能

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

          image.png

          导入功能支持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导入的分组:

          image.png

          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的返回头

          下面针对SwaggerBackendServerMockHeader进行说明

          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
          上一篇
          后端密钥管理
          下一篇
          调用指南