Tagging API - AWS Lake Formation

Tagging API

The Tagging API describes the data types and API related to an authorization strategy that defines a permissions model on attributes or key-value pair tags.

Data Types

Tag Structure

A structure for a key-value pair tag.

Fields

  • key – UTF-8 string, not less than 1 or more than 128 bytes long.

    The key for the tag.

  • value – UTF-8 string, not more than 256 bytes long.

    The value of the tag.

LFTagKeyResource Structure

A structure containing a tag key and values for a resource.

Fields

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The key-name for the tag.

  • TagValuesRequired: An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of possible values an attribute can take.

LFTagPolicyResource Structure

A structure containing a list of tag conditions that apply to a resource's tag policy.

Fields

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ResourceTypeRequired: UTF-8 string (valid values: DATABASE | TABLE).

    The resource type for which the tag policy applies.

  • ExpressionRequired: An array of LFTag objects, not less than 1 or more than 5 structures.

    A list of tag conditions that apply to the resource's tag policy.

TaggedTable Structure

A structure describing a table resource with tags.

Fields

  • Table – A TableResource object.

    A table that has tags attached to it.

  • LFTagOnDatabase – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags attached to the database where the table resides.

  • LFTagsOnTable – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags attached to the table.

  • LFTagsOnColumns – An array of ColumnLFTag objects.

    A list of tags attached to columns in the table.

TaggedDatabase Structure

A structure describing a database resource with tags.

Fields

  • Database – A DatabaseResource object.

    A database that has tags attached to it.

  • LFTags – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags attached to the database.

LFTag Structure

A structure that allows an admin to grant user permissions on certain conditions. For example, granting a role access to all columns not tagged 'PII' of tables tagged 'Prod'.

Fields

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag.

  • TagValuesRequired: An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of possible values an attribute can take.

LFTagPair Structure

A structure containing a tag key-value pair.

Fields

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag.

  • TagValuesRequired: An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of possible values an attribute can take.

LFTagError Structure

A structure containing an error related to a TagResource or UnTagResource operation.

Fields

  • LFTag – A LFTagPair object.

    The key-name of the tag.

  • Error – An ErrorDetail object.

    An error that occurred with the attachment or detachment of the tag.

ColumnLFTag Structure

A structure containing the name of a column resource and the tags attached to it.

Fields

  • Name – UTF-8 string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The name of a column resource.

  • LFTags – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    The tags attached to a column resource.

Operations

AddLFTagsToResource Action (Python: add_lf_tags_to_resource)

Attaches one or more tags to an existing resource.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ResourceRequired: A Resource object.

    The resource to which to attach a tag.

  • LFTagsRequired: An array of LFTagPair objects, not less than 1 or more than 50 structures.

    The tags to attach to the resource.

Response

  • Failures – An array of LFTagError objects.

    A list of failures to tag the resource.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • AccessDeniedException

  • ConcurrentModificationException

RemoveLFTagsFromResource Action (Python: remove_lf_tags_from_resource)

Removes a tag from the resource. Only database, table, or tableWithColumns resource are allowed. To tag columns, use the column inclusion list in tableWithColumns to specify column input.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ResourceRequired: A Resource object.

    The resource where you want to remove a tag.

  • LFTagsRequired: An array of LFTagPair objects, not less than 1 or more than 50 structures.

    The tags to be removed from the resource.

Response

  • Failures – An array of LFTagError objects.

    A list of failures to untag a resource.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException

  • ConcurrentModificationException

GetResourceLFTags Action (Python: get_resource_lf_tags)

Returns the tags applied to a resource.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ResourceRequired: A Resource object.

    The resource for which you want to return tags.

  • ShowAssignedLFTags – Boolean.

    Indicates whether to show the assigned tags.

Response

  • LFTagOnDatabase – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags applied to a database resource.

  • LFTagsOnTable – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags applied to a table resource.

  • LFTagsOnColumns – An array of ColumnLFTag objects.

    A list of tags applied to a column resource.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException

ListLFTags Action (Python: list_lf_tags)

Lists tags that the requester has permission to view.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ResourceShareType – UTF-8 string (valid values: FOREIGN | ALL).

    If resource share type is ALL, returns both in-account tags and shared tags that the requester has permission to view. If resource share type is FOREIGN, returns all share tags that the requester can view. If no resource share type is passed, lists tags in the given catalog ID that the requester has permission to view.

  • MaxResults – Number (integer), not less than 1 or more than 1000.

    The maximum number of results to return.

  • NextToken – UTF-8 string.

    A continuation token, if this is not the first call to retrieve this list.

Response

  • LFTags – An array of LFTagPair objects, not less than 1 or more than 50 structures.

    A list of tags that the requested has permission to view.

  • NextToken – UTF-8 string.

    A continuation token, present if the current list segment is not the last.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • AccessDeniedException

CreateLFTag Action (Python: create_lf_tag)

Creates a tag with the specified name and values.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag.

  • TagValuesRequired: An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of possible values an attribute can take.

Response

  • No Response parameters.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • ResourceNumberLimitExceededException

  • InternalServiceException

  • OperationTimeoutException

  • AccessDeniedException

GetLFTag Action (Python: get_lf_tag)

Returns a tag definition.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag.

Response

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKey – UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag.

  • TagValues – An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of possible values an attribute can take.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • AccessDeniedException

UpdateLFTag Action (Python: update_lf_tag)

Updates the list of possible values for the specified tag key. If the tag does not exist, the operation throws an EntityNotFoundException. The values in the delete key values will be deleted from list of possible values. If any value in the delete key values is attached to a resource, then API errors out with a 400 Exception - "Update not allowed". Untag the attribute before deleting the tag key's value.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag for which to add or delete values.

  • TagValuesToDelete – An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of tag values to delete from the tag.

  • TagValuesToAdd – An array of UTF-8 strings, not less than 1 or more than 50 strings.

    A list of tag values to add from the tag.

Response

  • No Response parameters.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • ConcurrentModificationException

  • AccessDeniedException

DeleteLFTag Action (Python: delete_lf_tag)

Deletes the specified tag key name. If the attribute key does not exist or the tag does not exist, then the operation will not do anything. If the attribute key exists, then the operation checks if any resources are tagged with this attribute key, if yes, the API throws a 400 Exception with the message "Delete not allowed" as the tag key is still attached with resources. You can consider untagging resources with this tag key.

Request

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • TagKeyRequired: UTF-8 string, not less than 1 or more than 128 bytes long, matching the Custom string pattern #10.

    The key-name for the tag to delete.

Response

  • No Response parameters.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • AccessDeniedException

SearchTablesByLFTags Action (Python: search_tables_by_lf_tags)

This operation allows a search on TABLE resources by LFTags. This will be used by admins who want to grant user permissions on certain LFTags. Before making a grant, the admin can use SearchTablesByLFTags to find all resources where the given LFTags are valid to verify whether the returned resources can be shared.

Request

  • NextToken – UTF-8 string.

    A continuation token, if this is not the first call to retrieve this list.

  • MaxResults – Number (integer), not less than 1 or more than 1000.

    The maximum number of results to return.

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ExpressionRequired: An array of LFTag objects, not less than 1 or more than 5 structures.

    A list of conditions (LFTag structures) to search for in table resources.

Response

  • NextToken – UTF-8 string.

    A continuation token, present if the current list segment is not the last.

  • TableList – An array of TaggedTable objects.

    A list of tables that meet the tag conditions.

Errors

  • EntityNotFoundException

  • InternalServiceException

  • InvalidInputException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException

SearchDatabasesByLFTags Action (Python: search_databases_by_lf_tags)

This operation allows a search on DATABASE resources by TagCondition. This operation is used by admins who want to grant user permissions on certain TagConditions. Before making a grant, the admin can use SearchDatabasesByTags to find all resources where the given TagConditions are valid to verify whether the returned resources can be shared.

Request

  • NextToken – UTF-8 string.

    A continuation token, if this is not the first call to retrieve this list.

  • MaxResults – Number (integer), not less than 1 or more than 1000.

    The maximum number of results to return.

  • CatalogId – Catalog id string, not less than 1 or more than 255 bytes long, matching the Single-line string pattern.

    The identifier for the Data Catalog. By default, the account ID. The Data Catalog is the persistent metadata store. It contains database definitions, table definitions, and other control information to manage your AWS Lake Formation environment.

  • ExpressionRequired: An array of LFTag objects, not less than 1 or more than 5 structures.

    A list of conditions (LFTag structures) to search for in database resources.

Response

  • NextToken – UTF-8 string.

    A continuation token, present if the current list segment is not the last.

  • DatabaseList – An array of TaggedDatabase objects.

    A list of databases that meet the tag conditions.

Errors

  • EntityNotFoundException

  • InternalServiceException

  • InvalidInputException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException