AWS quick documentation change
Summary
Added comprehensive documentation for API triggers in Amazon Quick Automate, including new sections on API triggers, IAM permissions configuration, StartAutomationJob and DescribeAutomationJob APIs, and examples of running automations with input/output payloads via API.
Security assessment
This change adds detailed security documentation about IAM permissions required for the new Automation Job APIs, including specific policy examples for StartAutomationJob and DescribeAutomationJob actions. It emphasizes the principle of least privilege and provides guidance on scoping resource ARNs. However, there is no evidence this addresses a specific security vulnerability or incident - it appears to be routine documentation for a new feature release.
Diff
diff --git a/quick/latest/userguide/deploying-automations.md b/quick/latest/userguide/deploying-automations.md index 5c54b33e9..e52ded035 100644 --- a//quick/latest/userguide/deploying-automations.md +++ b//quick/latest/userguide/deploying-automations.md @@ -7 +7 @@ -PrerequisitesDeploying an automationSetting up triggersDeploy and run automations with inputs and outputs +PrerequisitesDeploying an automationSetting up triggersRun automations with API triggers using input and outputDeploy and run automations with inputs and outputs @@ -99 +99,5 @@ At deployment, ensure that the correct credentials and connections are selected -Triggers determine when and how your automations run. You can configure automations to start based on a predefined schedule. To setup a trigger: +Triggers determine when and how your automations run. You can configure automations to start based on a predefined schedule or invoke them programmatically through the Amazon QuickSight API. + +### Schedules + +You can configure automations to start based on a predefined schedule. To setup a trigger: @@ -117,0 +122,318 @@ Triggers determine when and how your automations run. You can configure automati +### API triggers + +The Automation Job APIs enable you to programmatically start and monitor automation jobs from external applications. You can use these APIs to invoke deployed automations with custom input payloads and retrieve execution results through the AWS SDK and AWS CLI. + +The Automation Job APIs include two operations: + + * **StartAutomationJob** – Starts a new job for a deployed automation with an optional input payload. + + * **DescribeAutomationJob** – Retrieves the status, timestamps, and optional input and output payloads for a specified job. + + + + +These APIs are part of the Amazon QuickSight service namespace. You access them through the `quicksight` namespace in the AWS SDK and AWS CLI. + +For more information about AWS SDKs and toolkits, see the [AWS Getting Started Resource Center](https://aws.amazon.com/getting-started/tools-sdks/). + +#### Prerequisites + +Before you call the Automation Job APIs, complete the following setup steps. + +##### Find your automation identifiers + +To call the Automation Job APIs, you need the following identifiers: + + * **AWS account ID** – Your 12-digit AWS account ID. + + * **Automation group ID** – The unique ID of the automation group that contains your automation. + + * **Automation ID** – The unique ID of the automation you want to invoke. + + + + +You can find the automation group ID and automation ID in the Deployments section when you open any automation and have a deployed version. + +**To find your identifiers** + + * Sign in to Amazon Quick Automate. + + * In the left navigation pane, choose **Automations**. + + * Choose the automation group that contains your automation. + + * Choose the automation name to open the automation editor. + + * Choose the **Deployments** tab. + + * Choose the **Actions (⋮)** and **View deployment details** to get the **Automation ID** and **Group ID** at the top just below the heading Deployment Details. + + + + +##### Configure IAM permissions + +The Automation Job APIs require IAM permissions attached to your IAM identity (user, role, or group). Each operation requires a separate permission. + +**Permission for StartAutomationJob** + +Attach a policy that grants the `quicksight:StartAutomationJob` action. Scope the resource ARN to the specific automation that you want to allow. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowStartAutomationJob", + "Effect": "Allow", + "Action": [ + "quicksight:StartAutomationJob" + ], + "Resource": [ + "arn:aws:quicksight:us-west-2:111122223333:automation-group/EXAMPLE-GROUP-ID/automation/EXAMPLE-AUTOMATION-ID" + ] + } + ] + } + +**Permission for DescribeAutomationJob** + +Attach a policy that grants the `quicksight:DescribeAutomationJob` action. The resource ARN for this operation includes the job ID segment. To allow describing any job under an automation, use a wildcard (*) for the job segment. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowDescribeAutomationJob", + "Effect": "Allow", + "Action": [ + "quicksight:DescribeAutomationJob" + ], + "Resource": [ + "arn:aws:quicksight:us-west-2:111122223333:automation-group/EXAMPLE-GROUP-ID/automation/EXAMPLE-AUTOMATION-ID" + ] + } + ] + } + +AWS recommends scoping each permission to the most specific resource ARN possible to follow the principle of least privilege. For more information, see the following: + + * [IAM policy examples for Amazon QuickSight](https://docs.aws.amazon.com/quicksight/latest/user/iam-policy-examples.html) + + * [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) + + + + +##### Deploy your automation + +The StartAutomationJob API targets deployed automations only. You must commit and deploy your automation in the Amazon Quick Automate console before you can invoke it through the API. + +#### StartAutomationJob + +Starts a new job for a deployed automation. The operation is asynchronous — Amazon Quick Automate accepts the request, queues the job, and returns a **JobId** immediately. The automation runs in the background. If the automation has an input schema defined, Amazon Quick Automate validates the **InputPayload** against the schema before accepting the job. An invalid payload results in an **InvalidParameterValueException**. + +##### Request syntax + + + POST /accounts/AwsAccountId/automation-groups/AutomationGroupId/automations/AutomationId/jobs HTTP/1.1 + Content-type: application/json + + { + "InputPayload": "string" + } + +##### Request parameters + + * **AwsAccountId** (String, required) – Your AWS account ID (12 digits). + + * **AutomationGroupId** (String, required) – The ID of the automation group (UUID). + + * **AutomationId** (String, required) – The ID of the automation to run (UUID). + + * **InputPayload** (String, optional) – Input for the job as a JSON string. + + + + +##### Response elements + + * **Arn** (String) – ARN of the automation job. + + * **JobId** (String) – ID of the started job. Use this with `DescribeAutomationJob` to track status. + + * **Status** (Integer) – HTTP status code of the response. + + * **RequestId** (String) – AWS request ID. + + + + +##### Errors + + * **AccessDeniedException** – Insufficient permissions or invalid credentials. + + * **InvalidParameterValueException** – One or more parameters has a value that isn't valid. + + * **ResourceNotFoundException** – Automation group or automation not found. + + * **LimitExceededException** – A limit is exceeded. + + * **ThrottlingException** – Request was throttled. + + * **InternalFailureException** – Internal service error. + + + + +For more details, see the [API reference guide for StartAutomationJob](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_StartAutomationJob.html). + +#### DescribeAutomationJob + +Retrieves the status and details of a specified automation job, including execution timestamps and optional input and output payloads. Use this operation to poll for job completion after calling **StartAutomationJob**. + +The response does not include input and output payloads by default. Set the **IncludeInputPayload** and **IncludeOutputPayload** query parameters to `true` to request them. Amazon Quick Automate returns the output payload only when all of the following conditions are met: + + * **IncludeOutputPayload** is `true`. + + * **JobStatus** is `SUCCEEDED`. + + * The automation produced output values. +