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 LF-tag.

Fields

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

    The key for the LF-tag.

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

    The value of the LF-tag.

LFTagKeyResource Structure

A structure containing an LF-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 LF-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 LF-tag conditions that apply to a resource's LF-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 LF-tag policy applies.

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

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

TaggedTable Structure

A structure describing a table resource with LF-tags.

Fields

  • Table – A TableResource object.

    A table that has LF-tags attached to it.

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

    A list of LF-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 LF-tags attached to the table.

  • LFTagsOnColumns – An array of ColumnLFTag objects.

    A list of LF-tags attached to columns in the table.

TaggedDatabase Structure

A structure describing a database resource with LF-tags.

Fields

  • Database – A DatabaseResource object.

    A database that has LF-tags attached to it.

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

    A list of LF-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 that do not have the LF-tag 'PII' in tables that have the LF-tag 'Prod'.

Fields

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

    The key-name for the LF-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 an LF-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 #9.

    The key-name for the LF-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 LF-tag.

  • Error – An ErrorDetail object.

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

ColumnLFTag Structure

A structure containing the name of a column resource and the LF-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 LF-tags attached to a column resource.

Operations

AddLFTagsToResource Action (Python: add_lf_tags_to_resource)

Attaches one or more LF-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 database, table, or column resource to which to attach an LF-tag.

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

    The LF-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 an LF-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 database, table, or column resource where you want to remove an LF-tag.

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

    The LF-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 LF-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 database, table, or column resource for which you want to return LF-tags.

  • ShowAssignedLFTags – Boolean.

    Indicates whether to show the assigned LF-tags.

Response

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

    A list of LF-tags applied to a database resource.

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

    A list of LF-tags applied to a table resource.

  • LFTagsOnColumns – An array of ColumnLFTag objects.

    A list of LF-tags applied to a column resource.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException

ListLFTags Action (Python: list_lf_tags)

Lists LF-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 LF-tags and shared LF-tags that the requester has permission to view. If resource share type is FOREIGN, returns all share LF-tags that the requester can view. If no resource share type is passed, lists LF-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 LF-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 an LF-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 #9.

    The key-name for the LF-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 an LF-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 #9.

    The key-name for the LF-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 #9.

    The key-name for the LF-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 LF-tag key. If the LF-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 LF-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 #9.

    The key-name for the LF-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 LF-tag values to delete from the LF-tag.

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

    A list of LF-tag values to add from the LF-tag.

Response

  • No Response parameters.

Errors

  • EntityNotFoundException

  • InvalidInputException

  • InternalServiceException

  • OperationTimeoutException

  • ConcurrentModificationException

  • AccessDeniedException

DeleteLFTag Action (Python: delete_lf_tag)

Deletes the specified LF-tag key name. If the attribute key does not exist or the LF-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 LF-tag key is still attached with resources. You can consider untagging resources with this LF-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 #9.

    The key-name for the LF-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 LF-tags. 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 LF-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 LF-tag conditions.

Errors

  • EntityNotFoundException

  • InternalServiceException

  • InvalidInputException

  • OperationTimeoutException

  • GlueEncryptionException

  • AccessDeniedException