Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Création d’un index
Vous pouvez créer un index à l'aide de la console ou en appelant l'[CreateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateIndex.html)API. Vous pouvez utiliser le AWS Command Line Interface (AWS CLI) ou le SDK avec l'API. Après avoir créé votre index, vous pouvez y ajouter des documents directement ou à partir d'une source de données.
Pour créer un index, vous devez fournir le nom de ressource Amazon (ARN) d'un rôle Gestion des identités et des accès AWS (IAM) auquel les index peuvent accéder CloudWatch. Pour plus d'informations, consultez la section [IAM Rôles pour les index.](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html#iam-roles-index)
Les onglets suivants fournissent une procédure pour créer un index à l'aide de AWS Management Console, ainsi que des exemples de code pour utiliser le AWS CLI, et Python et Java SDKs.
------
#### [ Console ]
**Pour créer un index**
1. Connectez-vous à la console AWS de gestion et ouvrez-la à l' Amazon Kendra adresse [https://console.aws.amazon.com/kendra/](https://console.aws.amazon.com/kendra/).
1. Sélectionnez **Créer un index** dans la section **Index.**
1. Dans **Spécifier les détails** de l'index, donnez un nom et une description à votre index.
1. Dans **IAM le rôle**, indiquez un IAM rôle. Pour trouver un rôle, choisissez parmi les rôles de votre compte contenant le mot « kendra » ou entrez le nom d'un autre rôle. Pour plus d'informations sur les autorisations requises par le rôle, consultez la section [IAM Rôles pour les index.](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html#iam-roles-index)
1. Choisissez **Suivant**.
1. Sur la page **Configurer le contrôle d'accès utilisateur**, choisissez **Next**. Vous pouvez mettre à jour votre index afin d'utiliser des jetons pour le contrôle d'accès après avoir créé un index. Pour plus d'informations, consultez la section [Contrôle de l'accès aux documents](https://docs.aws.amazon.com/kendra/latest/dg/create-index-access-control.html).
1. Sur la page des **détails du provisionnement**, choisissez **Create**.
1. La création de l'index peut prendre un certain temps. Consultez la liste des index pour suivre la progression de la création de votre index. Lorsque le statut de l'index est défini`ACTIVE`, votre index est prêt à être utilisé.
------
#### [ AWS CLI ]
**Pour créer un index**
1. Utilisez la commande suivante pour créer un index. `role-arn`Il doit s'agir du Amazon Resource Name (ARN) d'un IAM rôle capable d'exécuter Amazon Kendra des actions. Pour plus d'informations, consultez la section [IAM Rôles](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html).
La commande est formatée pour Linux et macOS. Si vous utilisez Windows, remplacez le caractère de continuation de ligne Unix (\$1) par un curseur (^).
```
aws kendra create-index \
--name index name \
--description "index description" \
--role-arn arn:aws:iam::account ID:role/role name
```
1. La création de l'index peut prendre un certain temps. Pour vérifier l'état de votre index, utilisez l'ID d'index renvoyé `create-index` par la commande suivante. Lorsque le statut de l'index est défini`ACTIVE`, votre index est prêt à être utilisé.
```
aws kendra describe-index \
--index-id index ID
```
------
#### [ Python ]
**Pour créer un index**
+ Fournissez des valeurs pour les variables suivantes dans l'exemple de code ci-dessous :
+ `description`: une description de l'index que vous êtes en train de créer. Ce nom est facultatif.
+ `index_name`: le nom de l'index que vous créez.
+ `role_arn`—Le nom de ressource Amazon (ARN) d'un rôle pouvant être exécuté Amazon Kendra APIs. Pour plus d'informations, consultez la section [IAM Rôles](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html).
```
import boto3
from botocore.exceptions import ClientError
import pprint
import time
kendra = boto3.client("kendra")
print("Create an index.")
# Provide a name for the index
index_name = "index-name"
# Provide an optional description for the index
description = "index description"
# Provide the IAM role ARN required for indexes
role_arn = "arn:aws:iam::${account id}:role/${role name}"
try:
index_response = kendra.create_index(
Name = index_name,
Description = description,
RoleArn = role_arn
)
pprint.pprint(index_response)
index_id = index_response["Id"]
print("Wait for Amazon Kendra to create the index.")
while True:
# Get the details of the index, such as the status
index_description = kendra.describe_index(
Id = index_id
)
# If status is not CREATING, then quit
status = index_description["Status"]
print(" Creating index. Status: "+status)
if status != "CREATING":
break
time.sleep(60)
except ClientError as e:
print("%s" % e)
print("Program ends.")
```
------
#### [ Java ]
**Pour créer un index**
+ Fournissez des valeurs pour les variables suivantes dans l'exemple de code ci-dessous :
+ `description`: une description de l'index que vous êtes en train de créer. Ce nom est facultatif.
+ `index_name`: le nom de l'index que vous créez.
+ `role_arn`—Le nom de ressource Amazon (ARN) d'un rôle pouvant être exécuté Amazon Kendra APIs. Pour plus d'informations, consultez la section [IAM Rôles](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html).
```
package com.amazonaws.kendra;
import java.util.concurrent.TimeUnit;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.CreateIndexRequest;
import software.amazon.awssdk.services.kendra.model.CreateIndexResponse;
import software.amazon.awssdk.services.kendra.model.DescribeIndexRequest;
import software.amazon.awssdk.services.kendra.model.DescribeIndexResponse;
import software.amazon.awssdk.services.kendra.model.IndexStatus;
public class CreateIndexExample {
public static void main(String[] args) throws InterruptedException {
String indexDescription = "Getting started index for Kendra";
String indexName = "java-getting-started-index";
String indexRoleArn = "arn:aws:iam:::role/KendraRoleForGettingStartedIndex";
System.out.println(String.format("Creating an index named %s", indexName));
CreateIndexRequest createIndexRequest = CreateIndexRequest
.builder()
.description(indexDescription)
.name(indexName)
.roleArn(indexRoleArn)
.build();
KendraClient kendra = KendraClient.builder().build();
CreateIndexResponse createIndexResponse = kendra.createIndex(createIndexRequest);
System.out.println(String.format("Index response %s", createIndexResponse));
String indexId = createIndexResponse.id();
System.out.println(String.format("Waiting until the index with ID %s is created.", indexId));
while (true) {
DescribeIndexRequest describeIndexRequest = DescribeIndexRequest.builder().id(indexId).build();
DescribeIndexResponse describeIndexResponse = kendra.describeIndex(describeIndexRequest);
IndexStatus status = describeIndexResponse.status();
if (status != IndexStatus.CREATING) {
break;
}
TimeUnit.SECONDS.sleep(60);
}
System.out.println("Index creation is complete.");
}
}
```
------
Après avoir créé votre index, vous y ajoutez des documents. Vous pouvez les ajouter directement ou créer une source de données qui met régulièrement à jour votre index.
**Topics**
+ [Ajouter des documents directement à un index avec téléchargement par lots](in-adding-documents.md)
+ [Ajouter des questions fréquemment posées (FAQs) à un index](in-creating-faq.md)
+ [Création de champs de document personnalisés](custom-attributes.md)
+ [Contrôle de l'accès des utilisateurs aux documents à l'aide de jetons](create-index-access-control.md)
# Ajouter des documents directement à un index avec téléchargement par lots
Vous pouvez ajouter des documents directement à un index à l'aide de l'[BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html)API. Vous ne pouvez pas ajouter de documents directement à l'aide de la console. Si vous utilisez la console, vous vous connectez à une source de données pour ajouter des documents à votre index. Les documents peuvent être ajoutés à partir d'un compartiment S3 ou fournis sous forme de données binaires. Pour une liste des types de documents pris en charge par la Amazon Kendra section [Types de documents](https://docs.aws.amazon.com/kendra/latest/dg/index-document-types.html).
L'ajout de documents à un index en utilisant `BatchPutDocument` est une opération asynchrone. Après avoir appelé l'`BatchPutDocument`API, vous l'[BatchGetDocumentStatus](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchGetDocumentStatus)utilisez pour suivre la progression de l'indexation de vos documents. Lorsque vous appelez l'`BatchGetDocumentStatus`API avec une liste de documents IDs, elle renvoie le statut du document. Lorsque le statut du document est `INDEXED` ou`FAILED`, le traitement du document est terminé. Lorsque le statut est défini`FAILED`, l'`BatchGetDocumentStatus`API renvoie la raison pour laquelle le document n'a pas pu être indexé.
Si vous souhaitez modifier le contenu et les champs ou attributs des métadonnées du document pendant le processus d'ingestion du document, consultez la section [Enrichissement Amazon Kendra personnalisé des documents](https://docs.aws.amazon.com/kendra/latest/dg/custom-document-enrichment.html). Si vous souhaitez utiliser une source de données personnalisée, chaque document que vous soumettez à l'aide de l'`BatchPutDocument`API nécessite un ID de source de données et un ID d'exécution sous forme d'attributs ou de champs. Pour plus d'informations, consultez la section [Attributs obligatoires pour les sources de données personnalisées](https://docs.aws.amazon.com/kendra/latest/dg/data-source-custom.html#custom-required-attributes).
**Note**
Chaque identifiant de document doit être unique par index. Vous ne pouvez pas créer de source de données pour indexer vos documents avec leur caractère unique, IDs puis utiliser l'`BatchPutDocument`API pour indexer les mêmes documents, ou vice versa. Vous pouvez supprimer une source de données, puis utiliser l'`BatchPutDocument`API pour indexer les mêmes documents, ou vice versa. L'utilisation du connecteur `BatchPutDocument` et `BatchDeleteDocument` APIs en combinaison avec un connecteur de source de Amazon Kendra données pour le même ensemble de documents peut entraîner des incohérences dans vos données. Nous vous recommandons plutôt d'utiliser le [connecteur de source de données Amazon Kendra personnalisé](https://docs.aws.amazon.com/kendra/latest/dg/data-source-custom.html).
Les documents suivants du guide du développeur montrent comment ajouter des documents directement à un index.
**Topics**
+ [Ajouter des documents à l'aide de l' BatchPutDocument API](#in-adding-binary-doc)
+ [Ajouter des documents à partir d'un compartiment S3](#in-adding-plain-text)
## Ajouter des documents à l'aide de l' BatchPutDocument API
L'exemple suivant ajoute un blob de texte à un index en appelant [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument). Vous pouvez utiliser l'`BatchPutDocument`API pour ajouter des documents directement à votre index. Pour une liste des types de documents pris en charge par la Amazon Kendra section [Types de documents](https://docs.aws.amazon.com/kendra/latest/dg/index-document-types.html).
Pour un exemple de création d'un index à l'aide du AWS CLI et SDKs, consultez la section [Création d'un index](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html). Pour configurer la CLI SDKs, reportez-vous à la section [Configuration Amazon Kendra](https://docs.aws.amazon.com/kendra/latest/dg/setup.html).
**Note**
Les fichiers ajoutés à l'index doivent se trouver dans un flux d'octets codé en UTF-8.
Dans les exemples suivants, du texte codé en UTF-8 est ajouté à l'index.
------
#### [ CLI ]
Dans le AWS Command Line Interface, utilisez la commande suivante. La commande est formatée pour Linux et macOS. Si vous utilisez Windows, remplacez le caractère de continuation de ligne Unix (\$1) par un curseur (^).
```
aws kendra batch-put-document \
--index-id index-id \
--documents '{"Id":"doc-id-1", "Blob":"Amazon.com is an online retailer.", "ContentType":"PLAIN_TEXT", "Title":"Information about Amazon.com"}'
```
------
#### [ Python ]
```
import boto3
kendra = boto3.client("kendra")
# Provide the index ID
index_id = "index-id"
# Provide the title and text
title = "Information about Amazon.com"
text = "Amazon.com is an online retailer."
document = {
"Id": "1",
"Blob": text,
"ContentType": "PLAIN_TEXT",
"Title": title
}
documents = [
document
]
result = kendra.batch_put_document(
IndexId = index_id,
Documents = documents
)
print(result)
```
------
#### [ Java ]
```
package com.amazonaws.kendra;
import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentRequest;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentResponse;
import software.amazon.awssdk.services.kendra.model.ContentType;
import software.amazon.awssdk.services.kendra.model.Document;
public class AddDocumentsViaAPIExample {
public static void main(String[] args) {
KendraClient kendra = KendraClient.builder().build();
String indexId = "yourIndexId";
Document testDoc = Document
.builder()
.title("The title of your document")
.id("a_doc_id")
.blob(SdkBytes.fromUtf8String("your text content"))
.contentType(ContentType.PLAIN_TEXT)
.build();
BatchPutDocumentRequest batchPutDocumentRequest = BatchPutDocumentRequest
.builder()
.indexId(indexId)
.documents(testDoc)
.build();
BatchPutDocumentResponse result = kendra.batchPutDocument(batchPutDocumentRequest);
System.out.println(String.format("BatchPutDocument Result: %s", result));
}
}
```
------
## Ajouter des documents à partir d'un compartiment S3
Vous pouvez ajouter des documents directement à votre index à partir d'un Amazon S3 bucket à l'aide de l'[BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument)API. Vous pouvez ajouter jusqu'à 10 documents au cours d'un même appel. Lorsque vous utilisez un compartiment S3, vous devez fournir un IAM rôle autorisé à accéder au compartiment contenant vos documents. Vous spécifiez le rôle dans le `RoleArn` paramètre.
L'utilisation de l'[BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument)API pour ajouter des documents à partir d'un Amazon S3 bucket ne s'effectue qu'une seule fois. Pour synchroniser un index avec le contenu d'un bucket, créez une source de Amazon S3 données. Pour plus d'informations, consultez la section [Source de Amazon S3 données](https://docs.aws.amazon.com/kendra/latest/dg/data-source-s3.html).
Pour un exemple de création d'un index à l'aide du AWS CLI et SDKs, consultez la section [Création d'un index](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html). Pour configurer la CLI SDKs, reportez-vous à la section [Configuration Amazon Kendra](https://docs.aws.amazon.com/kendra/latest/dg/setup.html). Pour plus d'informations sur la création d'un compartiment S3, consultez [Amazon Simple Storage Service la documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html).
Dans l'exemple suivant, deux documents Microsoft Word sont ajoutés à l'index à l'aide de l'`BatchPutDocument`API.
------
#### [ Python ]
```
import boto3
kendra = boto3.client("kendra")
# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${acccountID}:policy/${roleName}"
doc1_s3_file_data = {
"Bucket": "bucket-name",
"Key": "document1.docx"
}
doc1_document = {
"S3Path": doc1_s3_file_data,
"Title": "Document 1 title",
"Id": "doc_1"
}
doc2_s3_file_data = {
"Bucket": "bucket-name",
"Key": "document2.docx"
}
doc2_document = {
"S3Path": doc2_s3_file_data,
"Title": "Document 2 title",
"Id": "doc_2"
}
documents = [
doc1_document,
doc2_document
]
result = kendra.batch_put_document(
Documents = documents,
IndexId = index_id,
RoleArn = role_arn
)
print(result)
```
------
#### [ Java ]
```
package com.amazonaws.kendra;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentRequest;
import software.amazon.awssdk.services.kendra.model.BatchPutDocumentResponse;
import software.amazon.awssdk.services.kendra.model.Document;
import software.amazon.awssdk.services.kendra.model.S3Path;
public class AddFilesFromS3Example {
public static void main(String[] args) {
KendraClient kendra = KendraClient.builder().build();
String indexId = "yourIndexId";
String roleArn = "yourIndexRoleArn";
Document pollyDoc = Document
.builder()
.s3Path(
S3Path.builder()
.bucket("amzn-s3-demo-bucket")
.key("What is Amazon Polly.docx")
.build())
.title("What is Amazon Polly")
.id("polly_doc_1")
.build();
Document rekognitionDoc = Document
.builder()
.s3Path(
S3Path.builder()
.bucket("amzn-s3-demo-bucket")
.key("What is Amazon Rekognition.docx")
.build())
.title("What is Amazon rekognition")
.id("rekognition_doc_1")
.build();
BatchPutDocumentRequest batchPutDocumentRequest = BatchPutDocumentRequest
.builder()
.indexId(indexId)
.roleArn(roleArn)
.documents(pollyDoc, rekognitionDoc)
.build();
BatchPutDocumentResponse result = kendra.batchPutDocument(batchPutDocumentRequest);
System.out.println(String.format("BatchPutDocument result: %s", result));
}
}
```
------
# Ajouter des questions fréquemment posées (FAQs) à un index
**Note**
La prise en charge des fonctionnalités varie en fonction du type d'index et de l'API de recherche utilisés. Pour savoir si cette fonctionnalité est prise en charge pour le type d'index et l'API de recherche que vous utilisez, consultez la section [Types d'index](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html).
Vous pouvez ajouter des questions fréquemment posées (FAQs) directement à votre index à l'aide de la console ou de l'[CreateFaq](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateFaq.html)API. L'ajout FAQs à un index est une opération asynchrone. Vous placez les données de la FAQ dans un fichier que vous stockez dans un Amazon Simple Storage Service bucket. Vous pouvez utiliser des fichiers CSV ou JSON comme entrée pour votre FAQ :
+ CSV de base : fichier CSV dans lequel chaque ligne contient une question, une réponse et un URI source facultatif.
+ CSV personnalisé : fichier CSV contenant des questions, des réponses et des en-têtes personnalisés fields/attributes que vous pouvez utiliser pour facetter, afficher ou trier les réponses aux FAQ. Vous pouvez également définir des champs de contrôle d'accès pour limiter la réponse à la FAQ à certains utilisateurs et groupes autorisés à voir la réponse à la FAQ.
+ JSON : fichier JSON contenant des questions, des réponses et des informations personnalisées fields/attributes que vous pouvez utiliser pour facetter, afficher ou trier les réponses aux FAQ. Vous pouvez également définir des champs de contrôle d'accès pour limiter la réponse à la FAQ à certains utilisateurs et groupes autorisés à voir la réponse à la FAQ.
Par exemple, ce qui suit est un fichier CSV de base qui fournit des réponses aux questions sur les cliniques gratuites à Spokane, dans l'État de Washington, aux États-Unis, et à Mountain View, dans le Missouri, aux États-Unis.
```
How many free clinics are in Spokane WA?, 13
How many free clinics are there in Mountain View Missouri?, 7
```
**Note**
Le fichier de FAQ doit être codé en UTF-8.
**Topics**
+ [Création de champs d'index pour un fichier FAQ](#in-custom-fields-faq)
+ [Fichier CSV de base](#faq-basic-csv)
+ [Fichier CSV personnalisé](#faq-custom-csv)
+ [Fichier JSON](#faq-custom-json)
+ [Utilisation de votre fichier FAQ](#using-faq-file)
+ [Fichiers de FAQ dans des langues autres que l'anglais](#faq-languages)
## Création de champs d'index pour un fichier FAQ
**Note**
La prise en charge des fonctionnalités varie en fonction du type d'index et de l'API de recherche utilisés. Pour savoir si cette fonctionnalité est prise en charge pour le type d'index et l'API de recherche que vous utilisez, consultez la section [Types d'index](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html).
Lorsque vous utilisez un fichier [CSV ou [JSON](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html#faq-custom-json) personnalisé](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html#faq-custom-csv) pour la saisie, vous pouvez déclarer des champs personnalisés pour vos questions de FAQ. Par exemple, vous pouvez créer un champ personnalisé qui attribue à chaque question de FAQ un département commercial. Lorsque la FAQ est renvoyée dans une réponse, vous pouvez utiliser le département comme facette pour affiner la recherche uniquement à « RH » ou « Finance », par exemple.
Un champ personnalisé doit être mappé à un champ d'index. Dans la console, vous utilisez la page de **définition des facettes** pour créer un champ d'index. Lorsque vous utilisez l'API, vous devez d'abord créer un champ d'index à l'aide de l'[UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html)API.
Le field/attribute type du fichier FAQ doit correspondre au type du champ d'index associé. Par exemple, le champ « Département » est un champ `STRING_LIST` de type. Vous devez donc fournir des valeurs pour le champ du département sous forme de liste de chaînes dans votre fichier FAQ. Vous pouvez vérifier le type des champs d'index à l'aide de la page de **définition des facettes** de la console ou à l'aide de l'[DescribeIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_DescribeIndex.html)API.
Lorsque vous créez un champ d'index mappé à un attribut personnalisé, vous pouvez le marquer comme affichable, facetable ou triable. Vous ne pouvez pas rendre un attribut personnalisé consultable.
Outre les attributs personnalisés, vous pouvez également utiliser les champs Amazon Kendra réservés ou communs dans un fichier CSV ou JSON personnalisé. Pour plus d'informations, consultez la section [Attributs ou champs du document](https://docs.aws.amazon.com/kendra/latest/dg/hiw-document-attributes.html).
## Fichier CSV de base
Utilisez un fichier CSV de base lorsque vous souhaitez utiliser une structure simple pour votre FAQs. Dans un fichier CSV de base, chaque ligne comporte deux ou trois champs : une question, une réponse et un URI source facultatif qui pointe vers un document contenant plus d'informations.
Le contenu du fichier doit respecter le [format commun RFC 4180 et le type MIME pour les fichiers CSV (valeurs séparées par des virgules](https://tools.ietf.org/html/rfc4180)).
Ce qui suit est un fichier de FAQ au format CSV de base.
```
How many free clinics are in Spokane WA?, 13, https://s3.region.company.com/bucket-name/directory/faq.csv
How many free clinics are there in Mountain View Missouri?, 7, https://s3.region.company.com/bucket-name/directory/faq.csv
```
## Fichier CSV personnalisé
Utilisez un fichier CSV personnalisé lorsque vous souhaitez ajouter une touche personnalisée fields/attributes à vos questions de FAQ. Pour un fichier CSV personnalisé, vous utilisez une ligne d'en-tête dans votre fichier CSV pour définir les attributs supplémentaires.
Le fichier CSV doit contenir les deux champs obligatoires suivants :
+ `_question`—La question fréquemment posée
+ `_answer`—La réponse à la question fréquemment posée
Votre fichier CSV personnalisé peut contenir à la fois des champs Amazon Kendra réservés (sauf `_faq_id` `_data_source_id``_document_title`,, et`_file_type`) et des champs personnalisés.
Voici un exemple de fichier CSV personnalisé.
```
_question,_answer,_last_updated_at,custom_string
How many free clinics are in Spokane WA?, 13, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
How many free clinics are there in Mountain View Missouri?, 7, 2012-03-25T12:30:10+01:00, Note: Some free clinics require you to meet certain criteria in order to use their services
```
Le contenu du fichier personnalisé doit respecter le [format commun RFC 4180 et le type MIME pour les fichiers CSV (valeurs séparées par des virgules](https://tools.ietf.org/html/rfc4180)).
La liste suivante répertorie les types de champs personnalisés :
+ Date : valeurs de date et d'heure codées selon la norme ISO 8601.
Par exemple, 2012-03-25T12:30:10\$101:00 est le format de date et d’heure ISO 8601 pour le 25 mars 2012 à 12 h 30 (plus 10 secondes) dans le fuseau horaire de l’heure d’Europe centrale.
+ Long : nombres, tels que. `1234`
+ Chaîne : valeurs de chaîne. Si votre chaîne contient des virgules, placez la valeur entière entre guillemets doubles («) (par exemple,`"custom attribute, and more"`).
+ Liste de chaînes : liste de valeurs de chaîne. Répertoriez les valeurs dans une liste séparée par des virgules et placée entre guillemets («) (par exemple,`"item1, item2, item3"`). Si la liste ne contient qu'une seule entrée, vous pouvez omettre les guillemets (par exemple,`item1`).
Un fichier CSV personnalisé peut contenir des champs de contrôle d'accès utilisateur. Vous pouvez utiliser ces champs pour limiter l'accès à la FAQ à certains utilisateurs et groupes. Pour filtrer en fonction du contexte utilisateur, celui-ci doit fournir des informations sur l'utilisateur et le groupe dans la requête. Dans le cas contraire, tous les éléments pertinents FAQs sont renvoyés. Pour plus d'informations, consultez la section [Filtrage du contexte utilisateur](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html).
Vous trouverez ci-dessous la liste des filtres contextuels utilisateur pour FAQs :
+ `_acl_user_allow`—Les utilisateurs figurant dans la liste des autorisations peuvent consulter la FAQ dans la réponse à la requête. La FAQ n'est pas renvoyée aux autres utilisateurs.
+ `_acl_user_deny`—Les utilisateurs figurant dans la liste de refus ne peuvent pas voir la FAQ dans la réponse à la requête. La FAQ est renvoyée à tous les autres utilisateurs lorsqu'elle est pertinente par rapport à la requête.
+ `_acl_group_allow`—Les utilisateurs membres d'un groupe autorisé peuvent consulter la FAQ dans la réponse à la requête. La FAQ n'est pas renvoyée aux utilisateurs membres d'un autre groupe.
+ `_acl_group_deny`—Les utilisateurs membres d'un groupe refusé ne peuvent pas voir la FAQ dans la réponse à la requête. La FAQ est renvoyée aux autres groupes lorsqu'elle est pertinente par rapport à la requête.
Fournissez les valeurs des listes d'autorisation et de refus dans des listes séparées par des virgules et placées entre guillemets (par exemple,`"user1,user2,user3"`). Vous pouvez inclure un utilisateur ou un groupe dans une liste d'autorisation ou une liste de refus, mais pas dans les deux cas où le même utilisateur est autorisé individuellement mais également dans le cas d'un groupe refusé. Si vous incluez un utilisateur ou un groupe dans les deux, vous recevez un message d'erreur.
Voici un exemple de fichier CSV personnalisé contenant des informations contextuelles sur l'utilisateur.
```
_question, _answer, _acl_user_allow, _acl_user_deny, _acl_group_allow, _acl_group_deny
How many free clinics are in Spokane WA?, 13, "userID6201,userID7552", "userID1001,userID2020", groupBasicPlusRate, groupPremiumRate
```
## Fichier JSON
Vous pouvez utiliser un fichier JSON pour fournir des questions, des réponses et des champs pour votre index. Vous pouvez ajouter n'importe lequel des champs Amazon Kendra réservés ou des champs personnalisés à la FAQ.
Le schéma du fichier JSON est le suivant.
```
{
"SchemaVersion": 1,
"FaqDocuments": [
{
"Question": string,
"Answer": string,
"Attributes": {
string: object
additional attributes
},
"AccessControlList": [
{
"Name": string,
"Type": enum( "GROUP" | "USER" ),
"Access": enum( "ALLOW" | "DENY" )
},
additional user context
]
},
additional FAQ documents
]
}
```
L'exemple de fichier JSON suivant montre deux documents de FAQ. L'un des documents contient uniquement la question et la réponse requises. L'autre document inclut également des informations supplémentaires sur le champ et le contexte utilisateur ou le contrôle d'accès.
```
{
"SchemaVersion": 1,
"FaqDocuments": [
{
"Question": "How many free clinics are in Spokane WA?",
"Answer": "13"
},
{
"Question": "How many free clinics are there in Mountain View Missouri?",
"Answer": "7",
"Attributes": {
"_source_uri": "https://s3.region.company.com/bucket-name/directory/faq.csv",
"_category": "Charitable Clinics"
},
"AccessControlList": [
{
"Name": "user@amazon.com",
"Type": "USER",
"Access": "ALLOW"
},
{
"Name": "Admin",
"Type": "GROUP",
"Access": "ALLOW"
}
]
}
]
}
```
La liste suivante répertorie les types de champs personnalisés :
+ Date : valeur de chaîne JSON avec des valeurs de date et d'heure codées ISO 8601. Par exemple, 2012-03-25T12:30:10\$101:00 est le format de date et d’heure ISO 8601 pour le 25 mars 2012 à 12 h 30 (plus 10 secondes) dans le fuseau horaire de l’heure d’Europe centrale.
+ Long : valeur numérique JSON, telle que`1234`.
+ Chaîne : valeur de chaîne JSON (par exemple,`"custom attribute"`).
+ Liste de chaînes : tableau JSON de valeurs de chaîne (par exemple,`["item1,item2,item3"]`).
Un fichier JSON peut contenir des champs de contrôle d'accès utilisateur. Vous pouvez utiliser ces champs pour limiter l'accès à la FAQ à certains utilisateurs et groupes. Pour filtrer en fonction du contexte utilisateur, celui-ci doit fournir des informations sur l'utilisateur et le groupe dans la requête. Dans le cas contraire, tous les éléments pertinents FAQs sont renvoyés. Pour plus d'informations, consultez la section [Filtrage du contexte utilisateur](https://docs.aws.amazon.com/kendra/latest/dg/user-context-filter.html).
Vous pouvez inclure un utilisateur ou un groupe dans une liste d'autorisation ou une liste de refus, mais pas dans les deux cas où le même utilisateur est autorisé individuellement mais également dans le cas d'un groupe refusé. Si vous incluez un utilisateur ou un groupe dans les deux, vous recevez un message d'erreur.
Voici un exemple d'inclusion du contrôle d'accès utilisateur à une FAQ JSON.
```
"AccessControlList": [
{
"Name": "group or user name",
"Type": "GROUP | USER",
"Access": "ALLOW | DENY"
},
additional user context
]
```
## Utilisation de votre fichier FAQ
Après avoir enregistré le fichier d'entrée de votre FAQ dans un compartiment S3, vous utilisez la console ou l'`CreateFaq`API pour placer les questions et réponses dans votre index. Si vous souhaitez mettre à jour une FAQ, supprimez-la et créez-la à nouveau. Vous utilisez l'`DeleteFaq`API pour supprimer une FAQ.
Vous devez fournir un IAM rôle ayant accès au compartiment S3 qui contient vos fichiers source. Vous spécifiez le rôle dans la console ou dans le `RoleArn` paramètre. Voici un exemple d'ajout d'un fichier de FAQ à un index.
------
#### [ Python ]
```
import boto3
kendra = boto3.client("kendra")
# Provide the index ID
index_id = "index-id"
# Provide the IAM role ARN required to index documents in an S3 bucket
role_arn = "arn:aws:iam::${accountId}:role/${roleName}"
# Provide the S3 bucket path information to the FAQ file
faq_path = {
"Bucket": "bucket-name",
"Key": "FreeClinicsUSA.csv"
}
response = kendra.create_faq(
S3Path = faq_path,
Name = "FreeClinicsUSA",
IndexId = index_id,
RoleArn = role_arn
)
print(response)
```
------
#### [ Java ]
```
package com.amazonaws.kendra;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.CreateFaqRequest;
import software.amazon.awssdk.services.kendra.model.CreateFaqResponse;
import software.amazon.awssdk.services.kendra.model.S3Path;
public class AddFaqExample {
public static void main(String[] args) {
KendraClient kendra = KendraClient.builder().build();
String indexId = "yourIndexId";
String roleArn = "your role for accessing S3 files";
CreateFaqRequest createFaqRequest = CreateFaqRequest
.builder()
.indexId(indexId)
.name("FreeClinicsUSA")
.roleArn(roleArn)
.s3Path(
S3Path
.builder()
.bucket("amzn-s3-demo-bucket")
.key("FreeClinicsUSA.csv")
.build())
.build();
CreateFaqResponse response = kendra.createFaq(createFaqRequest);
System.out.println(String.format("The result of creating FAQ: %s", response));
}
}
```
------
## Fichiers de FAQ dans des langues autres que l'anglais
Vous pouvez indexer une FAQ dans une langue prise en charge. Amazon Kendra index FAQs en anglais par défaut si vous ne spécifiez aucune langue. Vous spécifiez le code de langue lorsque vous appelez l'[CreateFaq](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateFaq.html)opération ou vous pouvez inclure le code de langue d'une FAQ dans les métadonnées de la FAQ sous forme de champ. Si les métadonnées d'une FAQ ne contiennent pas de code de langue spécifié dans un champ de métadonnées, la FAQ est indexée à l'aide du code de langue spécifié lorsque vous appelez l'`CreateFAQ`opération. Pour indexer un document de FAQ dans une langue prise en charge dans la console, accédez à **FAQs**et sélectionnez **Ajouter une FAQ**. Vous choisissez une langue dans le menu déroulant **Langue.**
# Création de champs de document personnalisés
**Note**
La prise en charge des fonctionnalités varie en fonction du type d'index et de l'API de recherche utilisés. Pour savoir si cette fonctionnalité est prise en charge pour le type d'index et l'API de recherche que vous utilisez, consultez la section [Recherche d'index.](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index.html#index-searching)
Vous pouvez créer des attributs ou des champs personnalisés pour vos documents dans votre index Amazon Kendra. Par exemple, vous pouvez créer un champ ou un attribut personnalisé appelé « Département » avec les valeurs « RH », « Ventes » et « Fabrication ». Si vous associez ces champs ou attributs personnalisés à votre index Amazon Kendra, vous pouvez les utiliser pour filtrer les résultats de recherche afin d'inclure des documents en fonction de l'attribut « département RH », par exemple.
Avant de pouvoir utiliser un champ ou un attribut personnalisé, vous devez d'abord créer le champ dans l'index. Utilisez la console pour modifier les mappages de champs de source de données afin d'ajouter un champ personnalisé ou utilisez l'[UpdateIndex](https://docs.aws.amazon.com/kendra/latest/APIReference/API_UpdateIndex.html)API pour créer le champ d'index. Vous ne pouvez pas modifier le type de données du champ une fois que vous l'avez créé.
Pour la plupart des sources de données, vous mappez les champs de la source de données externe aux champs correspondants de Amazon Kendra. Pour plus d’informations, consultez [Mappage des champs de source de données](https://docs.aws.amazon.com/kendra/latest/dg/field-mapping.html). Pour les sources de données S3, vous pouvez créer des champs ou des attributs personnalisés à l'aide d'un fichier de métadonnées JSON.
Vous pouvez créer jusqu'à 500 champs ou attributs personnalisés.
Vous pouvez également utiliser des champs Amazon Kendra réservés ou communs. Pour plus d'informations, consultez la section [Attributs ou champs du document](https://docs.aws.amazon.com/kendra/latest/dg/hiw-document-attributes.html).
**Topics**
+ [Mise à jour des champs de document personnalisés](#update-attributes)
## Mise à jour des champs de document personnalisés
Avec l'`UpdateIndex`API, vous pouvez ajouter des champs ou des attributs personnalisés à l'aide du `DocumentMetadataConfigurationUpdates` paramètre.
L’exemple JSON suivant utilise `DocumentMetadataConfigurationUpdates` pour ajouter un champ appelé « Département » à l’index.
```
"DocumentmetadataConfigurationUpdates": [
{
"Name": "Department",
"Type": "STRING_VALUE"
}
]
```
Les sections suivantes incluent des exemples d'ajout d'attributs ou de champs personnalisés à l'aide de [BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html)et pour une source de données Amazon S3.
**Topics**
+ [Ajouter des attributs ou des champs personnalisés avec l' BatchPutDocument API](#custom-attributes-batch)
+ [Ajouter des attributs ou des champs personnalisés à une source Amazon S3 de données](#custom-attributes-s3)
### Ajouter des attributs ou des champs personnalisés avec l' BatchPutDocument API
Lorsque vous utilisez l'[BatchPutDocument](https://docs.aws.amazon.com/kendra/latest/APIReference/API_BatchPutDocument.html)API pour ajouter un document à votre index, vous spécifiez des champs ou des attributs personnalisés dans le cadre de`Attributes`. Vous pouvez ajouter plusieurs champs ou attributs lorsque vous appelez l'API. Vous pouvez créer jusqu'à 500 champs ou attributs personnalisés. L’exemple suivant présente un champ ou un attribut personnalisé qui ajoute « Département » à un document.
```
"Attributes":
{
"Department": "HR",
"_category": "Vacation policy"
}
```
### Ajouter des attributs ou des champs personnalisés à une source Amazon S3 de données
Lorsque vous utilisez un compartiment S3 comme source de données pour votre index, vous ajoutez des métadonnées aux documents avec des fichiers de métadonnées associés. Placez les fichiers JSON de métadonnées dans une structure de répertoire parallèle à celle de vos documents. Pour plus d’informations, consultez [Métadonnées du document S3](https://docs.aws.amazon.com/kendra/latest/dg/s3-metadata.html).
Spécifiez des champs ou des attributs personnalisés dans la structure JSON `Attributes`. Vous pouvez créer jusqu'à 500 champs ou attributs personnalisés. Par exemple, l'exemple suivant permet `Attributes` de définir trois champs ou attributs personnalisés et un champ réservé.
```
"Attributes": {
"brand": "Amazon Basics",
"price": 1595,
"_category": "sports",
"subcategories": ["outdoors", "electronics"]
}
```
Les étapes suivantes vous expliquent comment ajouter des attributs personnalisés à une source de données Amazon S3.
**Topics**
+ [Étape 1 : Création d'un index Amazon Kendra](#custom-attributes-s3-1)
+ [Étape 2 : Mettre à jour l'index pour ajouter des champs de document personnalisés](#custom-attributes-s3-2)
+ [Étape 3 : créer une source de données Amazon S3 et mapper les champs de la source de données à des attributs personnalisés](#custom-attributes-s3-3)
#### Étape 1 : Création d'un index Amazon Kendra
Suivez les étapes ci-dessous [Création d’un index](create-index.md) pour créer votre index Amazon Kendra.
#### Étape 2 : Mettre à jour l'index pour ajouter des champs de document personnalisés
Après avoir créé un index, vous y ajoutez des champs. La procédure suivante montre comment ajouter des champs à un index à l'aide de la console et de la CLI.
------
#### [ Console ]
**Pour créer des champs d'index**
1. Assurez-vous d'avoir [créé un index](https://docs.aws.amazon.com/kendra/latest/dg/create-index.html).
1. Ensuite, dans le menu de navigation de gauche, dans **Gestion des données**, choisissez **Définition des facettes**.
1. Dans **le guide des paramètres** des **champs d'index**, dans Champs d'index, choisissez **Ajouter un champ** pour ajouter des champs personnalisés.
1. Dans la boîte de dialogue **Ajouter un champ d'index**, procédez comme suit :
+ **Nom du champ** — Ajoutez un nom de champ.
+ **Type de données** : sélectionnez le type de données, qu'il s'agisse d'**une chaîne****, d'une liste** de chaînes ou d'une **date**.
+ **Types d'utilisation** **: sélectionnez les types d'utilisation, qu'ils soient **facetables**, **consultables, affichables** **ou triables**.**
Ensuite, sélectionnez **Ajouter**.
Répétez la dernière étape pour tous les autres champs que vous souhaitez mapper.
------
#### [ CLI ]
```
aws kendra update-index \
--region $region \
--endpoint-url $endpoint \
--application-id $applicationId \
--index-id $indexId \
--document-metadata-configuration-updates \
"[
{
"Name": "string",
"Type": "STRING_VALUE"|"STRING_LIST_VALUE"|"LONG_VALUE"|"DATE_VALUE",
"Relevance": {
"Freshness": true|false,
"Importance": integer,
"Duration": "string",
"RankOrder": "ASCENDING"|"DESCENDING",
"ValueImportanceMap": {"string": integer
...}
},
"Search": {
"Facetable": true|false,
"Searchable": true|false,
"Displayable": true|false,
"Sortable": true|false
}
}
...
]"
```
------
#### Étape 3 : créer une source de données Amazon S3 et mapper les champs de la source de données à des attributs personnalisés
Pour créer une source de données Amazon S3 et y associer des champs, suivez les instructions figurant dans[Amazon S3](data-source-s3.md).
Si vous utilisez l'API, utilisez l'`fieldMappings`attribut ci-dessous `configuration` lorsque vous utilisez l'[CreateDataSource](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateDataSource.html)API.
Pour une vue d'ensemble de la façon dont les champs de source de données sont mappés, voir[Mappage de champs de source de données](field-mapping.md).
# Contrôle de l'accès des utilisateurs aux documents à l'aide de jetons
**Note**
La prise en charge des fonctionnalités varie en fonction du type d'index et de l'API de recherche utilisés. Pour savoir si cette fonctionnalité est prise en charge pour le type d'index et l'API de recherche que vous utilisez, consultez la section [Types d'index](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html).
**Important**
Les indices Amazon Kendra GenAI Enterprise Edition ne prennent pas en charge le contrôle d'accès utilisateur basé sur des jetons.
Vous pouvez contrôler quels utilisateurs ou groupes peuvent accéder à certains documents de votre index ou voir certains documents dans leurs résultats de recherche. C'est ce que l'on appelle le filtrage du contexte utilisateur. Il s'agit d'une sorte de recherche personnalisée qui a l'avantage de contrôler l'accès aux documents. Par exemple, les équipes qui recherchent des informations sur le portail de l'entreprise ne doivent pas toutes accéder aux documents top secrets de l'entreprise, et ces documents ne sont pas pertinents pour tous les utilisateurs. Seuls des utilisateurs ou des groupes d'équipes spécifiques ayant accès à des documents top secrets devraient voir ces documents dans leurs résultats de recherche.
Amazon Kendra Les indices Enterprise et Developer prennent en charge le contrôle d'accès des utilisateurs basé sur des jetons à l'aide des types de jetons suivants :
+ Identifiant ouvert
+ JWT avec un secret partagé
+ JWT avec une clé publique
+ JSON
Amazon Kendra peut être utilisé pour fournir une recherche d'entreprise sécurisée pour vos applications de récupération et de recherche. Au cours de la requête et de la récupération, Amazon Kendra filtre les résultats de recherche en fonction de la demande `AttributeFilters` et `UserContext` des informations fournies dans celle-ci. Amazon Kendra lit les listes de contrôle d'accès aux documents (ACLs) collectées par ses connecteurs lors de l'exploration et de l'ingestion. Les résultats de récupération et de recherche renvoient URLs vers les référentiels de documents originaux et de courts extraits. L'accès au document complet est toujours imposé par le référentiel d'origine.
**Topics**
+ [Utilisation d'OpenID](create-index-access-control-tokens-openid.md)
+ [Utilisation d'un jeton Web JSON (JWT) avec un secret partagé](create-index-access-control-tokens-jwtshared.md)
+ [Utilisation d'un jeton Web JSON (JWT) avec une clé publique](create-index-access-control-tokens-jwtpublic.md)
+ [Utilisation de JSON](create-index-access-control-tokens-json.md)
# Utilisation d'OpenID
Pour configurer un Amazon Kendra index afin d'utiliser un jeton OpenID pour le contrôle d'accès, vous avez besoin de l'URL JWKS (JSON Web Key Set) du fournisseur OpenID. Dans la plupart des cas, l'URL JWKS est au format suivant (s'ils suivent la découverte d'OpenID). `https://domain-name/.well_known/jwks.json`
Les exemples suivants montrent comment utiliser un jeton OpenID pour le contrôle d'accès des utilisateurs lorsque vous créez un index.
------
#### [ Console ]
1. Choisissez **Create index** pour commencer à créer un nouvel index.
1. Sur la page **Spécifier les détails** de l'index, donnez un nom et une description à votre index.
1. Pour **IAM le rôle**, sélectionnez un rôle ou sélectionnez **Créer un nouveau rôle** pour et spécifiez un nom de rôle pour créer un nouveau rôle. Le rôle IAM aura le préfixe « AmazonKendra - ».
1. Conservez les valeurs par défaut de tous les autres champs. Choisissez **Suivant**.
1. Sur la page **Configurer le contrôle d'accès utilisateur**, sous **Paramètres de contrôle d'accès**, choisissez **Oui** pour utiliser des jetons pour le contrôle d'accès.
1. Sous **Configuration du jeton**, sélectionnez **OpenID comme type** de **jeton**.
1. Spécifiez une **URL de clé de signature**. L'URL doit pointer vers un ensemble de clés Web JSON.
1. *Facultatif* sous **Configuration avancée** :
1. Spécifiez un **nom d'utilisateur** à utiliser lors de la vérification de l'ACL.
1. Spécifiez un ou plusieurs **groupes** à utiliser lors de la vérification de l'ACL.
1. Spécifiez l'**émetteur** qui validera l'émetteur du jeton.
1. Spécifiez le (s) **identifiant (s) client (s)**. Vous devez spécifier une expression régulière correspondant à l'audience du JWT.
1. Sur la page des **détails du provisionnement**, choisissez **Developer Edition**.
1. Choisissez **Créer** pour créer votre index.
1. Attendez que votre index soit créé. Amazon Kendra fournit le matériel nécessaire à votre index. Cette opération peut prendre un certain temps.
------
#### [ CLI ]
Pour créer un index à l' AWS CLI aide d'un fichier d'entrée JSON, créez d'abord un fichier JSON avec les paramètres souhaités :
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"URL": "https://example.com/.well-known/jwks.json"
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
Vous pouvez remplacer les noms de champs d'utilisateur et de groupe par défaut. La valeur par défaut pour `UserNameAttributeField` est « user ». La valeur par défaut pour `GroupAttributeField` est « groups ».
Ensuite, appelez `create-index` en utilisant le fichier d'entrée. Par exemple, si le nom de votre fichier JSON est`create-index-openid.json`, vous pouvez utiliser ce qui suit :
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"URL": "https://example.com/.well-known/jwks.json"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# Utilisation d'un jeton Web JSON (JWT) avec un secret partagé
Les exemples suivants montrent comment utiliser le jeton Web JSON (JWT) avec un jeton secret partagé pour le contrôle d'accès des utilisateurs lorsque vous créez un index.
------
#### [ Console ]
1. Choisissez **Create index** pour commencer à créer un nouvel index.
1. Sur la page **Spécifier les détails** de l'index, donnez un nom et une description à votre index.
1. Pour **le rôle IAM**, sélectionnez un rôle ou sélectionnez **Créer un nouveau rôle** pour et spécifiez un nom de rôle pour créer un nouveau rôle. Le IAM rôle aura le préfixe « AmazonKendra - ».
1. Conservez les valeurs par défaut de tous les autres champs. Choisissez **Suivant**.
1. Sur la page **Configurer le contrôle d'accès utilisateur**, sous **Paramètres de contrôle d'accès**, choisissez **Oui** pour utiliser des jetons pour le contrôle d'accès.
1. Sous **Configuration du jeton**, sélectionnez **JWT avec secret partagé** comme **type de jeton**.
1. Sous **Paramètres de signature du secret partagé**, choisissez le **type de secret**. Vous pouvez utiliser un secret AWS Secrets Manager partagé existant ou en créer un nouveau.
Pour créer un nouveau secret partagé, choisissez **Nouveau**, puis procédez comme suit :
1. Sous **Nouveau AWS Secrets Manager secret**, spécifiez un **nom secret**. Le préfixe `AmazonKendra-` sera ajouté lorsque vous enregistrerez la clé publique.
1. Spécifiez un **ID de clé**. L'identifiant de clé est un indice qui indique quelle clé a été utilisée pour sécuriser la signature Web JSON du jeton.
1. Choisissez l'**algorithme** de signature pour le jeton. Il s'agit de l'algorithme cryptographique utilisé pour sécuriser le jeton d'identification. Pour plus d'informations sur la norme RSA, consultez [Chiffrement RSA](https://tools.ietf.org/html/rfc3447).
1. Spécifiez un **secret partagé** en saisissant un secret codé en URL base64. Vous pouvez également sélectionner **Générer un secret** pour qu'un secret soit généré pour vous. Vous devez vous assurer que le secret est un code secret codé en URL base64.
1. (*Facultatif*) Spécifiez à quel moment le secret partagé est valide. Vous pouvez spécifier la date et l'heure de validité d'un secret, ou les deux. Le secret sera valide dans l'intervalle spécifié.
1. Sélectionnez **Enregistrer le secret** pour enregistrer le nouveau secret.
1. (*Facultatif*) Sous **Configuration avancée** :
1. Spécifiez un **nom d'utilisateur** à utiliser lors de la vérification de l'ACL.
1. Spécifiez un ou plusieurs **groupes** à utiliser lors de la vérification de l'ACL.
1. Spécifiez l'**émetteur** qui validera l'émetteur du jeton.
1. Spécifiez le **ou les numéros de réclamation**. Vous devez spécifier une expression régulière correspondant à l'audience du JWT.
1. Sur la page des **détails du provisionnement**, choisissez **Developer Edition**.
1. Choisissez **Créer** pour créer votre index.
1. Attendez que votre index soit créé. Amazon Kendra fournit le matériel pour votre index. Cette opération peut prendre un certain temps.
------
#### [ CLI ]
Vous pouvez utiliser un jeton JWT avec un secret partagé à l'intérieur de AWS Secrets Manager. Le secret doit être un secret codé en URL base64. Vous avez besoin de l' Secrets Manager ARN, et votre Amazon Kendra rôle doit avoir accès `GetSecretValue` à la Secrets Manager ressource. Si vous chiffrez la Secrets Manager ressource avec AWS KMS, le rôle doit également avoir accès à l'action de déchiffrement.
Pour créer un index à l' AWS CLI aide d'un fichier d'entrée JSON, créez d'abord un fichier JSON avec les paramètres souhaités :
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "SECRET_MANAGER",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
Vous pouvez remplacer les noms de champs d'utilisateur et de groupe par défaut. La valeur par défaut pour `UserNameAttributeField` est « user ». La valeur par défaut pour `GroupAttributeField` est « groups ».
Ensuite, appelez `create-index` en utilisant le fichier d'entrée. Par exemple, si le nom de votre fichier JSON est`create-index-openid.json`, vous pouvez utiliser ce qui suit :
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
Le secret doit avoir le format suivant AWS Secrets Manager :
```
{
"keys": [
{
"kid": "key_id",
"alg": "HS256|HS384|HS512",
"kty": "OCT",
"use": "sig", //this value can be sig only for now
"k": "secret",
"nbf":"ISO1806 date format"
"exp":"ISO1806 date format"
}
]
}
```
Pour plus d'informations sur JWT, consultez [jwt.io](http://jwt.io).
------
#### [ Python ]
Vous pouvez utiliser un jeton JWT avec un secret partagé à l'intérieur de AWS Secrets Manager. Le secret doit être un secret codé en URL base64. Vous avez besoin de l' Secrets Manager ARN, et votre Amazon Kendra rôle doit avoir accès `GetSecretValue` à la Secrets Manager ressource. Si vous chiffrez la Secrets Manager ressource avec AWS KMS, le rôle doit également avoir accès à l'action de déchiffrement.
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# Utilisation d'un jeton Web JSON (JWT) avec une clé publique
Les exemples suivants montrent comment utiliser le jeton Web JSON (JWT) avec une clé publique pour le contrôle d'accès des utilisateurs lorsque vous créez un index. Pour plus d'informations sur JWT, consultez [jwt.io](http://jwt.io).
------
#### [ Console ]
1. Choisissez **Create index** pour commencer à créer un nouvel index.
1. Sur la page **Spécifier les détails** de l'index, donnez un nom et une description à votre index.
1. Pour **le rôle IAM**, sélectionnez un rôle ou sélectionnez **Créer un nouveau rôle** pour et spécifiez un nom de rôle pour créer un nouveau rôle. Le IAM rôle aura le préfixe « AmazonKendra - ».
1. Conservez les valeurs par défaut de tous les autres champs. Choisissez **Suivant**.
1. Sur la page **Configurer le contrôle d'accès utilisateur**, sous **Paramètres de contrôle d'accès**, choisissez **Oui** pour utiliser des jetons pour le contrôle d'accès.
1. Sous **Configuration du jeton**, sélectionnez **JWT avec clé publique** comme **type de jeton**.
1. Sous **Paramètres de signature de la clé publique**, choisissez le **type de secret**. Vous pouvez utiliser un AWS Secrets Manager secret existant ou en créer un nouveau.
Pour créer un nouveau secret, choisissez **Nouveau**, puis procédez comme suit :
1. Sous **Nouveau AWS Secrets Manager secret**, spécifiez un **nom secret**. Le préfixe `AmazonKendra-` sera ajouté lorsque vous enregistrerez la clé publique.
1. Spécifiez un **ID de clé**. L'identifiant de clé est un indice qui indique quelle clé a été utilisée pour sécuriser la signature Web JSON du jeton.
1. Choisissez l'**algorithme** de signature pour le jeton. Il s'agit de l'algorithme cryptographique utilisé pour sécuriser le jeton d'identification. Pour plus d'informations sur la norme RSA, consultez [Chiffrement RSA](https://tools.ietf.org/html/rfc3447).
1. Sous **Attributs de certificat**, spécifiez une **chaîne de certificats** *facultative*. La chaîne de certificats est composée d'une liste de certificats. Il commence par le certificat d'un serveur et se termine par le certificat racine.
1. *Facultatif* Spécifiez l'**empreinte numérique ou l'empreinte digitale**. Il doit s'agir du hachage d'un certificat, calculé sur toutes les données du certificat et sur sa signature.
1. Spécifiez l'**exposant.** Il s'agit de la valeur de l'exposant pour la clé publique RSA. Elle est représentée sous la forme d'une valeur codée en base64URLUInt.
1. Spécifiez le **module.** Il s'agit de la valeur de l'exposant pour la clé publique RSA. Elle est représentée sous la forme d'une valeur codée en base64URLUInt.
1. Sélectionnez **Enregistrer la clé** pour enregistrer la nouvelle clé.
1. *Facultatif* sous **Configuration avancée** :
1. Spécifiez un **nom d'utilisateur** à utiliser lors de la vérification de l'ACL.
1. Spécifiez un ou plusieurs **groupes** à utiliser lors de la vérification de l'ACL.
1. Spécifiez l'**émetteur** qui validera l'émetteur du jeton.
1. Spécifiez le (s) **identifiant (s) client (s)**. Vous devez spécifier une expression régulière correspondant à l'audience du JWT.
1. Sur la page des **détails du provisionnement**, choisissez **Developer Edition**.
1. Choisissez **Créer** pour créer votre index.
1. Attendez que votre index soit créé. Amazon Kendra fournit le matériel nécessaire à votre index. Cette opération peut prendre un certain temps.
------
#### [ CLI ]
Vous pouvez utiliser JWT avec une clé publique à l'intérieur d'un AWS Secrets Manager. Vous avez besoin de l' Secrets Manager ARN, et votre Amazon Kendra rôle doit avoir accès `GetSecretValue` à la Secrets Manager ressource. Si vous chiffrez la Secrets Manager ressource avec AWS KMS, le rôle doit également avoir accès à l'action de déchiffrement.
Pour créer un index à l' AWS CLI aide d'un fichier d'entrée JSON, créez d'abord un fichier JSON avec les paramètres souhaités :
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account id:role:/my-role",
"UserTokenConfigurationList": [
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "SECRET_MANAGER",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret
}
}
], "UserContextPolicy": "USER_TOKEN"
}
```
Vous pouvez remplacer les noms de champs d'utilisateur et de groupe par défaut. La valeur par défaut pour `UserNameAttributeField` est « user ». La valeur par défaut pour `GroupAttributeField` est « groups ».
Ensuite, appelez `create-index` en utilisant le fichier d'entrée. Par exemple, si le nom de votre fichier JSON est`create-index-openid.json`, vous pouvez utiliser ce qui suit :
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
Le secret doit avoir le format suivant Secrets Manager :
```
{
"keys": [
{
"alg": "RS256|RS384|RS512",
"kty": "RSA", //this can be RSA only for now
"use": "sig", //this value can be sig only for now
"n": "modulus of standard pem",
"e": "exponent of standard pem",
"kid": "key_id",
"x5t": "certificate thumprint for x.509 cert",
"x5c": [
"certificate chain"
]
}
]
}
```
Pour plus d'informations sur JWT, consultez [jwt.io](http://jwt.io).
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account id:role:/my-role',
UserTokenConfigurationList=[
{
"JwtTokenTypeConfiguration": {
"KeyLocation": "URL",
"Issuer": "optional: specify the issuer url",
"ClaimRegex": "optional: regex to validate claims in the token",
"UserNameAttributeField": "optional: user",
"GroupAttributeField": "optional: group",
"SecretManagerArn": "arn:aws:secretsmanager:us-west-2:account id:secret:/my-user-context-secret"
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------
# Utilisation de JSON
Les exemples suivants montrent comment utiliser le JSON pour le contrôle d'accès des utilisateurs lorsque vous créez un index.
**Avertissement**
Le jeton JSON est une charge utile non validée. Cela ne doit être utilisé que lorsque les demandes Amazon Kendra proviennent d'un serveur fiable et jamais d'un navigateur.
------
#### [ Console ]
1. Choisissez **Create index** pour commencer à créer un nouvel index.
1. Sur la page **Spécifier les détails** de l'index, donnez un nom et une description à votre index.
1. Pour **IAM le rôle**, sélectionnez un rôle ou sélectionnez **Créer un nouveau rôle** pour et spécifiez un nom de rôle pour créer un nouveau rôle. Le IAM rôle aura le préfixe « AmazonKendra - ».
1. Conservez les valeurs par défaut de tous les autres champs. Choisissez **Suivant**.
1. Sur la page **Configurer le contrôle d'accès utilisateur**, sous **Paramètres de contrôle d'accès**, choisissez **Oui** pour utiliser des jetons pour le contrôle d'accès.
1. Sous **Configuration du jeton**, sélectionnez **JSON** comme **type de jeton**.
1. Spécifiez un **nom d'utilisateur** à utiliser lors de la vérification de l'ACL.
1. Spécifiez un ou plusieurs **groupes** à utiliser lors de la vérification de l'ACL.
1. Choisissez **Suivant**.
1. Sur la page des **détails du provisionnement**, choisissez **Developer Edition**.
1. Choisissez **Créer** pour créer votre index.
1. Attendez que votre index soit créé. Amazon Kendra fournit le matériel nécessaire à votre index. Cette opération peut prendre un certain temps.
------
#### [ CLI ]
Pour créer un index à l' AWS CLI aide d'un fichier d'entrée JSON, créez d'abord un fichier JSON avec les paramètres souhaités :
```
{
"Name": "user-context",
"Edition": "ENTERPRISE_EDITION",
"RoleArn": "arn:aws:iam::account-id:role:/my-role",
"UserTokenConfigurations": [
{
"JsonTokenTypeConfiguration": {
"UserNameAttributeField": "user",
"GroupAttributeField": "group"
}
}
],
"UserContextPolicy": "USER_TOKEN"
}
```
Ensuite, appelez `create-index` en utilisant le fichier d'entrée. Par exemple, si le nom de votre fichier JSON est`create-index-openid.json`, vous pouvez utiliser ce qui suit :
```
aws kendra create-index --cli-input-json file://create-index-openid.json
```
Si vous n'utilisez pas Open ID pour AWS IAM Identity Center, vous pouvez nous envoyer le jeton au format JSON. Dans ce cas, vous devez spécifier quel champ du jeton JSON contient le nom d'utilisateur et quel champ contient les groupes. Les valeurs des champs de groupe doivent être un tableau de chaînes JSON. Par exemple, si vous utilisez le protocole SAML, votre jeton sera similaire au suivant :
```
{
"username" : "user1",
"groups": [
"group1",
"group2"
]
}
```
Cela `TokenConfiguration` indiquerait le nom d'utilisateur et les noms des champs de groupe :
```
{
"UserNameAttributeField":"username",
"GroupAttributeField":"groups"
}
```
------
#### [ Python ]
```
response = kendra.create_index(
Name='user-context',
Edition='ENTERPRISE_EDITION',
RoleArn='arn:aws:iam::account-id:role:/my-role',
UserTokenConfigurations=[
{
"JwtTokenTypeConfiguration": {
"UserNameAttributeField": "user",
"GroupAttributeField": "group",
}
}
],
UserContextPolicy='USER_TOKEN'
)
```
------