文档

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
  }
}

属性

属性名称

类型

必须

允许更新

描述

约束

ApiName

String

API名称。

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

说明

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

GroupId

String

API分组编号。

RequestConfig

Map

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

更多信息,请参见RequestConfig属性

ResultSample

String

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

ResultType

String

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

取值:

  • JSON(默认值)

  • TEXT

  • BINARY

  • XML

  • PASSTHROUGH

ServiceConfig

Map

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

更多信息,请参见ServiceConfig属性

Visibility

String

API是否公开。

取值:

  • PUBLIC:公开。

  • PRIVATE:不公开。

AllowSignatureMethod

String

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

取值:

  • HmacSHA256(默认值)

  • HmacSHA1

AppCodeAuthType

String

AppCode认证方式。

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

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

  • DISABLE:不允许。

  • HEADER:允许AppCode的Header认证。

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

AuthType

String

API安全认证类型。

取值:

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

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

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

ConstParameters

List

指定API的常量参数。

更多信息,请参见ConstParameters属性

Description

String

API描述信息。

最多支持180个字符。

DisableInternet

Boolean

是否禁止公网调用API。

取值:

  • true:禁止。

  • false:允许。

ErrorCodeSamples

List

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

更多信息,请参见ErrorCodeSamples属性

FailResultSample

String

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

ForceNonceCheck

Boolean

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

取值:

  • true:强制检查。

  • false:不强制检查。

OpenIdConnectConfig

Map

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

更多信息,请参见OpenIdConnectConfig属性

RequestParameters

List

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

更多信息,请参见RequestParameters属性

ResultBodyModel

String

API的返回结果。

ResultDescriptions

String

结果描述。

ServiceParameters

List

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

更多信息,请参见ServiceParameters属性

ServiceParametersMap

List

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

更多信息,请参见ServiceParametersMap属性

SystemParameters

List

API的系统参数。

更多信息,请参见SystemParameters属性

Tags

List

标签。

最多支持添加20个标签。

更多信息,请参见Tags属性

WebSocketApiType

String

双向通信API类型。

取值:

  • COMMON:普通API。

  • REGISTER:注册API。

  • UNREGISTER:注销API。

  • NOTIFY:下行通知。

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属性

属性名称

类型

必须

允许更新

描述

约束

Code

String

错误码。

Message

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属性

属性名称

类型

必须

允许更新

描述

约束

ContentTypeCatagory

String

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

取值:

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

  • CUSTOM:自定义。

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

ContentTypeValue

String

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

FunctionComputeConfig

Map

后端服务为函数计算。

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

更多信息,请参见FunctionComputeConfig属性

Mock

String

是否采取Mock模式。

取值:

  • TRUE:采取Mock模式。

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

MockHeaders

List

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

更多信息,请参见MockHeader

更多信息,请参见MockHeaders属性

MockResult

String

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

MockStatusCode

Integer

状态码。

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

ServiceAddress

String

后端服务地址。

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

ServiceHttpMethod

String

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

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEAD

  • TRACE

  • PATCH

  • CONNECT

  • OPTIONS

  • ANY

ServicePath

String

后端服务路径。

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

ServiceProtocol

String

后端服务协议类型。

取值:

  • HTTP

  • HTTPS

  • FunctionCompute

ServiceTimeOut

Integer

后端服务超时时间。

单位:毫秒。

ServiceVpcEnable

String

是否使用专有网络。

取值:

  • TRUE:使用。

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

VpcConfig

Map

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

更多信息,请参见VpcConfig属性

VpcConfig语法

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

VpcConfig属性

属性名称

类型

必须

允许更新

描述

约束

InstanceId

String

专用网络中的实例ID。

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

Port

Integer

实例对应的端口号。

VpcId

String

专有网络ID。

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

后端参数名称。

DemoValue

String

示例。

Description

String

参数描述。

ServiceParameters语法

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

ServiceParameters属性

属性名称

类型

必须

允许更新

描述

约束

Location

String

参数位置。

取值:

  • BODY

  • HEAD

  • QUERY

  • PATH

ParameterType

String

后端参数数据类型。

取值:

  • STRING:字符。

  • NUMBER:数值。

  • BOOLEAN:布尔。

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必须指定。

IdTokenParamName

String

Token对应的参数名称。

PublicKey

String

公钥。

PublicKeyId

String

公钥ID。

RequestConfig语法

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

RequestConfig属性

属性名称

类型

必须

允许更新

描述

约束

RequestHttpMethod

String

请求方式。

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEADER

  • TRACE

  • PATCH

  • OPTIONS

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

BodyFormat

String

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

取值:

  • FORM:表单形式。

  • STREAM:字节流形式。

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

PostBodyDescription

String

请求体的描述。

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属性

属性名称

类型

必须

允许更新

描述

约束

ApiParameterName

String

参数名称。

Location

String

参数位置。

取值:

  • BODY

  • HEAD

  • QUERY

  • PATH

ParameterType

String

参数类型。

取值:

  • String:字符。

  • Int:整型。

  • Long:长整型。

  • Float:单精度浮点型。

  • Double:双精度浮点型。

  • Boolean:布尔。

Required

String

是否必填。

取值:

  • REQUIRED:必填。

  • OPTIONAL:选填。

DefaultValue

String

默认值。

DemoValue

String

示例值。

Description

String

参数描述。

DocOrder

Integer

文档中的顺序。

DocShow

String

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

取值:

  • PUBLIC

  • PRIVATE

EnumValue

String

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

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

JsonScheme

String

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

MaxLength

Integer

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

MaxValue

Integer

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

MinLength

Integer

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

MinValue

Integer

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

RegularExpression

String

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

ConstParameters语法

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

ConstParameters属性

属性名称

类型

必须

允许更新

描述

约束

ConstValue

String

参数值。

Location

String

参数位置。

取值:

  • BODY

  • HEAD(默认值)

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属性

属性名称

类型

必须

允许更新

描述

约束

ContentTypeCatagory

String

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

取值:

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

  • CUSTOM:自定义。

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

ContentTypeValue

String

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

FcBaseUrl

String

触发器地址。

http://https://开头。

FcRegionId

String

函数计算所在地域ID。

FcType

String

函数类型。

取值:

  • FCEvent(默认值)。

  • HttpTrigger。

FunctionName

String

函数计算定义的FunctionName。

Method

String

HTTP请求方式。

取值:

  • GET(默认值)

  • POST

  • DELETE

  • PUT

  • HEAD

  • PATCH

  • OPTIONS

  • ANY

OnlyBusinessPath

Boolean

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

取值:

  • true

  • false

Path

String

后端请求路径。

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

Qualifier

String

函数计算的别名。

RoleArn

String

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

ServiceName

String

函数计算定义的ServiceName。

MockHeaders语法

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

MockHeaders属性

属性名称

类型

必须

允许更新

描述

约束

HeaderName

String

响应头名称。

HeaderValue

String

响应头值。

返回值

Fn::GetAtt

ApiId:API ID。

示例

说明

请您按照实际情况更改下列脱敏的参数取值,例如InstanceId。

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-***
      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-***",
        "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": {
  }
}