全部产品
Search
文档中心

云服务器 ECS:DescribeSecurityGroups

更新时间:Aug 21, 2023

调用DescribeSecurityGroups查询您创建的安全组的基本信息。

接口说明

调用接口前,您需要注意:

  • 安全组的基本信息包括安全组ID和安全组描述等。返回参数列表按照安全组ID降序排列。
  • 在分页查询时,推荐您使用MaxResults与NextToken参数进行查询。具体使用说明:分页查询首页时,仅需设置MaxResults以限制返回信息的条目数,返回结果中的NextToken将作为查询后续页的凭证。查询后续页时,将NextToken参数设置为上一次返回结果中获取到的NextToken作为查询凭证,并设置MaxResults限制返回条目数。当返回结果中的NextToken为空时,表示该页为末页,不再有后续页。
  • 通过阿里云CLI调用API时,不同数据类型的请求参数取值必须遵循一定的格式要求。更多信息,请参见CLI参数格式说明

调试

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

请求参数

名称

类型

是否必选

示例值

描述

Action String DescribeSecurityGroups

系统规定参数。取值:DescribeSecurityGroups

RegionId String cn-hangzhou

地域ID。您可以调用DescribeRegions查看最新的阿里云地域列表。

SecurityGroupIds String ["sg-bp67acfmxazb4p****", "sg-bp67acfmxazb4p****", "sg-bp67acfmxazb4p****",....]

安全组ID列表。一次最多支持100个安全组ID,ID之间用半角逗号(,)隔开,格式为JSON数组。

VpcId String vpc-bp67acfmxazb4p****

安全组所在的专有网络ID。

SecurityGroupType String normal

安全组类型。取值范围:

  • normal:普通安全组。
  • enterprise:企业安全组。
说明 当不为该参数传值时,表示查询所有类型的安全组。
NextToken String e71d8a535bd9cc11

查询凭证(Token)。取值为上一次调用该接口返回的NextToken参数值,初次调用接口时无需设置该参数。

MaxResults Integer 10

分页查询时每页的最大条目数。一旦设置该参数,即表示使用MaxResultsNextToken组合参数的查询方式。

最大值为100。

默认值为10。

NetworkType String vpc

安全组的网络类型。取值范围:

  • vpc:专有网络。
  • classic:经典网络。
SecurityGroupName String SGTestName

安全组名称。

IsQueryEcsCount Boolean null

是否查询安全组的容量信息。传True时,返回值中的EcsCountAvailableInstanceAmount有效。

说明 该参数已废弃。
ResourceGroupId String rg-bp67acfmxazb4p****

安全组所在的企业资源组ID。使用该参数过滤资源时,资源数量不能超过1000个。您可以调用ListResourceGroups查询资源组列表。

说明 不支持默认资源组过滤。
Tag.N.key String testkey

安全组的标签键。

说明 为提高兼容性,建议您尽量使用Tag.N.Key参数。
Tag.N.Key String TestKey

安全组的标签键。N的取值范围为1~20。

使用一个标签过滤资源,查询到该标签下的资源数量不能超过1000个;使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过1000个。如果资源数量超过1000个,请使用ListTagResources接口进行查询。

Tag.N.Value String TestValue

安全组的标签值。N的取值范围:1~20。

Tag.N.value String testvalue

安全组的标签值。

说明 为提高兼容性,建议您尽量使用Tag.N.Value参数。
DryRun Boolean false

是否只预检此次请求。取值范围:

  • true:发送检查请求,不会查询资源状况。检查项包括AccessKey是否有效、RAM用户的授权情况和是否填写了必需参数。如果检查不通过,则返回对应错误。如果检查通过,会返回错误码DryRunOperation。
  • false:发送正常请求,通过检查后返回2XX HTTP状态码并直接查询资源状况。

默认值为false。

SecurityGroupId String sg-bp67acfmxazb4p****

安全组ID。

FuzzyQuery Boolean null
说明 该参数已废弃。
PageNumber Integer 1

安全组列表的页码。

起始值为1。

默认值为1。

说明 该参数即将下线,推荐您使用NextToken与MaxResults完成分页查询操作。
PageSize Integer 10

分页查询时设置的每页行数。

最大值为50。

默认值为10。

说明 该参数即将下线,推荐您使用NextToken与MaxResults完成分页查询操作。

返回数据

名称

类型

示例值

描述

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

请求ID。

RegionId String cn-hangzhou

安全组所属地域ID。

NextToken String e71d8a535bd9cc11

本次调用返回的查询凭证(Token)。当使用MaxResults和NextToken方式进行分页查询,且该返回值为空时,表示无更多返回的数据信息。

SecurityGroups Array of SecurityGroup

安全组信息集合。

SecurityGroup
SecurityGroupId String sg-bp67acfmxazb4p****

安全组ID。

SecurityGroupName String SGTestName

安全组名称。

Description String TestDescription

安全组描述信息。

SecurityGroupType String normal

安全组类型。可能值:

  • normal:普通安全组。
  • enterprise:企业安全组。
VpcId String vpc-bp67acfmxazb4p****

安全组所属的专有网络。

CreationTime String 2021-08-31T03:12:29Z

创建时间。按照ISO 8601标准表示,并需要使用UTC时间。格式为:yyyy-MM-ddThh:mmZ。

EcsCount Integer 0

安全组中已经容纳的私网IP数量,参见安全组容量

当入参IsQueryEcsCount传入True时,该参数返回值有效。

说明 该参数已废弃。返回值中的数量仅供参考,非实时一致。
AvailableInstanceAmount Integer 0

安全组中还可加入的私网IP数量,参见安全组容量

当入参IsQueryEcsCount传入True时,该参数返回值有效。

说明 该参数已废弃。返回值中的数量仅供参考,非实时一致。
ResourceGroupId String rg-bp67acfmxazb4p****

安全组所在的企业资源组ID。

ServiceManaged Boolean false

安全组的使用者是否为云产品或虚商。

ServiceID Long 12345678910

安全组对应的虚商ID。

Tags Array of Tag

安全组的标签。

Tag
TagValue String TestValue

安全组的标签值。

TagKey String TestKey

安全组的标签键。

TotalCount Integer 20

安全组的总数。当您使用MaxResultsNextToken参数查询时,不会返回该参数值。

PageNumber Integer 1

当前页码。

说明 该参数即将下线,推荐您使用NextToken与MaxResults完成分页查询操作。
PageSize Integer 10

每页行数。

说明 该参数即将下线,推荐您使用NextToken与MaxResults完成分页查询操作。

示例

请求示例

http(s)://ecs.aliyuncs.com/?Action=DescribeSecurityGroups
&RegionId=cn-hangzhou
&MaxResults=10
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeSecurityGroupsResponse>
    <PageSize>10</PageSize>
    <PageNumber>1</PageNumber>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <TotalCount>20</TotalCount>
    <RegionId>cn-hangzhou</RegionId>
    <SecurityGroups>
        <CreationTime>2021-08-31T03:12:29Z</CreationTime>
        <VpcId>vpc-bp67acfmxazb4p****</VpcId>
        <ServiceManaged>false</ServiceManaged>
        <Description>TestDescription</Description>
        <SecurityGroupId>sg-bp67acfmxazb4p****</SecurityGroupId>
        <ResourceGroupId>rg-bp67acfmxazb4p****</ResourceGroupId>
        <SecurityGroupName>SGTestName</SecurityGroupName>
        <EcsCount>0</EcsCount>
        <ServiceID>12345678910</ServiceID>
        <SecurityGroupType>normal</SecurityGroupType>
        <AvailableInstanceAmount>0</AvailableInstanceAmount>
        <Tags>
            <TagValue>TestValue</TagValue>
            <TagKey>TestKey</TagKey>
        </Tags>
    </SecurityGroups>
    <NextToken>e71d8a535bd9cc11</NextToken>
</DescribeSecurityGroupsResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

{
  "PageSize" : 10,
  "PageNumber" : 1,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount" : 20,
  "RegionId" : "cn-hangzhou",
  "SecurityGroups" : [ {
    "CreationTime" : "2021-08-31T03:12:29Z",
    "VpcId" : "vpc-bp67acfmxazb4p****",
    "ServiceManaged" : false,
    "Description" : "TestDescription",
    "SecurityGroupId" : "sg-bp67acfmxazb4p****",
    "ResourceGroupId" : "rg-bp67acfmxazb4p****",
    "SecurityGroupName" : "SGTestName",
    "EcsCount" : 0,
    "ServiceID" : 12345678910,
    "SecurityGroupType" : "normal",
    "AvailableInstanceAmount" : 0,
    "Tags" : [ {
      "TagValue" : "TestValue",
      "TagKey" : "TestKey"
    } ]
  } ],
  "NextToken" : "e71d8a535bd9cc11"
}

错误码

HttpCode

错误码

错误信息

描述

400 NotSupported.PageNumberAndPageSize The parameters PageNumber and PageSize are currently not supported, please use NextToken and MaxResults instead. 参数PageNumber和PageSize已经不受支持,请使用参数NextToken和MaxResults。
400 InValidParameter.NextToken The parameter NextToken is invalid. 指定的参数NextToken不合法。
400 MissingParameter.RegionId The input parameter RegionId that is mandatory for processing this request is not supplied. 参数 RegionId 不能为空。
400 InvalidParameter.SecurityGroupType The specified SecurityGroupType is not valid. 指定的 SecurityGroupType 参数无效,请检查该参数取值是否正确。
500 InternalError The request processing has failed due to some unknown error. 内部错误,请重试。

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