Queries trails in a region.

This topic provides an example on how to query the single-account trails within the current Alibaba Cloud account. The returned result shows that only one trail named test-4 is created within the Alibaba Cloud account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeTrails

The operation that you want to perform. Set the value to DescribeTrails.

IncludeShadowTrails Boolean No true

Specifies whether to return shadow trails. Valid values:

  • false: does not return shadow trails. This is the default value.
  • true: returns shadow trails.
NameList String No audit-log,trail-test2

The trails to query. Separate the names of multiple trails with commas (,).

IncludeOrganizationTrail Boolean No false

Specifies whether to query multi-account trails. Valid values:

  • true: queries multi-account trails.
  • false: does not query multi-account trails. Only single-account trails are queried. This is the default value.

Response parameters

Parameter Type Example Description
RequestId String 10313D41-C40A-4D53-ACA0-0190334DF81C

The ID of the request.

TrailList Array of TrailList

The list of returned trails.

TrailRegion String All

The region in which the trail delivers events. Valid values:

  • All: delivers events in all regions. This is the default value.
  • cn-hangzhou: delivers events only in the China (Hangzhou) region.
  • cn-beijing: delivers events only in the China (Beijing) region.
Status String Enable

The status of the trail. Valid values:

  • Disable: disabled.
  • Enable: enabled.
  • Fresh: The trail is created but is not enabled.
UpdateTime String 1619407012000

The most recent time when the configuration of the trail was updated.

HomeRegion String cn-hangzhou

The home region of the trail.

CreateTime String 1614580048000

The time when the trail was created.

OssKeyPrefix String trail1

The prefix of the log files stored in the Object Storage Service (OSS) bucket.

EventRW String Write

The type of events to be delivered. Valid values:

  • Write: write events. This is the default value.
  • Read: read events.
  • All: read and write events.
StartLoggingTime String 1619407012000

The time when the trail was last enabled.

MnsTopicArn String acs:mns:cn-hangzhou:1111:/topics/your-topic-name

The Alibaba Cloud Resource Name (ARN) of the Message Service (MNS) topic to which ActionTrail sends messages. The ARN is in the acs:mns:<Region>:<Account ID>:/topics/<Topic name> format. If the ARN is specified, a message is generated and sent to the MNS topic whenever an event is delivered to OSS.

RoleName String aliyunactiontraildefaultrole

The name of the Resource Access Management (RAM) role that is assumed by ActionTrail.

SlsProjectArn String acs:log:cn-hangzhou:159498693826****:project/alice-audit-log

The unique ARN of the Log Service project to which events are delivered.

IsOrganizationTrail Boolean false

Indicates whether the trail is a multi-account trail. Valid values:

  • false: The trail is not a multi-account trail. This is the default value.
  • true: The trail is a multi-account trail.
SlsWriteRoleArn String acs:ram::159498693826****:role/aliyunserviceroleforactiontrail

The unique ARN of the role that is assumed by ActionTrail to deliver log files to the Log Service project.

StopLoggingTime String 1617674944000

The time when the trail was last disabled.

Name String test-4

The name of the trail.

OssBucketName String secloud

The name of the OSS bucket to which events are delivered.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeTrails
&<Common request parameters>

Sample success responses

XML format 

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

<DescribeTrailsResponse>
    <RequestId>10313D41-C40A-4D53-ACA0-0190334DF81C</RequestId>
    <TrailList>
        <Status>Enable</Status>
        <MnsTopicArn>acs:mns:cn-hangzhou:1111:/topics/your-topic-name</MnsTopicArn>
        <HomeRegion>cn-hangzhou</HomeRegion>
        <StartLoggingTime>1619407012000</StartLoggingTime>
        <CreateTime>1614580048000</CreateTime>
        <StopLoggingTime>1617674944000</StopLoggingTime>
        <SlsWriteRoleArn>acs:ram::159498693826****:role/aliyunserviceroleforactiontrail</SlsWriteRoleArn>
        <TrailRegion>All</TrailRegion>
        <Name>test-4</Name>
        <IsOrganizationTrail>false</IsOrganizationTrail>
        <SlsProjectArn>acs:log:cn-hangzhou:159498693826****:project/alice-audit-log</SlsProjectArn>
        <RoleName>aliyunactiontraildefaultrole</RoleName>
        <EventRW>Write</EventRW>
        <UpdateTime>1619407012000</UpdateTime>
        <OssKeyPrefix>trail1</OssKeyPrefix>
        <OssBucketName>secloud</OssBucketName>
    </TrailList>
</DescribeTrailsResponse>

JSON format 

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

{
  "RequestId" : "10313D41-C40A-4D53-ACA0-0190334DF81C",
  "TrailList" : [ {
    "Status" : "Enable",
    "MnsTopicArn" : "acs:mns:cn-hangzhou:1111:/topics/your-topic-name",
    "HomeRegion" : "cn-hangzhou",
    "StartLoggingTime" : 1619407012000,
    "CreateTime" : 1614580048000,
    "StopLoggingTime" : 1617674944000,
    "SlsWriteRoleArn" : "acs:ram::159498693826****:role/aliyunserviceroleforactiontrail",
    "TrailRegion" : "All",
    "Name" : "test-4",
    "IsOrganizationTrail" : false,
    "SlsProjectArn" : "acs:log:cn-hangzhou:159498693826****:project/alice-audit-log",
    "RoleName" : "aliyunactiontraildefaultrole",
    "EventRW" : "Write",
    "UpdateTime" : 1619407012000,
    "OssKeyPrefix" : "trail1",
    "OssBucketName" : "secloud"
  } ]
}

Error codes

HTTP status code Error code Error message Description
400 InvalidTrailNameException The specified Trail name is invalid. The error message returned because the specified trail name is invalid. Specify a valid trail name.
400 InvalidQueryParameter The specified query parameter is invalid. The error message returned because one or more specified request parameters are invalid.

For a list of error codes, visit the API Error Center.