文档首页/ API网关 APIG/ 开发指南（巴黎区域）/ 导入导出API/ 扩展定义
更新时间：2022-02-21 GMT+08:00
查看PDF
分享

扩展定义

扩展定义表示API网关特有的API定义项，如：认证方式、后端服务定义等。

API网关的扩展定义如下：

1 x-apigateway-auth-type

含义：基于Swagger的apiKey认证格式，定义API网关支持的特有认证方式。

作用域：Security Scheme Object

示例：

securityDefinitions:
  apig-auth-app:
    in: header
    name: Authorization
    type: apiKey
    x-apigateway-auth-type: AppSigv1
  apig-auth-iam:
    in: header
    name: unused
    type: apiKey
    x-apigateway-auth-type: IAM
表1 参数说明

参数

是否必选

类型

说明

type

是

String

认证类型，仅支持apiKey

name

是

String

用于认证的参数名称

in

是

String

仅支持header

description

否

String

描述信息

x-apigateway-auth-type

是

String

API网关认证方式，支持AppSigv1、IAM

2 x-apigateway-request-type

含义：API网关定义的API请求类型，支持public和private。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-request-type: 'public'
表2 参数说明

参数

是否必选

类型

说明

x-apigateway-request-type

是

String

API类型，支持public和private。

  • public：公开类型API，可以上架。
  • private：私有类型API，不会被上架。

3 x-apigateway-match-mode

含义：API网关定义的API请求URL的匹配模式，支持NORMAL和SWA。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-match-mode: 'SWA'
表3 参数说明

参数

是否必选

类型

说明

x-apigateway-match-mode

是

String

API匹配模式，支持SWA和NORMAL。

  • SWA：前缀匹配，如“/prefix/foo”和“/prefix/bar”都会被“/prefix ”匹配，但“/prefixpart”却不会被匹配。
  • NORMAL：绝对匹配。

4 x-apigateway-cors

含义：API网关定义的API请求是否支持跨域，boolean类型。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-cors: true

开启跨域访问的API请求，响应会增加如下头域：

头域名称

头域值

描述

Access-Control-Max-Age

172800

预检响应最大缓存时间

Access-Control-Allow-Origin

*

允许任何域

Access-Control-Allow-Headers

X-Sdk-Date，X-Sdk-Nonce，X-Proxy-Signed-Headers，X-Sdk-Content-Sha256，X-Forwarded-For，Authorization，Content-Type，Accept，Accept-Ranges，Cache-Control，Range

正式请求允许的头域

Access-Control-Allow-Methods

GET，POST，PUT，DELETE，HEAD，OPTIONS，PATCH

正式请求允许的方法

5 x-apigateway-any-method

含义：API网关定义的API请求方法，用以匹配未指定定义的HTTP方法。

作用域：Path Item Object

示例：

paths:
  '/path':
    get:
      produces:
        - application/json
      responses:
        "200":
          description: "get response"
    x-apigateway-any-method:
      produces:
        - application/json
      responses:
        "200":
          description: "any response"

6 x-apigateway-backend

含义：API网关定义的API后端服务定义。

作用域：Operation Object

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
表4 参数说明

参数

是否必选

类型

说明

type

是

String

后端服务类型，支持HTTP、HTTP-VPC、FUNCTION、MOCK

parameters

否

x-apigateway-backend.parameters

后端参数定义

httpEndpoints

否

x-apigateway-backend.httpEndpoints

HTTP类型后端服务定义

httpVpcEndpoints

否

x-apigateway-backend.httpVpcEndpoints

HTTP-VPC类型后端服务定义

functionEndpoints

否

x-apigateway-backend.functionEndpoints

FUNCTION类型后端服务定义

mockEndpoints

否

x-apigateway-backend.mockEndpoints

MOCK类型后端服务定义

6.1 x-apigateway-backend.parameters

含义：API网关定义的API后端参数定义。

作用域：x-apigateway-backend

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "认证token"
          type: "string"
          in: "header"
          required: true
        - name: "userId"
          description: "用户名"
          type: "string"
          in: "path"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        parameters:
          - name: "userId"
            value: "userId"
            in: "query"
            origin: "REQUEST"
            description: "用户名"
          - name: "X-Invoke-User"
            value: "apigateway"
            in: "header"
            origin: "CONSTANT"
            description: "调用者"
表5 参数说明

参数

是否必选

类型

说明

name

是

String

参数名称，由字母、数字、下划线、连线、点组成，以字母开头，最长32字节

header位置的参数名称不区分大小写

value

是

String

参数值，当参数来源为REQUEST时，值为请求参数名称

in

是

String

参数位置，支持header、query、path

origin

是

String

参数映射来源，支持REQUEST、CONSTANT

description

否

String

参数含义描述

6.2 x-apigateway-backend.httpEndpoints

含义：API网关定义的HTTP类型API后端服务定义。

作用域：x-apigateway-backend

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "认证token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP"
        httpEndpoints:
          address: "example.com"
          scheme: "http"
          method: "GET"
          path: "/users"
          timeout: 30000
表6 参数说明

参数

是否必选

类型

说明

address

是

Array

后端服务地址，格式为：<域名或IP>:[port]

scheme

是

String

后端请求协议定义，支持http、https

method

是

String

后端请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY

path

是

String

后端请求路径，支持路径变量

timeout

否

Number

后端请求超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000

6.3 x-apigateway-backend.httpVpcEndpoints

含义：API网关定义的HTTP VPC类型API后端服务定义。

作用域：x-apigateway-backend

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "认证token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "HTTP-VPC"
        httpVpcEndpoints:
          name: "vpc-test-1"
          scheme: "http"
          method: "GET"
          path: "/users"
          timeout: 30000
表7 参数说明

参数

是否必选

类型

说明

name

是

Array

VPC通道名称

scheme

是

String

后端请求协议定义，支持http、https

method

是

String

后端请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH、ANY

path

是

String

后端请求路径，支持路径变量

timeout

否

Number

后端请求超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000

6.4 x-apigateway-backend.functionEndpoints

含义：API网关定义的FUNCTION类型API后端服务定义。

作用域：x-apigateway-backend

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "认证token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "FUNCTION"
        functionEndpoints:
          version: "v1"
          function-urn: ""
          invocation-type: "synchronous"
          timeout: 30000
表8 参数说明

参数

是否必选

类型

说明

function-urn

是

String

函数URN地址

version

是

String

函数版本

invocation-type

是

String

函数调用类型，支持async、sync

timeout

否

Number

函数超时时间，单位毫秒，缺省值为5000，取值范围为1 ~ 60000

6.5 x-apigateway-backend.mockEndpoints

含义：API网关定义的MOCK类型API后端服务定义。

作用域：x-apigateway-backend

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      parameters:
        - name: "X-Auth-Token"
          description: "认证token"
          type: "string"
          in: "header"
          required: true
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "MOCK"
        mockEndpoints:
          result-content: "mocked"
表9 参数说明

参数

是否必选

类型

说明

result-content

是

String

MOCK返回结果

7 x-apigateway-backend-policies

含义：API网关定义的API后端策略。

作用域：Operation Object

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"
表10 参数说明

参数

是否必选

类型

说明

type

是

String

后端服务类型，支持HTTP、HTTP-VPC、FUNCTION、MOCK

name

是

String

后端策略名称

parameters

否

x-apigateway-backend.parameters

后端参数定义

httpEndpoints

否

x-apigateway-backend.httpEndpoints

HTTP类型服务定义

httpVpcEndpoints

否

x-apigateway-backend.httpVpcEndpoints

HTTP-VPC类型服务定义

functionEndpoints

否

x-apigateway-backend.functionEndpoints

FUNCTION类型服务定义

mockEndpoints

否

x-apigateway-backend.mockEndpoints

MOCK类型服务定义

conditions

是

x-apigateway-backend-policies.conditions

策略条件数组

7.1 x-apigateway-backend-policies.conditions

含义：API网关定义的API后端策略条件。

作用域：x-apigateway-backend-policies

示例：

paths:
  '/users/{userId}':
    get:
      produces:
        - "application/json"
      responses:
        default:
          description: "default response"
      x-apigateway-request-type: "public"
      x-apigateway-backend:
        type: "backend endpoint type"
      x-apigateway-backend-policies:
        - type: "backend endpoint type"
          name: "backend policy name"
          conditions: 
            - type: "equal/enum/pattern",
              value: "string",
              origin: "source/request_parameter",
              parameter_name: "string"
表11 参数说明

参数

是否必选

类型

说明

type

是

String

策略条件类型，支持equal、enum、pattern

value

是

String

策略条件值

origin

是

String

策略条件输入来源，支持source、request

parameter

否

String

策略条件输入来源为request时，请求入参的名称

8 x-apigateway-ratelimit

含义：引用流控策略。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-ratelimit: 'customRatelimitName'

9 x-apigateway-ratelimits

含义：流控策略名称与关联策略映射。

作用域：Swagger Object

示例：

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: second/minute/hour
    shared: true
    special: 
      - type: APP
        limit: 100
        instance: xxxxxxxxx
表12 参数说明

参数

是否必选

类型

说明

customRatelimitName

否

x-apigateway-ratelimits.policy

指定名称的流控策略。

要使用该策略，将x-apigateway-ratelimit属性值引用为该策略名称。

9.1 x-apigateway-ratelimits.policy

含义：流控策略定义。

作用域：x-apigateway-ratelimits

示例：

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxx
表13 参数说明

参数

是否必选

类型

说明

api-limit

是

Number

API访问次数限制

user-limit

否

Number

用户访问次数限制

app-limit

否

Number

应用访问次数限制

ip-limit

否

Number

源IP访问次数限制

interval

是

Number

流控策略时间周期

unit

是

String

流控策略时间周期单位，支持SECOND、MINUTE、HOUR、DAY

shared

否

Boolean

是否共享流控策略

special

否

x-apigateway-ratelimits.policy.special

对象数组

特殊流控策略

9.2 x-apigateway-ratelimits.policy.special

含义：特殊流控策略定义。

作用域：x-apigateway-ratelimits.policy

示例：

x-apigateway-ratelimits:
  customRatelimitName:
    api-limit: 200
    app-limit: 200
    user-limit: 200
    ip-limit: 200
    interval: 1
    unit: MINUTE
    shared: false
    special: 
      - type: USER
        limit: 100
        instance: xxxxxxxx
表14 参数说明

参数

是否必选

类型

说明

type

是

String

特殊流控策略类型，支持APP、USER

limit

是

Number

访问次数

instance

是

String

特殊APP或USER的对象标识

10 x-apigateway-access-control

含义：引用访问控制策略。

作用域：Operation Object

示例：

paths:
  '/path':
    get:
      x-apigateway-access-control: 'customAccessControlName'

11 x-apigateway-access-controls

含义：访问控制策略名称与关联策略映射。

作用域：Swagger Object

示例：

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16
表15 参数说明

参数

是否必选

类型

说明

customAccessControlName

否

x-apigateway-access-controls.policy

指定名称的访问控制策略。

要使用该策略，将x-apigateway-access-control属性值引用为该策略名称。

11.1 x-apigateway-access-controls.policy

含义：访问控制策略定义。

作用域：x-apigateway-access-controls

示例：

x-apigateway-access-controls:
  customAccessControlName:
    acl-type: "DENY"
    entity-type: "IP"
    value: 127.0.0.1,192.168.0.1/16
表16 参数说明

参数

是否必选

类型

说明

acl-type

是

String

访问控制行为，支持PERMIT、DENY

entity-type

是

String

访问控制对象，仅支持IP

value

是

String

访问控制策略值，多个值以“,”间隔
父主题： 导入导出API