# Work with Quick Sight topics using the Amazon Quick Sight APIs | | | --- | |  Applies to: Enterprise Edition  | | | | --- | |    Intended audience: Amazon Quick developers  | Use this section to learn how to work with Quick Sight topics using the Amazon Quick Sight 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 Quick Sight 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 topic API operations, add all of the permissions listed in the table. | API operation | IAM policy | | --- | --- | | `CreateTopic` | `quicksight:CreateTopic` `quicksight:PassDataSet` | | `ListTopics` | `quicksight:ListTopics` | | `DescribeTopic` | `quicksight:DescribeTopic` | | `DescribeTopicPermissions` | `quicksight:DescribeTopicPermissions` | | `DescribeTopicRefresh` | `quicksight:DescribeTopicRefresh` | | `DeleteTopic` | `quicksight:DeleteTopic` | | `UpdateTopic` | `quicksight:UpdateTopic` `quicksight:PassDataSet` | | `UpdateTopicPermissions` | `quicksight:UpdateTopicPermissions` | | `CreateTopicRefreshSchedule` | `quicksight:CreateTopicRefreshSchedule` | | `ListTopicRefreshSchedules` | `quicksight:ListTopicRefreshSchedules` | | `DescribeTopicRefreshSchedule` | `quicksight:DescribeTopicRefreshSchedule` | | `UpdateTopicRefreshSchedule` | `quicksight:UpdateTopicRefreshSchedule` | | `DeleteTopicRefreshSchedule` | `quicksight:DeleteTopicRefreshSchedule` | | `BatchCreateTopicReviewedAnswer` | `quicksight:BatchCreateTopicReviewedAnswer` | | `BatchDeleteTopicReviewedAnswer` | `quicksight:BatchDeleteTopicReviewedAnswer` | | `ListTopicReviewedAnswers` | `quicksight:ListTopicReviewedAnswers` | The following example shows an IAM policy that allows a user to use the `ListTopics` API operation. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "quicksight:ListTopics" ], "Resource": "*" } ] } ``` ------ After you configure the permissions to create Quick Sight topics with the Quick Sight APIs, use the following topics to create and work with Quick Sight topic APIs. **Topics** + [Work with Quick Sight topics using the Quick Sight APIs](topic-cli-examples.md) + [Configure Quick Sight topic refresh schedules with the Quick Sight CLI](topic-refresh-apis.md) + [Copy and migrate Quick Sight topics within and between AWS accounts](topic-cli-walkthroughs.md) + [Create and modify reviewed answers in Quick Sight topics with the Quick Sight APIs](topic-reviewed-answer-apis.md) # Work with Quick Sight topics using the Quick Sight APIs The following example creates a new topic. ``` aws quicksight create-topic --aws-account-id AWSACCOUNTID --topic-id TOPICID --topic TOPIC ``` You can also create a new topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see [Using CLI skeleton files](https://docs.aws.amazon.com/quicksight/latest/developerguide/cli-skeletons.html) in the *Amazon Quick Sight Developer Guide*. ``` aws quicksight create-topic --cli-input-json file://createtopic.json ``` When you create a new 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 Quick Sight topic refresh schedules with the Quick Sight CLI](topic-refresh-apis.md). After you create your first topic, you can update, delete, list, or request a summary of a topic. The following example updates a topic. ``` aws quicksight update-topic --aws-account-id AWSACCOUNTID --topic-id TOPICID --topic TOPIC ``` You can also update a topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see [Using CLI skeleton files](https://docs.aws.amazon.com/quicksight/latest/developerguide/cli-skeletons.html) in the *Amazon Quick Sight Developer Guide*. ``` aws quicksight update-topic --cli-input-json file://updatetopic.json ``` The following example provides a list of all topics in a Quick account. ``` aws quicksight list-topics --aws-account-id AWSACCOUNTID ``` The following example deletes a topic. ``` aws quicksight delete-topic --aws-account-id AWSACCOUNTID --topic-id TOPICID ``` The following example provides information about how a topic was configured. ``` aws quicksight describe-topic --aws-account-id AWSACCOUNTID --topic-id TOPICID ``` The following command updates the permissions of a topic. ``` aws quicksight update-topic-permissions --aws-account-id AWSACCOUNTID --topic-id TOPICID --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 Quick 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 topic. ``` aws quicksight describe-topic-permissions --aws-account-id AWSACCOUNTID --topic-id TOPICID ``` After you create a Quick Sight topic, you can use the Amazon Quick Sight APIs to [configure a topic refresh schedule](https://docs.aws.amazon.com/quicksuite/latest/userguide/topic-refresh-apis), [migrate Quick Sight topics within or between accounts](https://docs.aws.amazon.com/quicksuite/latest/userguide/topic-cli-walkthroughs), and [ create reviewed answers](https://docs.aws.amazon.com/quicksuite/latest/userguide/topic-reviewed-answer-apis). # Configure Quick Sight topic refresh schedules with the Quick Sight CLI The following command creates a refresh schedule of a topic. ``` aws quicksight create-topic-refresh-schedule --aws-account-id AWSACCOUNTID --topic-id TOPICID --dataset-arn DATASETARN --refresh-schedule REFRESHSCHEDULE ``` After you create a refresh schedule for a 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 topic. ``` aws quicksight update-topic-refresh-schedule --aws-account-id AWSACCOUNTID --topic-id TOPICID --dataset-id DATASETID --refresh-schedule REFRESHSCHEDULE ``` The following example provides a list of all refresh schedules configured to a topic. ``` aws quicksight list-topic-refresh-schedules --aws-account-id AWSACCOUNTID --topic-id TOPICID ``` The following example deletes a topic refresh schedule. ``` aws quicksight delete-topic-refresh-schedule --aws-account-id AWSACCOUNTID --topic-id TOPICID --dataset-id DATASETID ``` The following example provides information about how a topic refresh schedule was configured. ``` aws quicksight describe-topic-refresh-schedule --aws-account-id AWSACCOUNTID --topic-id TOPICID --dataset-id DATASETID ``` # Copy and migrate Quick Sight topics within and between AWS accounts You can migrate your Quick Sight topics from one account to another with the Quick Sight command line interface (CLI). Instead of manually replicating the same topic across multiple dashboards, namespaces, or accounts, you can use the Quick Sight CLI to reuse the same topic repeatedly. This capability saves Quick Sight authors time and creates a standardized topic experience for dashboard readers across multiple dashboards. To migrate topics with the Quick Sight CLI, use the following procedure **To migrate a topic to another account** 1. First, identify the topic that you want to migrate. You can view a list of every topic in your Quick account with a `list-topics` API command. ``` aws quicksight list-topics --aws-account-id AWSACCOUNTID ``` 1. After you have a list of 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-id TOPICID ``` 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" } ``` 1. Use the JSON response to create a skeleton file that you can input into a new `create-topic` call in your other Quick 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 topic to. For more information about CLI skeleton files, see [Using CLI skeleton files](https://docs.aws.amazon.com/quicksight/latest/developerguide/cli-skeletons.html) in the *Amazon Quick Sight Developer Guide*. ``` aws quicksight create-topic --aws-account-id AWSACCOUNTID \ --cli-input-json file://./create-topic-cli-input.json ``` After you make a `create-topic` call to the Quick Sight API, the new topic appears in your account. To confirm that the new topic exists, make a `list-topics` call to the Quick Sight 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. # Create and modify reviewed answers in Quick Sight topics with the Quick Sight APIs After you create a Quick Sight topic, you can use the Quick Sight APIs to create, list, update, and delete reiewed answers for topics. The command below batch creates up to 100 reviewed answers for a Quick Sight topic. ``` aws quicksight batch-create-topic-reviewed-answer \ --topic-id TOPICID \ --aws-account-id AWSACCOUNTID \ —answers ANSWERS ``` You can also batch create reviewed answers from a CLI skeleton file with the following command. For more information about CLI skeleton files, see [Using CLI skeleton files](https://docs.aws.amazon.com/quicksight/latest/developerguide/cli-skeletons.html) in the *Amazon Quick Sight Developer Guide*. ``` aws quicksight batch-create-topic-reviewed-answer \ --cli-input-json file://createTopicReviewedAnswer.json ``` The command below lists all reviewed answers in a Quick Sight topic. ``` aws quicksight list-topic-reviewed-answers \ --aws-account-id AWSACCOUNTID \ --topic-id TOPICID \ ``` The example below batch deletes up to 100 reviewed answers from a topic. ``` aws quicksight batch-delete-topic-reviewed-answer \ --topic-id TOPICID \ --aws-account-id AWSACCOUNTID \ —answer-ids: ["AnswerId1, AnswerId2…"] ``` You can also batch create topic reviewed answers form a CLI skeleton file with the following command. For more information about CLI skeleton files, see [Using CLI skeleton files](https://docs.aws.amazon.com/quicksight/latest/developerguide/cli-skeletons.html) in the *Amazon Quick Sight Developer Guide*. ``` aws quicksight batch-delete-topic-reviewed-answer \ --cli-input-json file://deleteTopicReviewedAnswer.json ``` To update a reviewed answer, delete the existing answer from the topic with the `batch-delete-topic-reviewed-answer` API. Then, use the `batch-create-topic-reviewed-answer` API to add the updated reviewed answer to the topic.