# Amazon Resource Names (ARNs) in Quick Sight ARNs in Quick Sight Amazon Resource Names (ARNs) uniquely identify AWS resources. An ARN identifies a resource unambiguously across all of AWS, for example in IAM policies, Amazon Relational Database Service (Amazon RDS) tags, and API calls. To retrieve the ARN of an Quick Sight resource, you can use the `Describe` operation on the relevant resource. You can use this section to learn how ARNs work. The material here provides examples are geared specifically for Quick Sight. **Topics** + [ # ARN formats ](arn-formats.md) + [ # Quick Sight resource ARNs ](resource-arns.md) + [ # Permissions for Quick Sight resources ](resource-permissions.md) + [ # Quick Sight API errors ](resource-errors.md) # ARN formats ARNs are delimited by colons, and composed of segments, which are the parts separated by colons `(:)`. The specific components and values used in the segments of an ARN depend on which AWS service the ARN is for. The following example shows how ARNs are constructed. ``` arn:partition:service:region:account-id:resource-id arn:partition:service:region:account-id:resource-type/resource-id arn:partition:service:region:account-id:resource-type:resource-id ``` These ARNs contain the following segments: `partition` – The partition that the resource is in. For standard AWS Regions, the partition is `aws`. If you have resources in other partitions, the partition is `aws-partitionname`. For example, the partition for resources in the China (Beijing) Region is `aws-cn`. `service` – The service namespace that identifies the AWS product. For example, `quicksight` identifies Quick Sight, `s3` identifies Amazon S3, `iam` identifies IAM, and so on. `region` – The AWS Region that the resource resides in. The ARNs for some resources don't require an AWS Region, so this component might be omitted in some cases, like in the case of S3. Quick Sight ARNs require an AWS Region. `account-id` – The ID of the AWS account that owns the resource. When you use the account number in an ARN or an API operation, you omit the hyphens (for example, 123456789012). The ARNs for some resources don't require an account number, so this component might be omitted. Quick Sight ARNs require an AWS account number. However, the account number and the AWS Region are omitted from S3 bucket ARNs, as shown following. ``` arn:aws:s3:::bucket_name arn:aws:s3:::bucket_name/key_name ``` `resource` or `resource-type` – The content of this part of the ARN varies by service. A resource identifier can be the name or ID of the resource (for example, `user/Bob` or `instance/i-1234567890abcdef0`) or a resource path. For example, some resource identifiers include a parent resource ( `sub-resource-type/parent-resource/sub-resource`) or a qualifier such as a version ( `resource-type:resource-name:qualifier`). Some resource ARNs can include a path, variable, or wildcard. You can use wildcard characters (`*` and `?`) within any ARN segment. An asterisk (`*`) represents any combination of zero or more characters, and a question mark (`?`) represents any single character. You can use multiple `*` or `?` characters in each segment. If you're using the ARN for permissions, avoid using `*` wildcards if possible, to limit access to only the required elements. Following are some examples of using paths, wildcards, and variables. For the following example, we use an S3 ARN. You might use this when you give permissions to S3 in an IAM policy. This S3 ARN shows a path and file are specified. **Note** The term key name is used to describe what looks like a path and file after `bucketname/`. These are called key names because a bucket doesn't actually contain folder structures like those used in your computer's file system. Instead the slash (`/`) is a delimiter that helps to make the organization of the bucket more intuitive. In this case, the bucket name is `amzn-s3-demo-bucket`, and the key name is `developers/design_info.doc`. ``` arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-2019-q4.json ``` To identify all the objects in the bucket, you can use a wildcard to indicate that all key names (or paths and files) are included in the ARN, as follows. ``` arn:aws:s3:::amzn-s3-demo-bucket/* ``` You can use part of a key name plus the wildcard to identify all the objects that begin with a specific pattern. In this case, it resembles a folder name plus a wildcard, as shown following. However, this ARN also includes any "subfolders" inside of `my-data`. ``` arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export* ``` In this case, specifying using this wildcard includes the objects with names like the following: + `my-data/sales-export-1.xlsx` + `my-data/sales-export-new.txt` + `my-data/sales-export-2019/file1.txt` You can use wildcards of both types (asterisks and question marks) in combination or separately, as shown following. ``` arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-2019-q?.* arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-20??-q?.* ``` Or, if you want to future-proof the ARN, you can replace the entire year with a wildcard, rather than just using wildcards for the last two digits. ``` arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-????-q?.* arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-*-q?.* ``` To read more about S3 ARNs, see [Specifying Resources in a Policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-arn-format.html) and [Object Key and Metadata](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html) in the *Amazon S3 User Guide*. # Quick Sight resource ARNs Quick Sight resource ARNs The following resource types are defined by Quick Sight: user, group, and dashboard. These are used in Quick Sight API calls and as elements of IAM permission statements. To find up-to-date information for Quick Sight (service prefix: quicksight) resources, actions, and condition context keys for use in IAM permission policies, see Actions, Resources, and Condition Keys for Quick Sight in the *IAM User Guide*. | Resource type | ARN format | Condition keys | | --- | --- | --- | | user | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:user/\$1\$1ResourceId\$1 | N/A | | group | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:group/\$1\$1ResourceId\$1 | N/A | | dashboard | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:dashboard/\$1\$1ResourceId\$1 | N/A | Resource ARNs are constructed from the segments that describe your resource. For example, a resource ARN for an analysis consists of the following segments. ``` arn::quicksight:::/ ``` The segments are defined as follows: + *`partition`* – for example, `aws` or `aws-cn`. + *`aws-region`* – The AWS Region that contains the resource. + *`aws-account-id`* – The AWS account that contains the resource. This ID excludes the hyphens. + *`resource-type`* – The type of resource. For this example, this is `analyses`. For a dashboard, it's `dashboard`. + *`resource-id`* – The unique identifier for a specific resource. The AWS Region, resource type, and resource ID are identified in the URL of the resource when you are using the Quick Sight console. For example, let's say this is the URL of the analysis that you want an ARN for. ``` https://us-east-2.quicksight.aws.amazon.com/sn/analysis/4036e682-7de6-4c05-8a76-be51b9ec9b29 ``` The AWS Region is `us-east-2`. The resource-type is `analysis`. The resource ID in this URL is `4036e682-7de6-4c05-8a76-be51b9ec9b29`. If your account number is `111122223333`, then the ARN for this analysis is as follows. ``` arn:aws:quicksight:us-east-2:111122223333:analysis/4036e682-7de6-4c05-8a76-be51b9ec9b29 ``` To get your AWS account number, contact your system administrator. # Permissions for Quick Sight resources Permissions 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 highly 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 ARN. To retrieve the ARN of an Quick Sight resource, use the `Describe` operation on the relevant resource. Before you can call the Quick Sight API operations, you need the `quicksight:operation-name` permission in a 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 attempt to make the call you don't have permissions to call, the resulting error shows you what the missing permission is. We highly recommend that you restrict each permission as much as possible. You can add conditions in IAM to further restrict access to an API in some scenarios. For example, when you add `User1` to `Group1`, the main resource is `Group1`. You can allow or deny access to certain groups. Or you can also edit the Quick Sight IAM key `quicksight:UserName` to add a condition to allow or prevent certain users from being added to that group. For more information, see the following: + [Actions, Resources, and Condition Keys](https://docs.aws.amazon.com//IAM/latest/UserGuide/list_amazonquicksight.html) + [IAM JSON Policy Elements](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_elements.html) ## Best practices By working with Quick Sight, you can share analyses, dashboards, templates, and themes with up to 100 principals. A *principal* can be one of the following: + The Amazon Resource Name (ARN) of an Quick Sight user or group associated with a data source or dataset. (This is common.) + The ARN of an Quick Sight user, group, or namespace associated with an analysis, dashboard, template, or theme. (This is common.) + The ARN of an AWS account root: This is an IAM ARN rather than a Quick Sight ARN. Use this option only to share resources (templates) across AWS accounts. (This is less common.) To share these resources with more principals, consider assigning resource permissions at the group or namespace level. For example, if you add users into a group and share a resource to the group, the group counts as one principal. This is true even though it's shared to everyone in the group. # Quick Sight API errors Errors Quick Sight has two types of error codes: + **Client errors** – These errors are usually caused by something the client did. An example is specifying an incorrect or invalid parameter in the request. Another is using an action or resource for a user that doesn't have permission to use the action or resource. These errors are accompanied by a 400-series HTTP response code. + **Server errors** – These errors are usually caused by an AWS server-side issue. These errors are accompanied by a 500-series HTTP response code. **Topics** + [ ## Common client errors ](#resource-errors-client) + [ ## Client errors ](#resource-errors-table-client) + [ ## Server errors ](#qs-api-errors-table-server) ## Common client errors Following, you can find a list of the common client errors that all operations can return. | Error code | Description | | --- | --- | | AuthFailure | The provided credentials couldn't be validated. You might not be authorized to carry out the request. Ensure that your account is authorized to use the Quick Sight service and that your credit card details are correct. Also ensure that you're using the correct access keys. | | Blocked | Your account is currently blocked. Contact [Support](https://support.aws.amazon.com/#/contacts/aws-account-verification) if you have questions. | | DryRunOperation | The user has the required permissions, so the request would have succeeded, but the DryRun parameter was used. | | IdempotentParameterMismatch | The request uses the same client token as a previous, but nonidentical request. Don't reuse a client token with different requests, unless the requests are identical. | | IncompleteSignature | The request signature doesn't conform to AWS standards. | | InvalidAction | The action or operation requested isn't valid. Verify that the action is typed correctly. | | InvalidCharacter | A specified character isn't valid. | | InvalidClientTokenId | The X.509 certificate or AWS access key ID provided doesn't exist in our records. | | InvalidPaginationToken | The specified pagination token isn't valid or is expired. | | InvalidParameter | A parameter specified in a request isn't valid, is unsupported, or can't be used. The returned message provides an explanation of the error value. | | InvalidParameterCombination | A value that indicates an incorrect combination of parameters, or a missing parameter. | | InvalidParameterValue | A value specified in a parameter isn't valid, is unsupported, or can't be used. Ensure that you specify a resource by using its full ID. The returned message provides an explanation of the error value. | | InvalidQueryParameter | The AWS query string is malformed or doesn't adhere to AWS standards. | | MalformedQueryString | The query string contains a syntax error. | | MissingAction | The request is missing an action or a required parameter. | | MissingAuthenticationToken | The request must contain either a valid (registered) AWS access key ID or X.509 certificate. | | MissingParameter | The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request, for example the resource ID. | | OptInRequired | You aren't authorized to use the requested service. Ensure that you have subscribed to the service you are trying to use. If you are new to AWS, your account might take some time to be activated while your credit card details are being verified. | | PendingVerification | Your account is pending verification. Until the verification process is complete, you might not be able to carry out requests with this account. If you have questions, contact [AWS Support](https://console.aws.amazon.com/support/home#/). | | RequestExpired | The request reached the service more than 15 minutes after the date stamp on the request or the request expiration date (such as for presigned URLs). Or the date stamp on the request is more than 15 minutes in the future. If you're using temporary security credentials, this error can also occur if the credentials have expired. For more information, see [Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the IAM User Guide. | | UnauthorizedOperation | You aren't authorized to perform this operation. Check your IAM policies, and ensure that you are using the correct access keys. | | UnknownParameter | An unknown or unrecognized parameter was supplied. Requests that can cause this error include supplying a misspelled parameter or a parameter that isn't supported for the specified API version. | | UnsupportedInstanceAttribute | The specified attribute can't be modified. | | UnsupportedOperation | The specified request includes an unsupported operation. The returned message provides details of the unsupported operation. | | UnsupportedProtocol | The protocol that you used is unsupported. | | ValidationError | The input fails to satisfy the constraints specified by an AWS service. | ## Client errors Following, you can find a list of client errors that are specific to Quick Sight API operations. | Error code | Description | | --- | --- | | AccessDeniedException | You don't have access to this. The provided credentials can't be validated. You might not be authorized to carry out the request. Ensure that your account is authorized to use the Amazon Quick Sight service and that your policies have the correct permissions. Also, ensure that you are using the correct access keys. | | DomainNotWhiteListedException | The domain specified isn't on the allow list. Make sure that all domains for embedded dashboards are added to the approved list by an Amazon Quick Sight administrator. | | IdentityTypeNotSupportedException | The identity type specified isn't supported. Supported identity types include: IAM and QUICKSIGHT. | | InvalidNextTokenException | The NextToken value isn't valid. | | InvalidParameterValueException | One or more parameters doesn't have a valid value. | | PreconditionNotMetException | One or more preconditions aren't met. | | QuickSightUserNotFoundException | The user isn't found. This can happen in any operation that requires finding a user based on the provided user name, such as DeleteUser, DescribeUser, and so on. | | ResourceExistsException | The resource specified doesn't exist. | | ResourceNotFoundException | One or more resources couldn't be found. | | SessionLifetimeInMinutesInvalidException | The number of minutes specified for the lifetime of a session is invalid. The session lifetime must be 15–600 minutes. | | ThrottlingException | Access is throttled. | | UnsupportedUserEditionException | Indicates that you are calling an operation on an Amazon Quick Sight subscription where the edition doesn't include support for that operation. Amazon Quick Sight currently has Standard Edition and Enterprise Edition. Not every operation and capability is available in every edition. | ### Common causes of client errors There are a number of reasons that you might encounter an error while performing a request. Some errors can be prevented or easily solved by following these guidelines: + **Specify the AWS account ID and namespace** – Make sure that the relevant AWS account ID are provided with each request. The namespace must be set to `default`. + **Allow for eventual consistency** – Some errors are caused because a previous request hasn't yet propagated through the system. + **Use a sleep interval between request rates** – Quick Sight API requests are throttled to help maintain the performance of the service. If your requests have been throttled, you get an error. + **Use the full ID of the resource** – When specifying a resource, ensure that you use its full ID, and not its user-supplied name or description. + **Check your services** – Ensure that you have signed up for all the services you are attempting to use. You can check which services you're signed up for by going to the **My Account** section of the [AWS home page](http://aws.amazon.com). + **Check your permissions** – Ensure that you have the required permissions to carry out the request. + **Check your VPC** – Some resources can't be shared between virtual private clouds (VPCs), for example security groups. + **Check your credentials** – Ensure that you provide your access keys when you are making requests and that you have entered the credentials correctly. Also, if you have more than one account, ensure that you are using the correct credentials for a particular account. If the provided credentials are incorrect, you might get the following error: `Client.AuthFailure`. ## Server errors Following, you can find a list of errors that can be returned by the server. | Error code | Description | | --- | --- | | BatchClientRequestTokensNotDistinctException | The batch client request tokens aren't unique. | | EmptyBatchRequestException | The batch request was empty. | | InternalFailureException | An internal failure occurred. | | InternalServiceError | There was an internal error from the service. | | InvalidBatchClientRequestTokenException | The AWS request token for this client batch request is invalid. | | InvalidParameterException | One or more parameters has a value that isn't valid. | | LimitExceededException | A limit is exceeded. | | ResourceUnavailableException | This resource is currently unavailable. | | TooManyEntriesInBatchRequestException | There are too many entries in this batch request. |