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,
    "ResultSample": String,
    "ResultType": String,
    "ApiName": String,
    "FailResultSample": String,
    "ConstParameters": List,
    "GroupId": String,
    "ServiceParametersMap": List,
    "RequestParameters": List,
    "AppCodeAuthType": String
  }
}

属性

属性名称 类型 必须 允许更新 描述 约束
ServiceConfig Map 网关向后端服务发送API请求的相关配置项
RequestConfig Map Consumer向网关发送API请求的相关配置项
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 后端服务返回的错误码示例
Description String API描述信息 最多支持180个字符
SystemParameters List API的系统参数
ServiceParameters List 网关向后端服务发送API请求的参数描述
OpenIdConnectConfig Map 第三方账号认证OpenID Connect相关配置项
AuthType String

API安全认证类型

取值:
  • APP:只允许已授权的App调用。
  • ANONYMOUS:允许匿名调用,网关不会对调用者做身份认证,也无法根据用户需求设置流量控制。若所在分组要上架云市场,建议将该API转移至其他分组,或将类型设置为私有,或选择阿里云App认证方式。
  • APPOPENID:支持第三方账号认证OpenID Connect,而且只允许已授权的App调用。当设置此项时,参数OpenIdConnectConfig必须指定。
ServiceParametersMap List Consumer向网关发送请求的参数和网关向后端服务发送请求的参数的映射关系
FailResultSample String 后端服务失败返回应答的示例
RequestParameters List Consumer向网关发送API请求的参数描述
ConstParameters List 指定API的常量参数
AppCodeAuthType String AppCode认证方式 AuthType取值为APP时该参数生效,取值:
  • DEFAULT(默认值):随分组设置
  • DISABLE:不允许
  • HEADER:允许AppCode的Header认证
  • HEADER_QUERY:允许AppCode的Header及Query认证

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

MockStatusCode Integer 状态码 以兼容HTTP 1.1 Response Status Code的格式返回
MockHeaders List

启用Mock时,自定义的Mock响应头相关信息,详情请参见MockHeader

ServiceTimeOut Integer 后端服务超时时间 单位:毫秒
ServiceAddress String 调用后端服务地址 例如:后端服务完全地址为 http://api.a.com:8080/object/add?key1=value1&key2=value2,后端服务地址是指 http://api.a.com:8080
ServicePath String 调用后端服务路径 例如:后端服务完全地址为 http://api.a.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
  • FALSE(默认值)
MockResult String 启用Mock模式时返回的结果
VpcConfig Map 启用VPC通道时的相关配置项

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://api.a.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,9或A,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
}

FunctionComputeConfig属性

属性名称 类型 必须 允许更新 描述 约束
fcRegionId String 函数计算所在地域
roleArn String RAM授权给API网关访问函数计算的ARN
serviceName String 函数计算定义的ServiceName
functionName String 函数计算定义的FunctionName
qualifier String 函数计算的别名

MockHeaders语法

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

MockHeaders属性

属性名称 类型 必须 允许更新 描述 约束
HeaderName String 响应头名称
HeaderValue String 响应头值

返回值

Fn::GetAtt

ApiId:指定的API编号。

示例

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "GroupId": {
      "Type": "String",
      "Default": "xxxxec10b1b4dc7a2e6ba8ca3xxxx",
      "Description": "操作的分组"
    }
  },
  "Resources": {
    "API": {
      "Type": "ALIYUN::ApiGateway::Api",
      "Properties": {
        "GroupId": {
          "Ref": "GroupId"
        },
        "ApiName": "API_test",
        "Visibility": "PRIVATE",
        "Description": "keep for test",
        "AuthType": "APP",
        "RequestConfig": {
          "RequestHttpMethod": "GET",
          "RequestProtocol": "HTTP",
          "BodyFormat": "FORM",
          "PostBodyDescription": "k:v",
          "RequestPath": "/demo_test_345"
        },
        "ServiceConfig": {
          "ServiceProtocol": "HTTP",
          "ContentTypeValue": "application/x-www-form-urlencoded; charset=UTF-8",
          "Mock": "FALSE",
          "MockResult": "Nothing",
          "ServiceTimeOut": 20000,
          "ServiceAddress": "https://mytest.cn",
          "ServicePath": "/data",
          "ServiceHttpMethod": "GET",
          "ContentTypeCatagory": "DEFAULT",
          "ServiceVpcEnable": "FALSE"
        },
        "RequestParameters": [
          {
            "Required": "OPTION",
            "ParameterType": "String",
            "ApiParameterName": "x-demo",
            "DocShow": "PUBLIC",
            "DefaultValue": "x-demo-val",
            "Location": "HEAD",
            "DocOrder": 0
          },
          {
            "Required": "OPTION",
            "ParameterType": "String",
            "ApiParameterName": "y-demo",
            "DocShow": "PUBLIC",
            "DefaultValue": "y-demo-val",
            "Location": "QUERY",
            "DocOrder": 1
          }
        ],
        "ServiceParameters": [
          {
            "ServiceParameterName": "x-demo-ser",
            "ParameterType": "STRING",
            "Location": "HEAD"
          },
          {
            "ServiceParameterName": "y-demo-ser",
            "ParameterType": "STRING",
            "Location": "QUERY"
          }
        ],
        "ServiceParametersMap": [
          {
            "ServiceParameterName": "x-demo-ser",
            "RequestParameterName": "x-demo"
          },
          {
            "ServiceParameterName": "y-demo-ser",
            "RequestParameterName": "y-demo"
          }
        ],
        "ResultType": "JSON",
        "ResultSample": "demo sample result",
        "FailResultSample": "demo faile sample result",
        "ErrorCodeSamples": [
          {
            "Description": "??",
            "Message": "Missing",
            "Code": "400"
          },
          {
            "Description": "???",
            "Message": "Missing",
            "Code": "401"
          }
        ],
        "SystemParameters": [
          {
            "Description": "ClientIP",
            "ServiceParameterName": "demo-sys-ser",
            "DemoValue": "192.168.XX.XX",
            "Location": "HEAD",
            "ParameterName": "CaClientIp"
          }
        ],
        "ConstParameters": [
          {
            "Description": "demo_const",
            "ServiceParameterName": "demo-const-ser",
            "Location": "HEAD",
            "ConstValue": "demo_const_val"
          }
        ]
      }
    }
  }
}