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