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

属性

属性名称 类型 必须 允许更新 描述 约束
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认证。

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。

示例

  • JSON格式

    {
      "ROSTemplateFormatVersion": "2015-09-01",
      "Description": "Test ApiGateway Api",
      "Parameters": {
        "RoleName": {
          "Type": "String",
          "Default": "mytest"
        },
        "PolicyName": {
          "Type": "String",
          "Default": "mytest"
        },
        "InstanceId": {
          "Type": "String",
          "AllowedValues": [
            "api-shared-vpc-001",
            "api-shared-classic-001"
          ],
          "Default": "api-shared-vpc-001"
        },
        "GroupName": {
          "Type": "String",
          "Default": "mytest"
        },
        "ServiceName": {
          "Type": "String",
          "Default": "mytest"
        },
        "ApiName": {
          "Type": "String",
          "Default": "mytest"
        },
        "AppName": {
          "Type": "String",
          "Default": "mytest"
        }
      },
      "Resources": {
        "RamRole": {
          "Type": "ALIYUN::RAM::Role",
          "Properties": {
            "RoleName": {
              "Ref": "RoleName"
            },
            "Policies": [
              {
                "PolicyName": {
                  "Ref": "PolicyName"
                },
                "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": {
              "Ref": "ServiceName"
            },
            "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": {
              "Ref": "InstanceId"
            },
            "GroupName": {
              "Ref": "GroupName"
            }
          }
        },
        "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": {
              "Ref": "ApiName"
            },
            "GroupId": {
              "Fn::GetAtt": [
                "Group",
                "GroupId"
              ]
            }
          }
        },
        "App": {
          "Type": "ALIYUN::ApiGateway::App",
          "Properties": {
            "Description": "Test Create App",
            "AppName": {
              "Ref": "AppName"
            }
          }
        }
      },
      "Outputs": {
      }
    }
                
  • YAML格式

    ROSTemplateFormatVersion: '2015-09-01'
    Description: Test ApiGateway Api
    Parameters:
      RoleName:
        Type: String
        Default: mytest
      PolicyName:
        Type: String
        Default: mytest
      InstanceId:
        Type: String
        AllowedValues:
          - api-shared-vpc-001
          - api-shared-classic-001
        Default: api-shared-vpc-001
      GroupName:
        Type: String
        Default: mytest
      ServiceName:
        Type: String
        Default: mytest
      ApiName:
        Type: String
        Default: mytest
      AppName:
        Type: String
        Default: mytest
    Resources:
      RamRole:
        Type: ALIYUN::RAM::Role
        Properties:
          RoleName:
            Ref: RoleName
          Policies:
            - PolicyName:
                Ref: PolicyName
              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:
            Ref: ServiceName
          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:
            Ref: InstanceId
          GroupName:
            Ref: GroupName
      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:
            Ref: ApiName
          GroupId:
            Fn::GetAtt:
              - Group
              - GroupId
      App:
        Type: ALIYUN::ApiGateway::App
        Properties:
          Description: Test Create App
          AppName:
            Ref: AppName
    Outputs: {}

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