CreateDashboard
Creates a custom dashboard or the Highlights dashboard.
-
Custom dashboards - Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule.
-
Highlights dashboard - You can create the Highlights dashboard to see a summary of key user activities and API usage across all your event data stores. CloudTrail Lake manages the Highlights dashboard and refreshes the dashboard every 6 hours. To create the Highlights dashboard, you must set and enable a refresh schedule.
CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery
operation on your behalf. To provide permissions, run the PutResourcePolicy
operation to attach a resource-based policy to each event data store. For more information,
see Example: Allow CloudTrail to run queries to populate a dashboard in the
Amazon CloudTrail User Guide.
To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh
operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy
operation to attach a resource-based policy to the dashboard. For more information,
see
Resource-based policy example for a dashboard in the
Amazon CloudTrail User Guide.
For more information about dashboards, see CloudTrail Lake dashboards in the Amazon CloudTrail User Guide.
Request Syntax
{
"Name": "string
",
"RefreshSchedule": {
"Frequency": {
"Unit": "string
",
"Value": number
},
"Status": "string
",
"TimeOfDay": "string
"
},
"TagsList": [
{
"Key": "string
",
"Value": "string
"
}
],
"TerminationProtectionEnabled": boolean
,
"Widgets": [
{
"QueryParameters": [ "string
" ],
"QueryStatement": "string
",
"ViewProperties": {
"string
" : "string
"
}
}
]
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- Name
-
The name of the dashboard. The name must be unique to your account.
To create the Highlights dashboard, the name must be
AWSCloudTrail-Highlights
.Type: String
Length Constraints: Minimum length of 3. Maximum length of 128.
Pattern:
^[a-zA-Z0-9_\-]+$
Required: Yes
- RefreshSchedule
-
The refresh schedule configuration for the dashboard.
To create the Highlights dashboard, you must set a refresh schedule and set the
Status
toENABLED
. TheUnit
for the refresh schedule must beHOURS
and theValue
must be6
.Type: RefreshSchedule object
Required: No
- TagsList
-
A list of tags.
Type: Array of Tag objects
Array Members: Maximum number of 200 items.
Required: No
- TerminationProtectionEnabled
-
Specifies whether termination protection is enabled for the dashboard. If termination protection is enabled, you cannot delete the dashboard until termination protection is disabled.
Type: Boolean
Required: No
- Widgets
-
An array of widgets for a custom dashboard. A custom dashboard can have a maximum of ten widgets.
You do not need to specify widgets for the Highlights dashboard.
Type: Array of RequestWidget objects
Required: No
Response Syntax
{
"DashboardArn": "string",
"Name": "string",
"RefreshSchedule": {
"Frequency": {
"Unit": "string",
"Value": number
},
"Status": "string",
"TimeOfDay": "string"
},
"TagsList": [
{
"Key": "string",
"Value": "string"
}
],
"TerminationProtectionEnabled": boolean,
"Type": "string",
"Widgets": [
{
"QueryAlias": "string",
"QueryParameters": [ "string" ],
"QueryStatement": "string",
"ViewProperties": {
"string" : "string"
}
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- DashboardArn
-
The ARN for the dashboard.
Type: String
Pattern:
^[a-zA-Z0-9._/\-:]+$
- Name
-
The name of the dashboard.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 128.
Pattern:
^[a-zA-Z0-9_\-]+$
- RefreshSchedule
-
The refresh schedule for the dashboard, if configured.
Type: RefreshSchedule object
- TagsList
-
A list of tags.
Type: Array of Tag objects
Array Members: Maximum number of 200 items.
- TerminationProtectionEnabled
-
Indicates whether termination protection is enabled for the dashboard.
Type: Boolean
- Type
-
The dashboard type.
Type: String
Valid Values:
MANAGED | CUSTOM
- Widgets
-
An array of widgets for the dashboard.
Type: Array of Widget objects
Errors
For information about the errors that are common to all actions, see Common Errors.
- ConflictException
-
This exception is thrown when the specified resource is not ready for an operation. This can occur when you try to run an operation on a resource before CloudTrail has time to fully load the resource, or because another operation is modifying the resource. If this exception occurs, wait a few minutes, and then try the operation again.
HTTP Status Code: 400
- EventDataStoreNotFoundException
-
The specified event data store was not found.
HTTP Status Code: 400
- InactiveEventDataStoreException
-
The event data store is inactive.
HTTP Status Code: 400
- InsufficientEncryptionPolicyException
-
For the
CreateTrail
PutInsightSelectors
,UpdateTrail
,StartQuery
, andStartImport
operations, this exception is thrown when the policy on the S3 bucket or Amazon KMS key does not have sufficient permissions for the operation.For all other operations, this exception is thrown when the policy for the Amazon KMS key does not have sufficient permissions for the operation.
HTTP Status Code: 400
- InvalidQueryStatementException
-
The query that was submitted has validation errors, or uses incorrect syntax or unsupported keywords. For more information about writing a query, see Create or edit a query in the Amazon CloudTrail User Guide.
HTTP Status Code: 400
- InvalidTagParameterException
-
This exception is thrown when the specified tag key or values are not valid. It can also occur if there are duplicate tags or too many tags on the resource.
HTTP Status Code: 400
- ServiceQuotaExceededException
-
This exception is thrown when the quota is exceeded. For information about CloudTrail quotas, see Service quotas in the Amazon General Reference.
HTTP Status Code: 400
- UnsupportedOperationException
-
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
Examples
Example
The following example creates a custom dashboard named AccountActivityDashboard
with
four widgets and a refresh schedule of every 12 hours. This example enables termination protection to prevent the dashboard from being accidentally deleted.
{ "Name": "AccountActivityDashboard", "RefreshSchedule": { "Frequency": { "Unit": "HOURS", "Value": 12 }, "Status": "ENABLED", "TimeOfDay": "00:00" }, "TerminationProtectionEnabled": true, "Widgets": [ { "ViewProperties": { "Height": "2", "Width": "4", "Title": "TopErrors", "View": "Table" }, "QueryStatement": "SELECT errorCode, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' AND (errorCode is not null) GROUP BY errorCode ORDER BY eventCount DESC LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "MostActiveRegions", "View": "PieChart", "LabelColumn": "awsRegion", "ValueColumn": "eventCount", "FilterColumn": "awsRegion" }, "QueryStatement": "SELECT awsRegion, COUNT(*) AS eventCount FROM eds where eventTime > '?' and eventTime < '?' GROUP BY awsRegion ORDER BY eventCount LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "AccountActivity", "View": "LineChart", "YAxisColumn": "eventCount", "XAxisColumn": "eventDate", "FilterColumn": "readOnly" }, "QueryStatement": "SELECT DATE_TRUNC('?', eventTime) AS eventDate, IF(readOnly, 'read', 'write') AS readOnly, COUNT(*) as eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY DATE_TRUNC('?', eventTime), readOnly ORDER BY DATE_TRUNC('?', eventTime), readOnly", "QueryParameters": ["$Period$", "$StartTime$", "$EndTime$", "$Period$", "$Period$"] }, { "ViewProperties": { "Height": "2", "Width": "4", "Title": "TopServices", "View": "BarChart", "LabelColumn": "service", "ValueColumn": "eventCount", "FilterColumn": "service", "Orientation": "Horizontal" }, "QueryStatement": "SELECT REPLACE(eventSource, '.amazonaws.com') AS service, COUNT(*) AS eventCount FROM eds WHERE eventTime > '?' AND eventTime < '?' GROUP BY eventSource ORDER BY eventCount DESC LIMIT 100", "QueryParameters": ["$StartTime$", "$EndTime$"] } ] }
Example
The following example creates the Highlights dashboard. The Highlights dashboard requires that you set and enable a refresh schedule for every 6 hours.
{ "Name": "AWSCloudTrail-Highlights", "RefreshSchedule": { "Frequency": { "Unit": "HOURS", "Value": 6 }, "Status": "ENABLED" }, "TerminationProtectionEnabled": true }
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: