文档

ALIYUN::ApiGateway::Api

更新时间:

ALIYUN::ApiGateway::Api类型用于创建API。

语法

{
  "Type": "ALIYUN::ApiGateway::Api",
  "Properties": {
    "ErrorCodeSamples": List,
    "Description": String,
    "ServiceConfig": Map,
    "SystemParameters": List,
    "ServiceParameters": List,
    "OpenIdConnectConfig": Map,
    "RequestConfig": Map,
    "AuthType": String,
    "Visibility": String,
    "Tags": List,
    "ResultSample": String,
    "ResultType": String,
    "ApiName": String,
    "FailResultSample": String,
    "DisableInternet": Boolean,
    "ForceNonceCheck": Boolean,
    "ConstParameters": List,
    "GroupId": String,
    "ServiceParametersMap": List,
    "RequestParameters": List,
    "AppCodeAuthType": String,
    "ResultBodyModel": String,
    "AllowSignatureMethod": String,
    "WebSocketApiType": String,
    "ResultDescriptions": String
  }
}

属性

属性名称

类型

必须

允许更新

描述

约束

ServiceConfig

Map

网关向后端服务发送API请求的相关配置项。

更多信息,请参见ServiceConfig属性

RequestConfig

Map

Consumer向网关发送API请求的相关配置项。

更多信息,请参见RequestConfig属性

Visibility

String

API是否公开。

取值:

  • PUBLIC:公开。

  • PRIVATE:不公开。

ResultSample

String

后端服务返回应答的示例。

ResultType

String

后端服务返回应答的格式。

取值:

  • JSON(默认值)

  • TEXT

  • BINARY

  • XML

  • PASSTHROUGH

ApiName

String

API名称。

长度为4~50个字符。必须以英文字母或汉字开头。可包含英文字母、汉字、数字和下划线(_)。

说明

API分组内的API名称不允许重复。

GroupId

String

API分组编号。

ErrorCodeSamples

List

后端服务返回的错误码示例。

更多信息,请参见ErrorCodeSamples属性

Description

String

API描述信息。

最多支持180个字符。

DisableInternet

Boolean

是否禁止公网调用API。

取值:

  • true:禁止。

  • false:允许。

ForceNonceCheck

Boolean

请求时是否强制检查X-Ca-Nonce。

取值:

  • true:强制检查。

  • false:不强制检查。

Tags

List

标签。

最多支持添加20个标签。

更多信息,请参见Tags属性

SystemParameters

List

API的系统参数。

更多信息,请参见SystemParameters属性

ServiceParameters

List

网关向后端服务发送API请求的参数描述。

更多信息,请参见ServiceParameters属性

OpenIdConnectConfig

Map

第三方账号认证OpenID Connect相关配置项。

更多信息,请参见OpenIdConnectConfig属性

AuthType

String

API安全认证类型。

取值:

  • APP:只允许已授权的App调用。

  • ANONYMOUS:允许匿名调用,网关不会对调用者做身份认证,也无法根据用户需求设置流量控制。若所在分组要上架云市场,建议将该API转移至其他分组,或将类型设置为私有,或选择阿里云App认证方式。

  • APPOPENID:支持第三方账号认证OpenID Connect,而且只允许已授权的App调用。当设置此项时,参数OpenIdConnectConfig必须指定。

ServiceParametersMap

List

Consumer向网关发送请求的参数和网关向后端服务发送请求的参数的映射关系。

更多信息,请参见ServiceParametersMap属性

FailResultSample

String

后端服务失败返回应答的示例。

RequestParameters

List

Consumer向网关发送API请求的参数描述。

更多信息,请参见RequestParameters属性

ConstParameters

List

指定API的常量参数。

更多信息,请参见ConstParameters属性

AppCodeAuthType

String

AppCode认证方式。

AuthType取值为APP时该参数生效,取值:

  • DEFAULT(默认值):随分组设置。

  • DISABLE:不允许。

  • HEADER:允许AppCode的Header认证。

  • HEADER_QUERY:允许AppCode的Header及Query认证。

ResultBodyModel

String

API的返回结果。

AllowSignatureMethod

String

当AuthType为APP认证时,需要传该值明确签名算法。

取值:

  • HmacSHA256(默认值)

  • HmacSHA1

WebSocketApiType

String

双向通信API类型。

取值:

  • COMMON:普通API。

  • REGISTER:注册API。

  • UNREGISTER:注销API。

  • NOTIFY:下行通知。

ResultDescriptions

String

结果描述。

Tags语法

"Tags": [
  {
    "Key": String,
    "Value": String
  }
]  

Tags属性

属性名称

类型

必须

允许更新

描述

约束

Key

String

标签键。

长度为1~128个字符,不能以aliyunacs:开头,不能包含http://或者https://

Value

String

标签值。

长度为0~128个字符,不能以aliyunacs:开头,不能包含http://或者https://

ErrorCodeSamples语法

"ErrorCodeSamples": [
  {
    "Message": String,
    "Code": String,
    "Description": String
  }
]

ErrorCodeSamples属性

属性名称

类型

必须

允许更新

描述

约束

Message

String

错误信息。

Code

String

错误码。

Description

String

错误描述。

ServiceConfig语法

"ServiceConfig": {
  "ServiceTimeOut": Integer,
  "FunctionComputeConfig": Map,
  "VpcConfig": Map,
  "MockResult": String,
  "MockStatusCode": Integer,
  "ServiceHttpMethod": String,
  "ServiceProtocol": String,
  "ServiceVpcEnable": String,
  "ServiceAddress": String,
  "ContentTypeValue": String,
  "MockHeaders": List,
  "ContentTypeCatagory": String,
  "ServicePath": String,
  "Mock": String
}

ServiceConfig属性

属性名称

类型

必须

允许更新

描述

约束

FunctionComputeConfig

Map

后端服务为函数计算。

函数计算后端相关的配置项,请参见FunctionComputeConfig

更多信息,请参见FunctionComputeConfig属性

MockStatusCode

Integer

状态码。

以兼容HTTP 1.1 Response Status Code的格式返回。

MockHeaders

List

启用Mock时,自定义的Mock响应头相关信息。

更多信息,请参见MockHeader

更多信息,请参见MockHeaders属性

ServiceTimeOut

Integer

后端服务超时时间。

单位:毫秒。

ServiceAddress

String

后端服务地址。

例如:后端服务完整地址为http://example.com:8080/object/add?key1=value1&key2=value2,后端服务地址指http://example.com:8080

ServicePath

String

后端服务路径。

例如:后端服务完全地址为 http://example.com:8080/object/add?key1=value1&key2=value2, 后端服务路径指/object/add

ServiceProtocol

String

后端服务协议类型。

取值:

  • HTTP

  • HTTPS

  • FunctionCompute

ServiceVpcEnable

String

是否使用专有网络。

取值:

  • TRUE:使用。

  • FALSE(默认值):不使用。

ServiceHttpMethod

String

调用后端服务HTTP协议时的方法。

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEAD

  • TRACE

  • PATCH

  • CONNECT

  • OPTIONS

  • ANY

ContentTypeCatagory

String

调用后端HTTP服务时,ContentType头的取值策略。

取值:

  • DEFAULT:使用API网关默认值。

  • CUSTOM:自定义。

  • CLIENT(默认值):使用客户端上行的ContentType头。

ContentTypeValue

String

当后端服务是HTTP,ContentTypeCatagory取值为DEFAULT或CUSTOM时,ContentType头的取值。

Mock

String

是否采取Mock模式。

取值:

  • TRUE:采取Mock模式。

  • FALSE(默认值):不采取Mock模式。

MockResult

String

启用Mock模式时返回的结果。

VpcConfig

Map

启用VPC通道时的相关配置项。

更多信息,请参见VpcConfig属性

VpcConfig语法

"VpcConfig": {
  "InstanceId": String,
  "VpcId": String,
  "Port": Integer
}

VpcConfig属性

属性名称

类型

必须

允许更新

描述

约束

InstanceId

String

专用网络中的实例ID。

目前只支持ECS实例和SLB实例。

VpcId

String

专有网络ID。

Port

Integer

实例对应的端口号。

SystemParameters语法

"SystemParameters": [
  {
    "DemoValue": String,
    "ParameterName": String,
    "ServiceParameterName": String,
    "Location": String,
    "Description": String
  }
]

SystemParameters属性

属性名称

类型

必须

允许更新

描述

约束

Location

String

参数位置。

ParameterName

String

系统参数名称。

取值:

  • CaClientIp

  • CaDomain

  • CaRequestHandleTime

  • CaAppId

  • CaRequestId

  • CaHttpSchema

  • CaProxy

ServiceParameterName

String

后端参数名称。

Description

String

参数描述。

DemoValue

String

示例。

ServiceParameters语法

"ServiceParameters": [
  {
    "ParameterType": String,
    "Location": String,
    "ServiceParameterName": String
  }
]

ServiceParameters属性

属性名称

类型

必须

允许更新

描述

约束

ParameterType

String

后端参数数据类型。

取值:

  • STRING:字符。

  • NUMBER:数值。

  • BOOLEAN:布尔。

Location

String

参数位置。

取值:

  • BODY

  • HEAD

  • QUERY

  • PATH

ServiceParameterName

String

后端参数名称。

OpenIdConnectConfig语法

"OpenIdConnectConfig": {
  "OpenIdApiType": String,
  "PublicKey": String,
  "PublicKeyId": String,
  "IdTokenParamName": String
}

OpenIdConnectConfig属性

属性名称

类型

必须

允许更新

描述

约束

OpenIdApiType

String

OpenID Connect模式。

取值:

  • IDTOKEN:先获取授权API,再颁发Token。当设置此项时,参数PublicKeyId和PublicKey必须指定。

  • BUSINESS:先获取业务API,再进行Token验证。当设置此项时,参数IdTokenParamName必须指定。

PublicKey

String

公钥。

PublicKeyId

String

公钥ID。

IdTokenParamName

String

Token对应的参数名称。

RequestConfig语法

"RequestConfig": {
  "RequestMode": String,
  "RequestPath": String,
  "PostBodyDescription": String,
  "RequestProtocol": String,
  "RequestHttpMethod": String,
  "BodyFormat": String
}

RequestConfig属性

属性名称

类型

必须

允许更新

描述

约束

RequestMode

String

请求模式。

取值:

  • MAPPING(默认值):入参映射。

  • PASSTHROUGH:入参透传。

RequestPath

String

请求地址。

例如:API的完全地址为http://example.com:8080/object/add?key1=value1&key2=value2,请求地址指/object/add

RequestProtocol

String

API支持的协议类型。

取值:

  • HTTP

  • HTTPS

多个协议类型以半角逗号(,)隔开,例如:HTTP,HTTPS

RequestHttpMethod

String

请求方式。

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEADER

  • TRACE

  • PATCH

  • OPTIONS

PostBodyDescription

String

请求体的描述。

BodyFormat

String

POST、PUT或PATCH请求时,表示数据以何种方式传递给服务器。

取值:

  • FORM:表单形式。

  • STREAM:字节流形式。

当RequestMode值为MAPPING时,该参数有效。

ServiceParametersMap语法

"ServiceParametersMap": [
  {
    "RequestParameterName": String,
    "ServiceParameterName": String
  }
]

ServiceParametersMap属性

属性名称

类型

必须

允许更新

描述

约束

RequestParameterName

String

前端参数名称。

该参数取值必须存在于RequestParameters中,即RequestParameters.ApiParameterName。

ServiceParameterName

String

后端参数名称。

RequestParameters语法

"RequestParameters": [
  {
    "ParameterType": String,
    "Required": String,
    "Description": String,
    "DemoValue": String,
    "MinLength": Integer,
    "DefaultValue": String,
    "RegularExpression": String,
    "MaxValue": Integer,
    "MinValue": Integer,
    "JsonScheme": String,
    "ApiParameterName": String,
    "Location": String,
    "DocShow": String,
    "MaxLength": Integer,
    "EnumValue": String,
    "DocOrder": Integer
  }
]

RequestParameters属性

属性名称

类型

必须

允许更新

描述

约束

ParameterType

String

参数类型。

取值:

  • String:字符。

  • Int:整型。

  • Long:长整型。

  • Float:单精度浮点型。

  • Double:双精度浮点型。

  • Boolean:布尔。

Required

String

是否必填。

取值:

  • REQUIRED:必填。

  • OPTIONAL:选填。

ApiParameterName

String

参数名称。

Location

String

参数位置。

取值:

  • BODY

  • HEAD

  • QUERY

  • PATH

RegularExpression

String

当ParameterType为String时,该参数通过正则表达式进行验证。

Description

String

参数描述。

DefaultValue

String

默认值。

MaxLength

Integer

当ParameterType为 String时,参数的最大长度限定。

MinLength

Integer

当ParameterType为String时,参数的最小长度限定。

MaxValue

Integer

当ParameterType为Int、Long、Float、Double 时,参数的最大值限定。

MinValue

Integer

当ParameterType为 Int、Long、Float、Double 时,参数的最小值限定。

EnumValue

String

当ParameterType为Int、Long、Float、Double或String时,允许输入的散列值。

不同的值用半角逗号(,)分隔,例如:1,2,3,4,9A,B,C,E,F

JsonScheme

String

当ParameterType为String时,该参数进行JSON验证。

DocOrder

Integer

文档中的顺序。

DocShow

String

API网关生成的SDK或文档是否可见。

取值:

  • PUBLIC

  • PRIVATE

DemoValue

String

示例值。

ConstParameters语法

"ConstParameters": [
  {
    "ConstValue": String,
    "ServiceParameterName": String,
    "Description": String,
    "Location": String
  }
]

ConstParameters属性

属性名称

类型

必须

允许更新

描述

约束

Location

String

参数位置。

取值:

  • BODY

  • HEAD(默认值)

ConstValue

String

参数值。

ServiceParameterName

String

后端参数名称。

Description

String

参数描述。

FunctionComputeConfig语法

"FunctionComputeConfig": {
 "FcRegionId": String,
 "RoleArn": String,
 "ServiceName": String,
 "FunctionName": String,
 "Qualifier": String,
 "ContentTypeValue": String,
 "ContentTypeCatagory": String,
 "FcBaseUrl": String,
 "FcType": String,
 "Method": String,
 "OnlyBusinessPath": Boolean,
 "Path": String
}

FunctionComputeConfig属性

属性名称

类型

必须

允许更新

描述

约束

FcRegionId

String

函数计算所在地域ID。

RoleArn

String

RAM授权给API网关访问函数计算的ARN。

ServiceName

String

函数计算定义的ServiceName。

FunctionName

String

函数计算定义的FunctionName。

Qualifier

String

函数计算的别名。

ContentTypeCatagory

String

调用后端服务HTTP服务时,ContentType头的取值策略。

取值:

  • DEFAULT:使用API网关默认的值。

  • CUSTOM:自定义。

  • CLIENT(默认值):使用客户端上行的ContentType的头。

ContentTypeValue

String

调用后端HTTP服务,ContentTypeCatagory的值为DEFAULT或者CUSTOM时,ContentType头的取值。

FcBaseUrl

String

触发器地址。

http://https://开头。

FcType

String

函数类型。

取值:

  • FCEvent(默认值)。

  • HttpTrigger。

Method

String

HTTP请求方式。

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEAD

  • PATCH

  • OPTIONS

  • ANY

OnlyBusinessPath

Boolean

是否只传递自定义的后端请求路径给后端。

取值:

  • true

  • false

Path

String

后端请求路径。

参数必须放在方括号中,例如:/ getUserInfo / [userId]

MockHeaders语法

"MockHeaders": [
  {
    "HeaderValue": String,
    "HeaderName": String
  }
]    

MockHeaders属性

属性名称

类型

必须

允许更新

描述

约束

HeaderName

String

响应头名称。

HeaderValue

String

响应头值。

返回值

Fn::GetAtt

ApiId:API ID。

示例

YAML格式

ROSTemplateFormatVersion: '2015-09-01'
Description: Test ApiGateway Api
Parameters: {}
Resources:
  RamRole:
    Type: ALIYUN::RAM::Role
    Properties:
      RoleName: TestRole
      Policies:
        - PolicyName: TestPolicy
          PolicyDocument:
            Version: '1'
            Statement:
              - Action:
                  - fc:InvokeFunction
                Resource:
                  - '*'
                Effect: Allow
      AssumeRolePolicyDocument:
        Version: '1'
        Statement:
          - Action: sts:AssumeRole
            Effect: Allow
            Principal:
              Service:
                - apigateway.aliyuncs.com
  FCService:
    Type: ALIYUN::FC::Service
    Properties:
      ServiceName: TestService
      InternetAccess: true
  Function:
    Type: ALIYUN::FC::Function
    DependsOn: FCService
    Properties:
      Handler: index.handler
      Runtime: python3
      Code:
        SourceCode: "def handler(event, context):\n\treturn {'isBase64Encode': False, 'statusCode': 200, 'body': 'Hello World!', 'headers': {'Content-type': 'aplication/json'}}\n"
      FunctionName: mytest
      ServiceName:
        Fn::GetAtt:
          - FCService
          - ServiceName
      MemorySize: 128
  Group:
    Type: ALIYUN::ApiGateway::Group
    Properties:
      InstanceId: api-shared-vpc-001
      GroupName: TestGroup
  Api:
    DependsOn:
      - RamRole
      - Group
    Type: ALIYUN::ApiGateway::Api
    Properties:
      AppCodeAuthType: HEADER_QUERY
      AuthType: APP
      ServiceConfig:
        FunctionComputeConfig:
          fcRegionId:
            Ref: ALIYUN::Region
          qualifier: LATEST
          roleArn:
            Fn::GetAtt:
              - RamRole
              - Arn
          serviceName:
            Fn::GetAtt:
              - FCService
              - ServiceName
          functionName:
            Fn::GetAtt:
              - Function
              - FunctionName
        ServiceProtocol: FunctionCompute
        ContentTypeCatagory: CLIENT
      RequestConfig:
        RequestMode: MAPPING
        RequestHttpMethod: POST
        RequestProtocol: HTTP,HTTPS
        RequestPath: /test
        BodyFormat: FORM
      ResultSample: ''
      Visibility: PRIVATE
      ResultType: JSON
      ApiName: TestApi
      GroupId:
        Fn::GetAtt:
          - Group
          - GroupId
  App:
    Type: ALIYUN::ApiGateway::App
    Properties:
      Description: Test Create App
      AppName: TestApp
Outputs: {}

JSON格式

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Description": "Test ApiGateway Api",
  "Parameters": {
  },
  "Resources": {
    "RamRole": {
      "Type": "ALIYUN::RAM::Role",
      "Properties": {
        "RoleName": "TestRole",
        "Policies": [
          {
            "PolicyName": "TestPolicy",
            "PolicyDocument": {
              "Version": "1",
              "Statement": [
                {
                  "Action": [
                    "fc:InvokeFunction"
                  ],
                  "Resource": [
                    "*"
                  ],
                  "Effect": "Allow"
                }
              ]
            }
          }
        ],
        "AssumeRolePolicyDocument": {
          "Version": "1",
          "Statement": [
            {
              "Action": "sts:AssumeRole",
              "Effect": "Allow",
              "Principal": {
                "Service": [
                  "apigateway.aliyuncs.com"
                ]
              }
            }
          ]
        }
      }
    },
    "FCService": {
      "Type": "ALIYUN::FC::Service",
      "Properties": {
        "ServiceName": "TestService",
        "InternetAccess": true
      }
    },
    "Function": {
      "Type": "ALIYUN::FC::Function",
      "DependsOn": "FCService",
      "Properties": {
        "Handler": "index.handler",
        "Runtime": "python3",
        "Code": {
          "SourceCode": "def handler(event, context):\n\treturn {'isBase64Encode': False, 'statusCode': 200, 'body': 'Hello World!', 'headers': {'Content-type': 'aplication/json'}}\n"
        },
        "FunctionName": "mytest",
        "ServiceName": {
          "Fn::GetAtt": [
            "FCService",
            "ServiceName"
          ]
        },
        "MemorySize": 128
      }
    },
    "Group": {
      "Type": "ALIYUN::ApiGateway::Group",
      "Properties": {
        "InstanceId": "api-shared-vpc-001",
        "GroupName": "TestGroup"
      }
    },
    "Api": {
      "DependsOn": [
        "RamRole",
        "Group"
      ],
      "Type": "ALIYUN::ApiGateway::Api",
      "Properties": {
        "AppCodeAuthType": "HEADER_QUERY",
        "AuthType": "APP",
        "ServiceConfig": {
          "FunctionComputeConfig": {
            "fcRegionId": {
              "Ref": "ALIYUN::Region"
            },
            "qualifier": "LATEST",
            "roleArn": {
              "Fn::GetAtt": [
                "RamRole",
                "Arn"
              ]
            },
            "serviceName": {
              "Fn::GetAtt": [
                "FCService",
                "ServiceName"
              ]
            },
            "functionName": {
              "Fn::GetAtt": [
                "Function",
                "FunctionName"
              ]
            }
          },
          "ServiceProtocol": "FunctionCompute",
          "ContentTypeCatagory": "CLIENT"
        },
        "RequestConfig": {
          "RequestMode": "MAPPING",
          "RequestHttpMethod": "POST",
          "RequestProtocol": "HTTP,HTTPS",
          "RequestPath": "/test",
          "BodyFormat": "FORM"
        },
        "ResultSample": "",
        "Visibility": "PRIVATE",
        "ResultType": "JSON",
        "ApiName": "TestApi",
        "GroupId": {
          "Fn::GetAtt": [
            "Group",
            "GroupId"
          ]
        }
      }
    },
    "App": {
      "Type": "ALIYUN::ApiGateway::App",
      "Properties": {
        "Description": "Test Create App",
        "AppName": "TestApp"
      }
    }
  },
  "Outputs": {
  }
}            

更多示例,请参见创建API、创建应用、为API授权应用的访问权限、发布API或快速切换API版本、创建后端签名密钥、绑定API与后端签名密钥、创建用户自定义的流控策略和为API绑定用户自定义流控的组合示例:JSON示例YAML示例

  • 本页导读 (1)
文档反馈