文档首页 > > 开发指南> 导入导出API> 扩展定义

扩展定义

分享
更新时间:2020/07/06 GMT+08:00

扩展定义表示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

访问控制策略值,多个值以“,”间隔

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

智能客服提问云社区提问