# Get started with the Amazon Quick Sight API You can manage most aspects of your deployment with the AWS SDKs to access an API that's tailored to the programming language or platform that you're using. For more information, see [AWS SDKs](http://aws.amazon.com/tools/#SDKs). For more information about specific API operations, see [Quick Sight API Reference](https://docs.aws.amazon.com/quicksight/index.html?id=docs_gateway). Use the topics in this section to get started with the Quick Sight API and SDKs. **Topics** + [Prerequisites](getting-started-prerequisites.md) + [Make API requests with the Quick Sight SDKs](getting-started-making-api-requests.md) + [Use CLI skeleton files](cli-skeletons.md) + [Use the Quick Sight Dev Portal](getting-started-dev-portal.md) # Prerequisites If you plan to access Quick Sight through its API, make sure you're familiar with the following: + JSON + Web services + HTTP requests + One or more programming languages, such as JavaScript, Java, Python, or C\$1 We recommend visiting the AWS [Getting Started Resource Center](https://aws.amazon.com/getting-started/tools-sdks/) for a tour of what AWS SDKs and toolkits have to offer. Although you can use a terminal and your favorite text editor, you might benefit from the more visual UI experience you get in an integrated development environment (IDE). We provide a list of IDEs in the AWS Getting Started Resource Center in the [IDE and IDE Toolkits](https://aws.amazon.com/getting-started/tools-sdks/#IDE_and_IDE_Toolkits) section. This site provides AWS toolkits that you can download for your preferred IDE. Some IDEs also offer tutorials to help you learn more about programming languages. Before you can call the Quick Sight API operations, make sure that you have the `quicksight:operation-name` permission in an IAM policy attached to your IAM identity. For example, to call `list-users`, you need the permission `quicksight:ListUsers`. The same pattern applies to all operations. If you’re not sure what the necessary permission is, you can attempt to make a call. The client then tells you what the missing permission is. You can use asterisk (`*`) in the Resource field of your permission policy instead of specifying explicit resources. However, we recommend that you restrict each permission as much as possible. You can restrict user access by specifying or excluding resources in the policy, using their Quick Sight Amazon Resource Name (ARN) identifier. For more information, see the following: + [IAM Policy Examples](https://docs.aws.amazon.com/quicksight/latest/user/iam-policy-examples.html) in the *Amazon Quick Sight User Guide* + [Actions, Resources, and Condition Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazoninspector.html) in the *IAM User Guide* + [IAM JSON Policy Elements](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide* To retrieve the ARN of a user or a group, use the `Describe` operation on the relevant resource. You can also add conditions in IAM to further restrict access to an API in some scenarios. For instance, when adding `User1` to `Group1`, the main resource is `Group1`, so you can allow or deny access to certain groups. However, you can also add a condition by using the Quick Sight IAM key `quicksight:UserName` to allow or prevent certain users from being added to that group. Following is an example policy. It means that the caller with this policy attached can invoke the `CreateGroupMembership` operation for any group, if the user name they are adding to the group isn't `user1`. ``` { "Effect": "Allow", "Action": "quicksight:CreateGroupMembership", "Resource": "arn:aws:quicksight:us-east-1:aws-account-id:group/default/*", "Condition": { "StringNotEquals": { "quicksight:UserName": "user1" } } } ``` ------ #### [ AWS CLI ] The following procedure explains how to interact with Quick Sight API operations through the AWS Command Line Interface (AWS CLI). The following instructions have been tested in Bash but should be identical or similar in other command-line environments. **To use Quick Sight API operations through the AWS CLI** 1. Install AWS SDK in your environment. For instructions, see [AWS Command line Interface](https://aws.amazon.com/cli/). 1. Set up your AWS CLI identity and AWS Region using the following command and follow-up instructions. Use the credentials for an IAM identity or role that has the proper permissions. ``` aws configure ``` 1. Look at Quick Sight SDK help by running the following command. ``` aws quicksight help ``` 1. To get detailed instructions on how to use an API, enter its name followed by `help`, as follows. ``` aws quicksight list-users help ``` 1. Call an Quick Sight API operation. The following example returns a list of Quick Sight users in your account. ``` aws quicksight list-users \ --aws-account-id aws-account-id \ --namespace default \ --region us-east-1 ``` ------ #### [ Java SDK ] Use the following procedure to set up a Java app that interacts with Quick Sight. **To set up a Java app that works with Quick Sight** 1. Create a Java project in your IDE. 1. Import the Quick Sight SDK into your new project, for example: `AWSQuickSightJavaClient-1.11.x.jar` 1. After your IDE indexes the Quick Sight SDK, add an import line as follows. ``` import com.amazonaws.services.quicksight.AmazonQuickSight; ``` If your IDE doesn't recognize line this as valid, verify that you imported the SDK. 1. Download and import external dependencies for the Quick Sight SDK. Like other AWS SDKs, Quick Sight SDK requires external dependencies to perform many of its functions. Make sure to download and import those into the same project. The following dependencies are required: + `aws-java-sdk-1.11.402.jar` (AWS Java SDK and credentials setup) – To download, see [Set up the AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html) in the SDK for Java documentation. + `commons-logging-1.2.jar` – To download, see [Download Apache Commons Logging](https://commons.apache.org/proper/commons-logging/download_logging.cgi) on the Apache Commons website. + `jackson-annotations-2.9.6.jar`, `jackson-core-2.9.6.jar`, and `jackson-databind-2.9.6.jar` – To download, see [the Maven repository](https://repo1.maven.org/maven2/com/fasterxml/jackson/core/). + `httpclient-4.5.6.jar`, `httpcore-4.4.10.jar` – To download, see [the Apache site](https://hc.apache.org/downloads.cgi). + `joda-time-2.1.jar` – To download, see [the MVNrepository Joda Time site.](https://mvnrepository.com/artifact/joda-time/joda-time/2.1) 1. Create an Quick Sight client. You can use a default public endpoint that the client can communicate with, or you can reference the endpoint explicitly. There are multiple ways to provide your AWS credentials. In the following example, we provide a direct, simple approach. The following client method is used to make all the API calls that follow. ``` private static AmazonQuickSight getClient() { final AWSCredentialsProvider credsProvider = new AWSCredentialsProvider() { @Override public AWSCredentials getCredentials() { // provide actual IAM access key and secret key here return new BasicAWSCredentials("access-key", "secret-key"); } @Override public void refresh() {} }; return AmazonQuickSightClientBuilder .standard() .withRegion(Regions.US_EAST_1.getName()) .withCredentials(credsProvider) .build(); } ``` 1. Use the client that you just created to list all the users in our Quick Sight account. Provide the AWS account ID that you used to subscribe to Quick Sight. This ID must match the AWS account ID of the caller's identity. Cross-account calls aren't supported at this time. Also, make sure that the required parameter `namespace` is set to *`default`*. ``` getClient().listUsers(new ListUsersRequest() .withAwsAccountId("relevant_AWS_account_ID") .withNamespace("default")) .getUserList().forEach(user -> { System.out.println(user.getArn()); }); ``` 1. See a list of all possible API operations and the request objects they use by choosing the CTRL key and clicking the client object in your IDE view of the Quick Sight interface. Or find this list in the `com.amazonaws.services.quicksight` package in the Quick Sight JavaClient .jar file. ------ #### [ JavaScript (Node.js) SDK ] Use the following procedure to interact with Quick Sight using Node.js. **To work with Quick Sight using Node.js** 1. Set up your node environment using the following commands: + `npm install aws-sdk` + `npm install aws4 ` + `npm install request` + `npm install url` For information on configuring the Node.js with AWS SDK and setting your credentials, see the [AWS SDK for JavaScript Developer Guide for SDK v2](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html). 1. Use the following code example to test your setup. HTTPS is required. The example displays a full listing of Quick Sight operations along with their URL request parameters, followed by a list of Quick Sight users in your account. ``` const AWS = require('aws-sdk'); const https = require('https'); var quicksight = new AWS.Service({ apiConfig: require('./quicksight-2018-04-01.min.json'), region: 'us-east-1', }); console.log(quicksight.config.apiConfig.operations); quicksight.listUsers({ // Enter your actual AWS account ID 'AwsAccountId': 'relevant_AWS_account_ID', 'Namespace': 'default', }, function(err, data) { console.log('---'); console.log('Errors: '); console.log(err); console.log('---'); console.log('Response: '); console.log(data); }); ``` ------ #### [ Python3 SDK ] Use the following procedure to create a custom-built `botocore` package to interact with Quick Sight. **To create a custom botocore package to work with Quick Sight** 1. Create a credentials file in the AWS directory for your environment. In a Linux- or macOS-based environment, that file is called `~/.aws/credentials` and looks like the following. ``` [default] aws_access_key_id = Your_IAM_access_key aws_secret_access_key = Your_IAM_secret_key ``` 1. Unzip the folder `botocore-1.12.10`. Change directory into `botocore-1.12.10` and enter the Python3 interpreter environment. Each response comes back as a dictionary object. They each have a `ResponseMetadata` entry that contains request IDs and response status. Other entries are based on what type of operation you run. 1. As a test, use the following example code, a sample app that first creates, deletes, and lists groups. Then it lists users in a Quick Sight account. ``` import botocore.session default_namespace = 'default' account_id = 'relevant_AWS_Account' session = botocore.session.get_session() client = session.create_client("quicksight", region_name='us-east-1') print('Creating three groups: ') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2') client.create_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3') print('Retrieving the groups and listing them: ') response = client.list_groups(AwsAccountId = account_id, Namespace=default_namespace) for group in response['GroupList']: print(group) print('Deleting our groups: ') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup1') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup2') client.delete_group(AwsAccountId = account_id, Namespace=default_namespace, GroupName='MyGroup3') response = client.list_users(AwsAccountId = account_id, Namespace=default_namespace) for user in response['UserList']: print(user) ``` ------ #### [ .NET/C\$1 SDK ] Use the following procedure to interact with Quick Sight using C\$1.NET. This example is constructed on Microsoft Visual for Mac; the instructions can vary slightly based on your IDE and platform. **To work with Quick Sight using C\$1.NET** 1. Unzip the `nuget.zip` file into a folder called `nuget`. 1. Create a new **Console app** project in Visual Studio. 1. Under your solution, locate app **Dependencies**, then open the context (right-click) menu and choose **Add Packages**. 1. In the sources list, choose **Configure Sources**. 1. Choose **Add**, and name the source `QuickSightSDK`. Browse to the `nuget` folder and choose **Add Source**. 1. Choose **OK**. Then, with `QuickSightSDK` selected, select all three Quick Sight packages: + `AWSSDK.QuickSight` + `AWSSDK.Extensions.NETCore.Setup` + `AWSSDK.Extensions.CognitoAuthentication` 1. Choose **Add Package**. 1. Copy and paste the following sample app into your console app editor. ``` using System; using Amazon.QuickSight.Model; using Amazon.QuickSight; namespace DotNetQuickSightSDKTest { class Program { private static readonly string AccessKey = "insert_your_access_key"; private static readonly string SecretAccessKey = "insert_your_secret_key"; private static readonly string AccountID = "AWS_account_ID"; private static readonly string Namespace = "default"; // leave this as default static void Main(string[] args) { var client = new AmazonQuickSightClient( AccessKey, SecretAccessKey, Amazon.RegionEndpoint.USEast1); var listUsersRequest = new ListUsersRequest { AwsAccountId = AccountID, Namespace = Namespace }; client.ListUsersAsync(listUsersRequest).Result.UserList.ForEach( user => Console.WriteLine(user.Arn) ); var listGroupsRequest = new ListGroupsRequest { AwsAccountId = AccountID, Namespace = Namespace }; client.ListGroupsAsync(listGroupsRequest).Result.GroupList.ForEach( group => Console.WriteLine(group.Arn) ); } } } ``` ------ # Make API requests with the Quick Sight SDKs You can use API operations for Amazon Quick Sight and AWS SDKs to access Quick Sight from your preferred programming language. Currently, you can use the Amazon Quick Sight API to manage users and groups. In Enterprise Edition, you can also use the API to embed dashboards in your webpage or app. To monitor the calls made to the Quick Sight API for your account, including calls made by the AWS Management Console, command line tools, and other services, use AWS CloudTrail. For more information, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/). AWS provides libraries, sample code, tutorials, and other resources for software developers who prefer to build applications using language-specific API operations instead of submitting a request over HTTPS. These libraries provide basic functions that automatically take care of tasks such as cryptographically signing your requests, retrying requests, and handling error responses. These libraries help make it easier for you to get started. For more information about downloading the AWS SDKs, see [AWS SDKs and Tools](https://aws.amazon.com/tools/). The following links are a sample of the language-specific API documentation available. **AWS Command Line Interface** + [AWS CLI Quick Sight Command Reference](https://docs.aws.amazon.com/cli/latest/reference/quicksight/index.html) + [AWS CLI User Guide](https://docs.aws.amazon.com/cli/latest/userguide/) + [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/) **AWS SDK for .NET** + [Amazon.Quicksight](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSight.html) + [Amazon.Quicksight.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSightModel.html) **AWS SDK for C\$1\$1** + [Aws::QuickSight::QuickSightClient Class Reference](https://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_quick_sight_1_1_quick_sight_client.html) **AWS SDK for Go** + [quicksight](https://docs.aws.amazon.com/sdk-for-go/api/service/quicksight/) **AWS SDK for Java** + [QuickSightClient](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/package-summary.html) + [QuickSightModel](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/model/package-summary.html) **AWS SDK for JavaScript** + [AWS.QuickSight](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/QuickSight.html) **AWS SDK for PHP** + [QuickSightClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.QuickSight.QuickSightClient.html) **AWS SDK for Python (Boto3)** + [QuickSight](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/quicksight.html) **AWS SDK for Ruby** + [Aws::QuickSight](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/QuickSight.html) # Use CLI skeleton files To run AWS CLI commands that require long and complicated strings, you can generate CLI skeleton files . A *CLI skeleton* is a JSON file that provides you with an outline, or skeleton, of the command that you want to run. You can use a CLI skeleton file for every Quick Sight command, but skeleton files are most useful when using `Create` or `Update` commands. ## Generate a CLI skeleton file To generate a CLI skeleton file, enter the following command into your terminal. ``` aws quicksight OPERATION --generate-cli-skeleton ``` A JSON file that contains a skeleton of the command that you want to run then appears in your terminal. Enter the required input values and save the file. The following example shows a cli example that is generated for the `UpdateDashboardPermissions` API. ``` $ aws quicksight update-dashboard-permissions --generate-cli-skeleton { "AwsAccountId": "", "DashboardId": "", "GrantPermissions":[ { "Principal": "", "Actions": [ "" ] } ], "RevokePermissions": [ { "Principal": "", "Actions": [ "" ] } ] } ``` Enter the following to make a CLI command using the saved skeleton file. ``` aws quicksight COMMAND --cli-input-json file://filename.json ``` You can update and reuse CLI skeleton files to run future commands. ## Operations that skeleton files are most useful for You can use a CLI skeleton file for every command in Quick Sight. However, skeleton files are most useful for commands that require long or complicated string inputs, such as a permissions update. Following is a list of Quick Sight operations where we recommend using a CLI skeleton file: **Account customization operations** + [CreateAccountCustomization](create-account-customization.md) + [UpdateAccountCustomization](update-account-customization.md) + [UpdateAccountSettings](update-account-settings.md) **Analysis operations** + [CreateAnalysis](create-analysis.md) + [UpdateAnalysis](update-analysis.md) + [UpdateAnalysisPermissions](update-analysis-permissions.md) **Dashboard operations** + [CreateDashboard](create-dashboard.md) + [UpdateDashboard](update-dashboard.md) + [UpdateDashboardPermissions](update-dashboard-permissions.md) + [UpdateDashboardPublishedVersion](update-dashboard-published-version.md) **Dataset operations** + [CreateDataSet](create-data-set.md) + [UpdateDataSet](update-data-set.md) + [UpdateDataSetPermissions](update-data-set-permissions.md) **Data source operations** + [CreateDataSource](create-data-source.md) + [UpdateDataSource](update-data-source.md) + [UpdateDataSourcePermissions](update-data-source-permissions.md) **Folder operations** + [CreateFolder](create-folder.md) + [CreateFolderMembership](create-folder-membership.md) + [UpdateFolder](update-folder.md) + [UpdateFolderPermissions](update-folder-permissions.md) **Group operations** + [CreateGroup](create-group.md) + [CreateGroupMembership](create-group-membership.md) + [UpdateGroup](update-group.md) **IAM policy assignment operations** + [CreateIAMPolicyAssignment](create-iam-policy-assignment.md) + [UpdateIAMPolicyAssignment](update-iam-policy-assignment.md) **Ingestion operations** + [CreateIngestion](create-ingestion.md) **Namespace operations** + [CreateNamespace](create-namespace.md) **Template operations** + [CreateTemplate](create-template.md) + [UpdateTemplate](update-template.md) + [UpdateTemplatePermissions](update-template-permissions.md) **Template alias operations** + [CreateTemplateAlias](create-template-alias.md) + [UpdateTemplateAlias](update-template-alias.md) **Theme operations** + [CreateTheme](create-theme.md) + [UpdateTheme](update-theme.md) + [UpdateThemePermissions](update-theme-permissions.md) **Theme alias permissions** + [CreateThemeAlias](create-theme-alias.md) + [UpdateTemplateAlias](update-template-alias.md) **User operations** + [RegisterUser](register-user.md) + [UpdateUser](update-user.md) # Use the Quick Sight Dev Portal The Dev Portal helps you learn by example how to use the Quick Sight API in your website or application. Currently, the Dev Portal focuses on API operations for embedded analytics. The portal provides easy-to-use code samples to get you started. You can choose from the following three different use cases: + Displaying embedded dashboards to everyone (nonauthenticated users) + Personalizing dashboards for your users + Embedding dashboard authoring The portal itself displays dashboards by using embedding for everyone. **To get started with the Dev Portal** 1. Open the Dev Portal and choose **Try it** on the use case that you want to view. 1. View code examples by choosing **How to embed it** in the menu bar. Then choose each of the following from the navigation pane at left: + Configure permissions + Get embedding URL (code samples in Java, JavaScript, and Python) + Embed URL in your application 1. Choose **Download all code** to download all of the code in a .zip file. 1. Choose **How to customize it** to customize the dashboard, This screen is interactive, so you can choose any item in the navigation pane to view the changes live. 1. View and download the HTML code at bottom left. 1. Choose the Quick Sight icon at upper left to return to the start page.