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,
    "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
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认证。

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://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语法

"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,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",
  "Parameters": {
    "RequestConfig": {
      "Type": "Json",
      "Description": "The configuration of the request"
    },
    "Description": {
      "Type": "String",
      "Description": "Description of the API, less than 180 characters."
    },
    "ResultSample": {
      "Type": "String",
      "Description": "The sample of the result."
    },
    "DisableInternet": {
      "Type": "Boolean",
      "Description": "Set DisableInternet to true, only support intranet to call API. \nSet DisableInternet to false, then the call is not restricted. \n",
      "AllowedValues": [
        "True",
        "true",
        "False",
        "false"
      ]
    },
    "ApiName": {
      "Type": "String",
      "Description": "The name of the API.Need [4, 50] Chinese\\English\\Number characters or \"_\",and should start with Chinese/English character."
    },
    "ForceNonceCheck": {
      "Type": "Boolean",
      "Description": "Set ForceNonceCheck to true, compulsorily check X-Ca-Nonce when requesting, \nthis is the unique identifier of the request, generally using UUID to identify. \nThe API gateway will verify the validity of this parameter after receiving this parameter. \nThe same value can only be used once within 15 minutes. It can effectively prevent API replay attacks.\nSet ForceNonceCheck to false, then no check. ",
      "AllowedValues": [
        "True",
        "true",
        "False",
        "false"
      ]
    },
    "ResultType": {
      "Type": "String",
      "Description": "The format of service's response, \"JSON\", \"TEXT\", \"BINARY\", \"XML\", \"HTML\" or \"PASSTHROUGH\". Default is \"JSON\".",
      "AllowedValues": [
        "JSON",
        "TEXT",
        "BINARY",
        "XML",
        "HTML",
        "PASSTHROUGH"
      ],
      "Default": "JSON"
    },
    "FailResultSample": {
      "Type": "String",
      "Description": "The sample of the fail result."
    },
    "ErrorCodeSamples": {
      "Type": "Json",
      "Description": "The Error Code samples."
    },
    "GroupId": {
      "Type": "String",
      "Description": "The id of the Group."
    },
    "ServiceParametersMap": {
      "Type": "Json",
      "Description": "The mapping relation between (request parameters\\const parameters\\system parameters) and service parameters."
    },
    "RequestParameters": {
      "Type": "Json",
      "Description": "The request parameters.",
      "Default": []
    },
    "AppCodeAuthType": {
      "Type": "String",
      "Description": "When AuthType is APP authentication, the optional values are as follows: If not passed, the default value is DEFAULT:\nDEFAULT: Default (set by group).\nDISABLE: Not allowed\nHEADER: Allow AppCode header authentication\nHEADER_QUERY: Allow AppCode header and query authentication",
      "AllowedValues": [
        "DEFAULT",
        "DISABLE",
        "HEADER",
        "HEADER_QUERY"
      ]
    },
    "ServiceConfig": {
      "Type": "Json",
      "Description": "The configuration of the service."
    },
    "ConstParameters": {
      "Type": "Json",
      "Description": "The const parameters."
    },
    "SystemParameters": {
      "Type": "Json",
      "Description": "The system parameters."
    },
    "OpenIdConnectConfig": {
      "Type": "Json",
      "Description": "The configuration of the open id."
    },
    "Visibility": {
      "Type": "String",
      "Description": "Whether to make the API public. \"PUBLIC\" or \"PRIVATE\".",
      "AllowedValues": [
        "PUBLIC",
        "PRIVATE"
      ]
    },
    "ServiceParameters": {
      "Type": "Json",
      "Description": "The service parameters."
    },
    "AuthType": {
      "Type": "String",
      "Description": "Type of authorization of the API . \"APP\",\"ANONYMOUS\", or \"APPOPENID\"",
      "AllowedValues": [
        "APP",
        "ANONYMOUS",
        "APPOPENID"
      ]
    }
  },
  "Resources": {
    "API": {
      "Type": "ALIYUN::ApiGateway::Api",
      "Properties": {
        "RequestConfig": {
          "Ref": "RequestConfig"
        },
        "Description": {
          "Ref": "Description"
        },
        "ResultSample": {
          "Ref": "ResultSample"
        },
        "DisableInternet": {
          "Ref": "DisableInternet"
        },
        "ApiName": {
          "Ref": "ApiName"
        },
        "ForceNonceCheck": {
          "Ref": "ForceNonceCheck"
        },
        "ResultType": {
          "Ref": "ResultType"
        },
        "FailResultSample": {
          "Ref": "FailResultSample"
        },
        "ErrorCodeSamples": {
          "Ref": "ErrorCodeSamples"
        },
        "GroupId": {
          "Ref": "GroupId"
        },
        "ServiceParametersMap": {
          "Ref": "ServiceParametersMap"
        },
        "RequestParameters": {
          "Ref": "RequestParameters"
        },
        "AppCodeAuthType": {
          "Ref": "AppCodeAuthType"
        },
        "ServiceConfig": {
          "Ref": "ServiceConfig"
        },
        "ConstParameters": {
          "Ref": "ConstParameters"
        },
        "SystemParameters": {
          "Ref": "SystemParameters"
        },
        "OpenIdConnectConfig": {
          "Ref": "OpenIdConnectConfig"
        },
        "Visibility": {
          "Ref": "Visibility"
        },
        "ServiceParameters": {
          "Ref": "ServiceParameters"
        },
        "AuthType": {
          "Ref": "AuthType"
        }
      }
    }
  },
  "Outputs": {
    "ApiId": {
      "Description": "The id of the API.",
      "Value": {
        "Fn::GetAtt": [
          "API",
          "ApiId"
        ]
      }
    }
  }
}

YAML格式

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  RequestConfig:
    Type: Json
    Description: The configuration of the request
  Description:
    Type: String
    Description: 'Description of the API, less than 180 characters.'
  ResultSample:
    Type: String
    Description: The sample of the result.
  DisableInternet:
    Type: Boolean
    Description: |
      Set DisableInternet to true, only support intranet to call API. 
      Set DisableInternet to false, then the call is not restricted. 
    AllowedValues:
      - 'True'
      - 'true'
      - 'False'
      - 'false'
  ApiName:
    Type: String
    Description: >-
      The name of the API.Need [4, 50] Chinese\English\Number characters or
      "_",and should start with Chinese/English character.
  ForceNonceCheck:
    Type: Boolean
    Description: >-
      Set ForceNonceCheck to true, compulsorily check X-Ca-Nonce when
      requesting, 

      this is the unique identifier of the request, generally using UUID to
      identify. 

      The API gateway will verify the validity of this parameter after receiving
      this parameter. 

      The same value can only be used once within 15 minutes. It can effectively
      prevent API replay attacks.

      Set ForceNonceCheck to false, then no check. 
    AllowedValues:
      - 'True'
      - 'true'
      - 'False'
      - 'false'
  ResultType:
    Type: String
    Description: >-
      The format of service's response, "JSON", "TEXT", "BINARY", "XML", "HTML"
      or "PASSTHROUGH". Default is "JSON".
    AllowedValues:
      - JSON
      - TEXT
      - BINARY
      - XML
      - HTML
      - PASSTHROUGH
    Default: JSON
  FailResultSample:
    Type: String
    Description: The sample of the fail result.
  ErrorCodeSamples:
    Type: Json
    Description: The Error Code samples.
  GroupId:
    Type: String
    Description: The id of the Group.
  ServiceParametersMap:
    Type: Json
    Description: >-
      The mapping relation between (request parameters\const parameters\system
      parameters) and service parameters.
  RequestParameters:
    Type: Json
    Description: The request parameters.
    Default: []
  AppCodeAuthType:
    Type: String
    Description: >-
      When AuthType is APP authentication, the optional values are as follows:
      If not passed, the default value is DEFAULT:

      DEFAULT: Default (set by group).

      DISABLE: Not allowed

      HEADER: Allow AppCode header authentication

      HEADER_QUERY: Allow AppCode header and query authentication
    AllowedValues:
      - DEFAULT
      - DISABLE
      - HEADER
      - HEADER_QUERY
  ServiceConfig:
    Type: Json
    Description: The configuration of the service.
  ConstParameters:
    Type: Json
    Description: The const parameters.
  SystemParameters:
    Type: Json
    Description: The system parameters.
  OpenIdConnectConfig:
    Type: Json
    Description: The configuration of the open id.
  Visibility:
    Type: String
    Description: Whether to make the API public. "PUBLIC" or "PRIVATE".
    AllowedValues:
      - PUBLIC
      - PRIVATE
  ServiceParameters:
    Type: Json
    Description: The service parameters.
  AuthType:
    Type: String
    Description: 'Type of authorization of the API . "APP","ANONYMOUS", or "APPOPENID"'
    AllowedValues:
      - APP
      - ANONYMOUS
      - APPOPENID
Resources:
  API:
    Type: 'ALIYUN::ApiGateway::Api'
    Properties:
      RequestConfig:
        Ref: RequestConfig
      Description:
        Ref: Description
      ResultSample:
        Ref: ResultSample
      DisableInternet:
        Ref: DisableInternet
      ApiName:
        Ref: ApiName
      ForceNonceCheck:
        Ref: ForceNonceCheck
      ResultType:
        Ref: ResultType
      FailResultSample:
        Ref: FailResultSample
      ErrorCodeSamples:
        Ref: ErrorCodeSamples
      GroupId:
        Ref: GroupId
      ServiceParametersMap:
        Ref: ServiceParametersMap
      RequestParameters:
        Ref: RequestParameters
      AppCodeAuthType:
        Ref: AppCodeAuthType
      ServiceConfig:
        Ref: ServiceConfig
      ConstParameters:
        Ref: ConstParameters
      SystemParameters:
        Ref: SystemParameters
      OpenIdConnectConfig:
        Ref: OpenIdConnectConfig
      Visibility:
        Ref: Visibility
      ServiceParameters:
        Ref: ServiceParameters
      AuthType:
        Ref: AuthType
Outputs:
  ApiId:
    Description: The id of the API.
    Value:
      'Fn::GetAtt':
        - API
        - ApiId