principal_mappings
Creates, updates, deletes, gets or lists a principal_mappings resource.
Overview
| Name | principal_mappings |
| Type | Resource |
| Id | aws.kendra.principal_mappings |
Fields
The following fields are returned by SELECT queries:
- describe_principal_mapping
| Name | Datatype | Description |
|---|---|---|
data_source_id | string | Shows the identifier of the data source to see information on the processing of PUT and DELETE actions for mapping users to their groups. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9_-]*</code>) |
group_id | string | Shows the identifier of the group to see information on the processing of PUT and DELETE actions for mapping users to their groups. (pattern: <code>^\P{C}*$</code>) |
group_ordering_id_summaries | array | Shows the following information on the processing of PUT and DELETE actions for mapping users to their groups: Status—the status can be either PROCESSING, SUCCEEDED, DELETING, DELETED, or FAILED. Last updated—the last date-time an action was updated. Received—the last date-time an action was received or submitted. Ordering ID—the latest action that should process and apply after other actions. Failure reason—the reason an action could not be processed. |
index_id | string | Shows the identifier of the index to see information on the processing of PUT and DELETE actions for mapping users to their groups. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9-]*</code>) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
describe_principal_mapping | select | region | Describes the processing of PUT and DELETE actions for mapping users to their groups. This includes information on the status of actions currently processing or yet to be processed, when actions were last updated, when actions were received by Amazon Kendra, the latest action that should process and apply after other actions, and useful error messages if an action could not be processed. DescribePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region. | |
put_principal_mapping | replace | region, IndexId, GroupId, GroupMembers | Maps users to their groups so that you only need to provide the user ID when you issue the query. You can also map sub groups to groups. For example, the group "Company Intellectual Property Teams" includes sub groups "Research" and "Engineering". These sub groups include their own list of users or people who work in these teams. Only users who work in research and engineering, and therefore belong in the intellectual property group, can see top-secret company documents in their search results. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. For more information, see Filtering on user context. If more than five PUT actions for a group are currently processing, a validation exception is thrown. | |
delete_principal_mapping | delete | region | Deletes a group so that all users that belong to the group can no longer access documents only available to that group. For example, after deleting the group "Summer Interns", all interns who belonged to that group no longer see intern-only documents in their search results. If you want to delete or replace users or sub groups of a group, you need to use the PutPrincipalMapping operation. For example, if a user in the group "Engineering" leaves the engineering team and another user takes their place, you provide an updated list of users or sub groups that belong to the "Engineering" group when calling PutPrincipalMapping. You can update your internal list of users or sub groups and input this list when calling PutPrincipalMapping. DeletePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
region | string | AWS region (default: us-east-1) |
SELECT examples
- describe_principal_mapping
Describes the processing of PUT and DELETE actions for mapping users to their groups. This includes information on the status of actions currently processing or yet to be processed, when actions were last updated, when actions were received by Amazon Kendra, the latest action that should process and apply after other actions, and useful error messages if an action could not be processed. DescribePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region.
SELECT
data_source_id,
group_id,
group_ordering_id_summaries,
index_id
FROM aws.kendra.principal_mappings
WHERE region = '{{ region }}' -- required
;
REPLACE examples
- put_principal_mapping
Maps users to their groups so that you only need to provide the user ID when you issue the query. You can also map sub groups to groups. For example, the group "Company Intellectual Property Teams" includes sub groups "Research" and "Engineering". These sub groups include their own list of users or people who work in these teams. Only users who work in research and engineering, and therefore belong in the intellectual property group, can see top-secret company documents in their search results. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents. For more information, see Filtering on user context. If more than five PUT actions for a group are currently processing, a validation exception is thrown.
REPLACE aws.kendra.principal_mappings
SET
IndexId = '{{ IndexId }}',
DataSourceId = '{{ DataSourceId }}',
GroupId = '{{ GroupId }}',
GroupMembers = '{{ GroupMembers }}',
OrderingId = {{ OrderingId }},
RoleArn = '{{ RoleArn }}'
WHERE
region = '{{ region }}' --required
AND IndexId = '{{ IndexId }}' --required
AND GroupId = '{{ GroupId }}' --required
AND GroupMembers = '{{ GroupMembers }}' --required;
DELETE examples
- delete_principal_mapping
Deletes a group so that all users that belong to the group can no longer access documents only available to that group. For example, after deleting the group "Summer Interns", all interns who belonged to that group no longer see intern-only documents in their search results. If you want to delete or replace users or sub groups of a group, you need to use the PutPrincipalMapping operation. For example, if a user in the group "Engineering" leaves the engineering team and another user takes their place, you provide an updated list of users or sub groups that belong to the "Engineering" group when calling PutPrincipalMapping. You can update your internal list of users or sub groups and input this list when calling PutPrincipalMapping. DeletePrincipalMapping is currently not supported in the Amazon Web Services GovCloud (US-West) region.
DELETE FROM aws.kendra.principal_mappings
WHERE region = '{{ region }}' --required
;