Tagging Amazon Textract Insights resources
To help you manage your Amazon Textract Insights resources, you can assign metadata to them as tags. A tag is a label that you assign to an AWS resource. Each tag consists of a key and a value. You can tag projects, blueprints, and jobs.
Tags help you do the following:
Identify and organize your resources. Categorize projects, blueprints, and jobs by purpose, owner, environment, or application. Many AWS services support tagging, so you can apply the same tag across services to show that resources belong together.
Control access to your resources. Use tags in IAM policies to allow or deny actions on Amazon Textract Insights resources based on their tags (attribute-based access control, or ABAC).
For tagging best practices, see the AWS tagging best-practices guidance.
Before you begin, install and configure the AWS CLI or an AWS SDK. See Prerequisites and setup.
Taggable resources
You can tag the following Amazon Textract Insights resources.
Resource |
ARN format |
Tag at creation |
Tag after creation |
|---|---|---|---|
Blueprint |
|
|
|
Project |
|
|
|
Job |
|
|
|
Note the following:
Tags apply to a blueprint as a whole. You can't tag an individual blueprint version, and
CreateBlueprintVersiondoesn't accept tags.You can't tag public blueprints, such as
arn:aws:textract:us-east-1:aws:blueprint/public-w2-form, because AWS owns them.A job doesn't inherit tags from its project or blueprints. To tag a job, pass
--tagswhen you start it, or callTagResourceon the job ARN afterward.UpdateProjectandUpdateBlueprintdon't change tags. UseTagResourceandUntagResource.GetProject,GetBlueprint, andGetDocumentInsightsdon't return tags. UseListTagsForResource.You can tag only resources in your own account and in the AWS Region you call.
If you delete a resource, any tags associated with the resource are also deleted.
Tag a resource when you create it
Pass --tags as a map of key-value pairs.
Project
aws textract create-project \ --region us-east-1 \ --project-name "invoice-processing" \ --extraction-configuration '{"BoundingBox": {"State": "DISABLED"}, "Granularity": {"Types": ["PAGE"]}, "OutputFormat": {"TextFormat": {"Types": ["MARKDOWN"]}, "AdditionalFileFormat": {"State": "DISABLED"}}}' \ --custom-configuration '{"Blueprints": [{"BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-invoice"}]}' \ --tags '{"Team": "finance", "Environment": "production"}'
Blueprint
aws textract create-blueprint \ --region us-east-1 \ --blueprint-name "my-invoice-blueprint" \ --schema file://invoice-schema.json \ --tags '{"Team": "finance", "Environment": "production"}'
Job
aws textract start-document-insights \ --region us-east-1 \ --input-configuration S3Uri=s3://amzn-s3-demo-bucket/documents/invoice.pdf \ --output-configuration S3Uri=s3://amzn-s3-demo-destination-bucket/results \ --project-arn "arn:aws:textract:us-east-1:111122223333:project/abcd1234efgh" \ --tags '{"Team": "finance", "Workflow": "accounts-payable"}'
Tagging a resource when you create it requires the textract:TagResource permission in addition to the create permission. See Required permissions.
Manage tags on an existing resource
Use TagResource, ListTagsForResource, and UntagResource with the resource ARN.
Add or update tags
If a tag key already exists on the resource, TagResource replaces its value.
aws textract tag-resource \ --region us-east-1 \ --resource-arn "arn:aws:textract:us-east-1:111122223333:project/abcd1234efgh" \ --tags '{"Owner": "doc-platform-team"}'
List tags
aws textract list-tags-for-resource \ --region us-east-1 \ --resource-arn "arn:aws:textract:us-east-1:111122223333:project/abcd1234efgh"
{ "Tags": { "Team": "finance", "Environment": "production", "Owner": "doc-platform-team" } }
Remove tags
Specify the keys of the tags to remove.
aws textract untag-resource \ --region us-east-1 \ --resource-arn "arn:aws:textract:us-east-1:111122223333:project/abcd1234efgh" \ --tag-keys Owner Environment
Python (boto3)
import boto3 textract = boto3.client("textract", region_name="us-east-1") project_arn = "arn:aws:textract:us-east-1:111122223333:project/abcd1234efgh" # Add or update tags textract.tag_resource(ResourceARN=project_arn, Tags={"Team": "finance", "Environment": "production"}) # List tags print(textract.list_tags_for_resource(ResourceARN=project_arn)["Tags"]) # Remove tags textract.untag_resource(ResourceARN=project_arn, TagKeys=["Environment"])
When you view these operations in AWS CloudTrail, you can identify the resource being tagged by checking the request parameters in the event details.
Control access with tags
You can use the following condition keys in IAM policies for Amazon Textract Insights resources.
Condition key |
Use it to |
|---|---|
|
Allow or deny actions based on the tags already on a project, blueprint, or job. |
|
Require or restrict specific tag values in a request that creates or tags a resource. |
|
Control which tag keys a request can include. |
For examples of tag-based policies, see the IAM User Guide.
Required permissions
Tagging operations require the following permissions.
Action |
Required for |
|---|---|
|
Calling |
|
Calling |
|
Calling |
Add these actions to the policy in Data protection and encryption if your workflow uses tags.
Tag restrictions
Amazon Textract Insights tags have the following restrictions.
Restriction |
Value |
|---|---|
Maximum user tags per resource |
50 |
Tag key length |
1–128 characters |
Tag value length |
0–256 characters |
Allowed characters |
Unicode letters, numbers, and spaces, plus |
Reserved prefix |
Tag keys can't begin with |
Tag keys and values are case sensitive.
Next steps
To set up IAM for your workflow, see Data protection and encryption and Prerequisites and setup.
For request parameters and errors, see the Amazon Textract Insights API Reference