Work with QuickSight Q topics using the Amazon QuickSight CLI
Applies to: Enterprise Edition |
Intended audience: Amazon QuickSight developers |
Use this section to learn how to work with QuickSight Q topics using the Amazon QuickSight command line interface (CLI).
Prerequisites
Before you begin, make sure that you have an AWS Identity and Access Management (IAM) role that grants the CLI user access to call the QuickSight API operations. The following table shows which permissions must be added to the IAM policy to use specific API operations. To use all of the Q topic API operations, add all of the permissions listed in the table.
API operation | IAM policy |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following example shows an IAM policy that allows a user to use the
ListTopics
API operation.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "quicksight:ListTopics" ], "Resource": "*" } ] }
Work with QuickSight Q topics using the QuickSight CLI
The following example creates a new Q topic.
aws quicksight create-topic --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--topicTOPIC
You can also create a new Q topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.
aws quicksight create-topic --cli-input-json file://createtopic.json
When you create a new Q topic, the dataset refresh configuration is not copied to
the topic. To set a topic refresh schedule for your new topic, you can make a create-topic-refresh-schedule
API call. For more information about configuring topic refresh schedules with the CLI, see Configure Q topic refresh schedules with the
QuickSight CLI.
After you create your first Q topic, you can update, delete, list, or request a summary of a Q topic.
The following example updates a Q topic.
aws quicksight update-topic --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--topicTOPIC
You can also update a Q topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.
aws quicksight update-topic --cli-input-json file://updatetopic.json
The following example provides a list of all Q topics in a QuickSight account.
aws quicksight list-topics --aws-account-id
AWSACCOUNTID
The following example deletes a Q topic.
aws quicksight delete-topic --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
The following example provides information about how a Q topic was configured.
aws quicksight describe-topic --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
The following command updates the permissions of a Q topic.
aws quicksight update-topic-permissions --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--grant-permissions Principal=arn:aws:quicksight:us-east-1
:AWSACCOUNTID
:user/default/USERNAME
,Actions=quicksight:DescribeTopic --revoke-permissions Principal=arn:aws:quicksight:us-east-1
:AWSACCOUNTID
:user/default/USERNAME
,Actions=quicksight:DescribeTopic
Use the grant-permissions
parameter to grant read and author permissions to QuickSight account users. To grant read permissions to an account user, enter the following value: "quicksight:DescribeTopic"
. To grant permissions to an account user, enter the following values:
-
"quicksight:DescribeTopic"
-
"quicksight:DescribeTopicRefresh"
-
"quicksight:ListTopicRefreshSchedules"
-
"quicksight:DescribeTopicRefreshSchedule"
-
"quicksight:DeleteTopic"
-
"quicksight:UpdateTopic"
-
"quicksight:CreateTopicRefreshSchedule"
-
"quicksight:DeleteTopicRefreshSchedule"
-
"quicksight:UpdateTopicRefreshSchedule"
-
"quicksight:DescribeTopicPermissions"
-
"quicksight:UpdateTopicPermissions"
The RevokePermissions
parameter revokes all permissions granted to an account user.
The following command describes all permissions from a Q topic.
aws quicksight describe-topic-permissions --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
Configure Q topic refresh schedules with the QuickSight CLI
The following command creates a refresh schedule of a Q topic.
aws quicksight create-topic-refresh-schedule --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--dataset-arnDATASETARN
--refresh-scheduleREFRESHSCHEDULE
After you create a refresh schedule for a Q topic, you can update, delete, list, or request a summary of the topic's refresh schedule.
The following command updates the refresh schedule of a Q topic.
aws quicksight update-topic-refresh-schedule --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--dataset-idDATASETID
--refresh-scheduleREFRESHSCHEDULE
The following example provides a list of all refresh schedules configured to a Q topic.
aws quicksight list-topic-refresh-schedules --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
The following example deletes a topic refresh schedule.
aws quicksight delete-topic-refresh-schedule --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--dataset-idDATASETID
The following example provides information about how a topic refresh schedule was configured.
aws quicksight describe-topic-refresh-schedule --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
--dataset-idDATASETID
Copy and migrate QuickSight Q topics within and between AWS accounts
You can migrate your QuickSight Q topics from one account to another with the QuickSight command line interface (CLI). Instead of manually replicating the same topic across multiple dashboards, namespaces, or accounts, you can use the QuickSight CLI to reuse the same topic repeatedly. This capability saves QuickSight authors time and creates a standardized topic experience for dashboard readers across multiple dashboards.
To migrate Q topics with the QuickSight CLI, use the following procedure
To migrate a Q topic to another account
-
First, identify the topic that you want to migrate. You can view a list of every Q topic in your QuickSight account with a
list-topics
API command.aws quicksight list-topics --aws-account-id
AWSACCOUNTID
-
After you have a list of Q topics, locate the topic that you want to migrate and make a
describe-topic
call to receive a JSON structure of the topic's configuration.aws quicksight describe-topic --aws-account-id
AWSACCOUNTID
--topic-idTOPICID
Following is an example of a
describe-topic
API response.{ "Status": 200, "TopicId": "TopicExample", "Arn": "string", "Topic": [ { "Name": "{}", "DataSets": [ { "DataSetArn": "{}", "DataSetName": "{}", "DataSetDescription": "{}", "DataAggregation": "{}", "Filters": [], "Columns": [], "CalculatedFields": [], "NamedEntities": [] } ] } ], "RequestId": "requestId" }
-
Use the JSON response to create a skeleton file that you can input into a new
create-topic
call in your other QuickSight account. Before you make an API call with your skeleton file, make sure to change the AWS account ID and dataset ID in the skeleton file to match the AWS account ID and dataset ID that you are adding the new Q topic to. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.aws quicksight create-topic --aws-account-id
AWSACCOUNTID
\ --cli-input-jsonfile://./create-topic-cli-input.json
After you make a create-topic
call to the QuickSight API, the new
topic appears in your account. To confirm that the new topic exists, make a list-topics
call to the QuickSight API. If the source topic that was duplicated contains verified answers, the answers are not migrated to the new topic. To see a list of all verified answers that are configured to the original topic, use a describe-topic
API call.