全部产品
Search
文档中心

API 网关:DescribeApi - 查询 API 定义

更新时间:Nov 21, 2024

查询指定API的定义。

接口说明

  • 此接口面向开放 API 的用户

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
apigateway:DescribeApiget
*ApiGroup
acs:apigateway:{#regionId}:{#accountId}:apigroup/{#GroupId}

请求参数

名称类型必填描述示例值
GroupIdstring

API 所在的分组编号

123
ApiIdstring

API 的 ID 标识

8afff6c8c4c6447abb035812e4d66b65

返回参数

名称类型描述示例值
object
ApiIdstring

API 的 ID 标识

8afff6c8c4c6447abb035812e4d66b65
ResultTypestring

后端服务返回应答的格式,目前可以设置为:JSON、TEXT、BINARY、XML、HTML。

JSON
WebSocketApiTypestring

双向通信 API 类型:

  • COMMON:普通 API
  • REGISTER:注册 API
  • UNREGISTER:注销 API
  • NOTIFY:下行通知
COMMON
DisableInternetboolean

API 是否仅支持内网调用, 取值:

  • true:仅支持内网调用 API
  • false:不限制调用
false
ResultBodyModelstring

api 的返回结果

{}
ResultSamplestring

后端服务返回应答的示例

200
AppCodeAuthTypestring

AuthTypeAPP 认证时,可选值如下:

  • DEFAULT: 不传默认是 DEFAULT(随分组设置)
  • DISABLE: 不允许
  • HEADER: 允许 AppCode 的 Header 认证
  • HEADER_QUERY: 允许 AppCode 的 Header 及 Query 认证
HEADER
AllowSignatureMethodstring

AuthTypeAPP 认证时,需要传该值明确签名算法。可选值如下,不传默认是 HmacSHA256:

  • HmacSHA256
  • HmacSHA1,HmacSHA256
HmacSHA256
RegionIdstring

API 所处的 Region 的 ID

cn-qingdao
ForceNonceCheckboolean

调用 API 时是否必须携带 header : X-Ca-Nonce, 这个是请求的唯一标识,一般使用 UUID 来标识。API 网关收到这个参数后通过校验这个参数的有效性可以有效防止 API 的重放攻击,同样的值,15 分内只能被使用一次。 取值:

  • true: 请求 API 时强制检查这个字段,防止 API 的重放攻击
  • false: 不检查这个字段
true
Visibilitystring

API 是否公开,目前可以取值:

  • PUBLIC:公开,如选择此类型,该 API 的线上环境,会在所有用户的控制台“发现 API”页面展示
  • PRIVATE:不公开,如选择此类型,当该组 API 在云市场上架时,私有类型的 API 不会上架
PUBLIC
FailResultSamplestring

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

400
AuthTypestring

API 安全认证类型,目前可以取值:

  • APP:只允许已授权的 APP 调用
  • ANONYMOUS:允许匿名调用,设置为允许匿名调用需要注意:
    • 任何能够获取该 API 服务信息的人,都将能够调用该 API。网关不会对调用者做身份认证,也无法设置按用户的流量控制,若开放该 API 请设置好按 API 的流量控制。
    • “ANONYMOUS”API 不建议上架云市场,网关无法对调用者区分计量,也无法限制调用次数,若所在分组要上架云市场,建议将该 API 转移至其他分组,或将类型设置为“私有”,或选择“阿里云 APP”认证方式。
  • APPOPENID:支持第三方账号认证 OpenID Connect,而且只允许已授权的 APP 调用;当设置此项时,参数 OpenIdConnectConfig 为必传。
APP
ModifiedTimestring

API 最后一次修改的时间

2016-07-28T13:13:12Z
RequestIdstring

请求 ID

D0FF585F-7966-40CF-BC60-75DB070B23D5<
Descriptionstring

API 描述信息

Api description
GroupNamestring

API 所在的分组名称

ApiTest
GroupIdstring

API 所在的分组编号

08ae4aa0f95e4321849ee57f4e0b3077
Mockstring

是否启用 MOCK 模式,目前可以取值:

  • OPEN:启用 Mock 模式

  • CLOSED:不启用 Mock 模式

CLOSED
MockResultstring

Mock 返回结果

test result
CreatedTimestring

API 创建的时间

2016-07-28T09:50:43Z
ApiNamestring

API 的名称,组内不允许重复

ApiName
BackendEnableboolean

是否启用后端服务

true
BackendConfigobject

后端配置

BackendIdstring

后端服务 ID

0038e00c3dca44fcba3a94015d8f5bbf
BackendTypestring

后端服务类型

HTTP
BackendNamestring

后端服务名称

testoss
RequestConfigobject

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

BodyModelstring

body 模型

https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab
RequestPathstring

API path,比如 API 的完全地址为http://api.a.com:8080/object/add?key1=value1&key2=value2,path 是指/object/add这一部分。

/api/billing/test/[type]
RequestHttpMethodstring

HTTP Method,取值为:GET、POST、DELETE、PUT、HEADER、TRACE、PATCH、CONNECT、OPTIONS。

POST
BodyFormatstring

RequestMode 值为 MAPPING 时有效。

POST/PUT 请求时,表示数据以何种方式传递给服务器,取值为:FORMSTREAM,分别表示表单形式(k-v 对应)、字节流形式。

STREAM
RequestModestring

请求的模式,取值为:MAPPINGPASSTHROUGH,分别表示入参映射、入参透传

MAPPING
PostBodyDescriptionstring

Body 描述

fwefwef
RequestProtocolstring

API 支持的协议类型,可以多选,多选情况下以英文逗号隔开,如:”HTTP,HTTPS”,取值为:HTTP、HTTPS。

HTTP
EscapePathParamboolean

是否转义 Path 参数,如果为 true,则 Path 上的[param]将被视为普通字符。

true
ServiceConfigobject

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

AoneAppNamestring

aone 应用名称

ib-blank
MockStatusCodeinteger

Mock 返回状态码

200
ContentTypeValuestring

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

application/x-www-form-urlencoded; charset=UTF-8
ServiceProtocolstring

后端服务协议类型,目前只支持 HTTP/HTTPS

HTTP
ServicePathstring

调用后端服务 path,比如后端服务完全地址为http://api.a.com:8080/object/add?key1=value1&key2=value2ServicePath 是指/object/add这一部分。

/object/add
ContentTypeCatagorystring

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

  • DEFAULT:使用 API 网关默认的值
  • CUSTOM:自定义
  • CLIENT:使用客户端上行的 ContentType 的头
CUSTOM
ServiceAddressstring

调用后端服务地址,比如后端服务完全地址为http://api.a.com:8080/object/add?key1=value1&key2=value2ServiceAddress 是指http://api.a.com:8080这一部分。

http://api.a.com:8080
Mockstring

是否采取 Mock 模式,目前可以取值:

  • TRUE:启用 Mock 模式
  • FALSE:不启用 Mock 模式
TRUE
ServiceVpcEnablestring

是否启用 VPC 通道,目前可以取值:

  • TRUE:启用 VPC 通道,必须先添加 VPC 授权成功后才能启用
  • FALSE:不启用 VPC 通
TRUE
MockResultstring

如果启用 Mock 模式,返回的结果

test result
ServiceHttpMethodstring

调用后端服务 HTTP 协议时的 Method,取值为:GET、POST、DELETE、PUT、HEADER、TRACE、PATCH、CONNECT、OPTIONS。

POST
ServiceTimeoutinteger

后端服务超时时间,单位:毫秒

1000
MockHeadersarray<object>

模拟 Headers

MockHeaderobject
HeaderValuestring

HTTP 头参数的取值。

86400
HeaderNamestring

HTTP 头参数的名字。

Content-Length
VpcConfigobject

VPC 通道相关配置项

VpcIdstring

专用网络 ID

vpc-2zeafsc3fygk1***
VpcSchemestring

VPC 协议

HTTP
InstanceIdstring

专用网络中的实例 ID(Ecs/负载均衡)

i-bp1h497hkijewv2***
Portinteger

实例对应的端口号

8080
Namestring

VPC 授权名称

glmall-app-test
FunctionComputeConfigobject

后端为函数计算时的后端配置项

FcTypestring

函数计算服务类型

HttpTrigger
RoleArnstring

Ram 授权给 API 网关访问函数计算的 arn

acs:ram::111***:role/aliyunserviceroleforsas
Methodstring

请求方法。

GET
FcBaseUrlstring

函数计算服务根路径

https://1227****64334133.ap-southeast-1-int***al.fc.aliyuncs.com/201****-15/proxy/test****ice.LATEST/testHttp/
ContentTypeValuestring

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

application/x-www-form-urlencoded; charset=UTF-8
RegionIdstring

函数计算所在 Region

cn-qingdao
OnlyBusinessPathboolean

后端只接收业务 path

false
FunctionNamestring

函数计算定义的 FunctionName

edge_function
ContentTypeCatagorystring

调用后端服务函数计算服务时,ContentType 头的取值策略:

  • DEFAULT:使用 API 网关默认的值
  • CUSTOM:自定义
  • CLIENT:使用客户端上行的 ContentType 的头
DEFAULT
Pathstring

API 请求路径

/api/offline/cacheData
ServiceNamestring

函数计算定义的 ServiceName

fcservicename
Qualifierstring

函数别名

2
OssConfigobject

后端为 OSS 的信息

Keystring

OSS 内存储对象或文件夹路径

/folder/test.json
Actionstring

OSS 的操作,目前可以取值

  • GetObject
  • PostObject
  • DeleteObject
  • PutObject
  • HeadObject
  • GetObjectMeta
  • AppendObject
GetObject
OssRegionIdstring

OSS 服务所在地域 ID。

cn-hangzhou
BucketNamestring

OSS 存储 Bucket。

cbg-db
EventBridgeConfigobject

事件总线设置

EventBusstring

事件总线

testBus
EventSourcestring

事件来源。

baas_driver
EventBridgeRegionIdstring

事件总线服务所在区域 ID

cn-beijing
RoleArnstring

Ram 授权给 EventBridge 的 arn

acs:ram::1933122015759***:role/adminoidcaliyun
OpenIdConnectConfigobject

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

OpenIdApiTypestring

OpenID Connect 模式,目前可以取值:

  • IDTOKEN:获取授权 API,颁发 Token,当设置此项时,参数 PublicKeyId 和 PublicKey 为必传。
  • BUSINESS:业务 API,Token 验证,当设置此项时,参数 IdTokenParamName 为必传。
IDTOKEN
IdTokenParamNamestring

Token 对应的参数名称

xxx
PublicKeyIdstring

公钥 ID

88483727556929326703309904351185815489
PublicKeystring

公钥

EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92
ErrorCodeSamplesarray<object>

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

ErrorCodeSampleobject
Codestring

错误码

400
Modelstring

模型

[\"*\"]
Messagestring

错误信息

Missing the parameter UserId
Descriptionstring

描述

请求缺少参数 UserId
SystemParametersarray<object>

网关发送给后端服务的系统参数

SystemParameterobject
DemoValuestring

示例

192.168.1.1
Descriptionstring

参数描述

客户端IP
ParameterNamestring

系统参数名,取值为:CaClientIp、CaDomain、CaRequestHandleTime、CaAppId、CaRequestId、CaHttpSchema、CaProxy。

CaClientIp
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD
ServiceParameterNamestring

对应后端参数名称

clientIp
CustomSystemParametersarray<object>

自定义系统参数列表

CustomSystemParameterobject
DemoValuestring

示例

192.168.1.1
Descriptionstring

参数描述

客户端IP
ParameterNamestring

系统参数名,取值为:CaClientIp、CaDomain、CaRequestHandleTime、CaAppId、CaRequestId、CaHttpSchema、CaProxy

CaClientIp
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD
ServiceParameterNamestring

对应后端参数名称

clientIp
ConstantParametersarray<object>

网关发送给后端服务的常量参数

ConstantParameterobject
Descriptionstring

参数描述

constance
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD
ServiceParameterNamestring

后端参数名称

constance
ConstantValuestring

参数值

constance
RequestParametersarray<object>

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

RequestParameterobject
JsonSchemestring

ParameterType=String,JSON 验证(Json Scheme)

JSON
MaxValuelong

ParameterType=Int、Long、Float、Double,参数的最大值限定

123456
ArrayItemsTypestring

数组元素的类型

String
MinValuelong

ParameterType=Int、Long、Float、Double,参数的最小值限定

123456
DocShowstring

文档可见,取值为:PUBLICPRIVATE

PUBLIC
MaxLengthlong

ParameterType=String,参数的最大长度限定

123456
DefaultValuestring

默认值

20
ApiParameterNamestring

参数名

age
EnumValuestring

ParameterType=Int、Long、Float、Double 或 String,允许输入的散列值,不同的值用英文的逗号分隔,形如:1,2,3,4,9 或 A,B,C,E,F。

boy,girl
DemoValuestring

示例

20
Requiredstring

是否必填,取值为:REQUIREDOPTIONAL,分别表示必填、不必填

OPTIONAL
Descriptionstring

参数描述

年龄
ParameterTypestring

参数类型,取值为:String、Int、Long、Float、Double、Boolean,分别表示字符、整型、长整型、单精度浮点型、双精度浮点型、布尔。

String
RegularExpressionstring

ParameterType=String,参数验证(正则表达式)

xxx
MinLengthlong

ParameterType=String,参数的最小长度限定

123456
DocOrderinteger

文档中顺序

0
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD
ServiceParametersarray<object>

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

ServiceParameterobject
Locationstring

参数位置,取值为:BODY、HEAD、QUERY、PATH

HEAD
ParameterTypestring

后端参数数据类型,取值为:STRING、NUMBER、BOOLEAN,分别表示字符、数值、布尔。

String
ServiceParameterNamestring

后端参数名称

clientIp
ServiceParametersMaparray<object>

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

ServiceParameterMapobject
RequestParameterNamestring

对应前端入参名称,这个值必须存在于 RequestParametersObject 中,匹配于 RequestParam.ApiParameterName。

name
ServiceParameterNamestring

后端参数名称

name
DeployedInfosarray<object>

API 发布状态

DeployedInfoobject
StageNamestring

环境名称,取值为:RELEASE、TEST

RELEASE
EffectiveVersionstring

有效的版本

xxx
DeployedStatusstring

部署状态,取值为:DEPLOYED、NONDEPLOYED,分别表示已部署、未部署

DEPLOYED
TagListarray<object>

标签列表

Tagobject
TagKeystring

标签键

APP
TagValuestring

标签值

value3

示例

正常返回示例

JSON格式

{
  "ApiId": "8afff6c8c4c6447abb035812e4d66b65",
  "ResultType": "JSON",
  "WebSocketApiType": "COMMON",
  "DisableInternet": false,
  "ResultBodyModel": "{}",
  "ResultSample": "200",
  "AppCodeAuthType": "HEADER",
  "AllowSignatureMethod": "HmacSHA256",
  "RegionId": "cn-qingdao",
  "ForceNonceCheck": true,
  "Visibility": "PUBLIC",
  "FailResultSample": "400",
  "AuthType": "APP",
  "ModifiedTime": "2016-07-28T13:13:12Z",
  "RequestId": "D0FF585F-7966-40CF-BC60-75DB070B23D5<",
  "Description": "Api description",
  "GroupName": "ApiTest",
  "GroupId": "08ae4aa0f95e4321849ee57f4e0b3077",
  "Mock": "CLOSED",
  "MockResult": "test result",
  "CreatedTime": "2016-07-28T09:50:43Z",
  "ApiName": "ApiName",
  "BackendEnable": true,
  "BackendConfig": {
    "BackendId": "0038e00c3dca44fcba3a94015d8f5bbf",
    "BackendType": "HTTP",
    "BackendName": "testoss"
  },
  "RequestConfig": {
    "BodyModel": "https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab",
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP",
    "EscapePathParam": true
  },
  "ServiceConfig": {
    "AoneAppName": "ib-blank",
    "MockStatusCode": 200,
    "ContentTypeValue": "application/x-www-form-urlencoded; charset=UTF-8",
    "ServiceProtocol": "HTTP",
    "ServicePath": "/object/add",
    "ContentTypeCatagory": "CUSTOM",
    "ServiceAddress": "http://api.a.com:8080",
    "Mock": "TRUE",
    "ServiceVpcEnable": "TRUE",
    "MockResult": "test result",
    "ServiceHttpMethod": "POST",
    "ServiceTimeout": 1000,
    "MockHeaders": {
      "MockHeader": [
        {
          "HeaderValue": "86400",
          "HeaderName": "Content-Length"
        }
      ]
    },
    "VpcConfig": {
      "VpcId": "vpc-2zeafsc3fygk1***",
      "VpcScheme": "HTTP",
      "InstanceId": "i-bp1h497hkijewv2***",
      "Port": 8080,
      "Name": "glmall-app-test"
    },
    "FunctionComputeConfig": {
      "FcType": "HttpTrigger",
      "RoleArn": "acs:ram::111***:role/aliyunserviceroleforsas",
      "Method": "GET",
      "FcBaseUrl": "https://1227****64334133.ap-southeast-1-int***al.fc.aliyuncs.com/201****-15/proxy/test****ice.LATEST/testHttp/",
      "ContentTypeValue": "application/x-www-form-urlencoded; charset=UTF-8",
      "RegionId": "cn-qingdao",
      "OnlyBusinessPath": false,
      "FunctionName": "edge_function",
      "ContentTypeCatagory": "DEFAULT",
      "Path": "/api/offline/cacheData",
      "ServiceName": "fcservicename",
      "Qualifier": "2"
    },
    "OssConfig": {
      "Key": "/folder/test.json",
      "Action": "GetObject",
      "OssRegionId": "cn-hangzhou",
      "BucketName": "cbg-db"
    },
    "EventBridgeConfig": {
      "EventBus": "testBus",
      "EventSource": "baas_driver",
      "EventBridgeRegionId": "cn-beijing",
      "RoleArn": "acs:ram::1933122015759***:role/adminoidcaliyun"
    }
  },
  "OpenIdConnectConfig": {
    "OpenIdApiType": "IDTOKEN",
    "IdTokenParamName": "xxx",
    "PublicKeyId": "88483727556929326703309904351185815489",
    "PublicKey": "EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92"
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "400",
        "Model": "[\\\"*\\\"]",
        "Message": "Missing the parameter UserId",
        "Description": "请求缺少参数 UserId"
      }
    ]
  },
  "SystemParameters": {
    "SystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "客户端IP",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "CustomSystemParameters": {
    "CustomSystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "客户端IP",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ConstantParameters": {
    "ConstantParameter": [
      {
        "Description": "constance",
        "Location": "HEAD",
        "ServiceParameterName": "constance",
        "ConstantValue": "constance"
      }
    ]
  },
  "RequestParameters": {
    "RequestParameter": [
      {
        "JsonScheme": "JSON",
        "MaxValue": 123456,
        "ArrayItemsType": "String",
        "MinValue": 123456,
        "DocShow": "PUBLIC",
        "MaxLength": 123456,
        "DefaultValue": "20",
        "ApiParameterName": "age",
        "EnumValue": "boy,girl",
        "DemoValue": "20",
        "Required": "OPTIONAL",
        "Description": "年龄",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 123456,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  },
  "ServiceParameters": {
    "ServiceParameter": [
      {
        "Location": "HEAD",
        "ParameterType": "String",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ServiceParametersMap": {
    "ServiceParameterMap": [
      {
        "RequestParameterName": "name",
        "ServiceParameterName": "name"
      }
    ]
  },
  "DeployedInfos": {
    "DeployedInfo": [
      {
        "StageName": "RELEASE",
        "EffectiveVersion": "xxx",
        "DeployedStatus": "DEPLOYED"
      }
    ]
  },
  "TagList": {
    "Tag": [
      {
        "TagKey": "APP",
        "TagValue": "value3"
      }
    ]
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2024-11-21OpenAPI 描述信息更新查看变更详情
2024-05-27OpenAPI 返回结构发生变更查看变更详情
2024-03-14OpenAPI 返回结构发生变更查看变更详情
2023-07-11OpenAPI 返回结构发生变更查看变更详情