AddDocuments Import documents - Tablestore - Centre de documentation Alibaba Cloud

Utilisez l'API AddDocuments pour importer des documents dans une base de connaissances. Le système analyse, découpe, vectorise et construit l'index automatiquement. Le téléchargement d'un même ossKey écrase le document original.

Prérequis

Vous avez créé une instance AgentStorage dont le statut est normal, et vous disposez du endpoint et du nom de l'instance.
Vous avez créé une API Key.
Avant l'importation, préparez un bucket OSS dans la même région et accordez-lui les droits de lecture. L'API AddDocuments prend en charge l'authentification par API Key. Si vous utilisez le SDK pour télécharger des fichiers locaux, vous devez également fournir un AccessKey RAM ou des identifiants temporaires pour accéder à OSS.

Paramètres de requête

Paramètre

Type

Description

knowledgeBaseName

string

Nom de la base de connaissances (obligatoire).

subspace

string

Nom du subspace (jusqu'à 128 octets UTF-8). Obligatoire si le subspace est activé.

documents

list<object>

Liste des documents (obligatoire). Maximum 10 par requête.

documents[].filePath

string

Utilisé uniquement par la méthode de téléchargement local upload_documents du SDK. Ce n'est pas un paramètre de requête HTTP AddDocuments. Téléchargez d'abord les fichiers locaux sur OSS, puis importez-les via ossKey.

documents[].ossKey

string

Chemin du fichier ou du répertoire OSS (longueur : 1–256 caractères). Obligatoire lors de l'appel à AddDocuments.

documents[].metadata

object

Métadonnées du document. Elles doivent être conformes au schéma de métadonnées défini par la base de connaissances.

documents[].inclusionFilters

list<string>

Filtres d'inclusion. Ils acceptent les caractères génériques en début et fin de chaîne (par exemple, .pdf) et servent à l'analyse des répertoires OSS.

documents[].exclusionFilters

list<string>

Filtres d'exclusion. Ils acceptent les caractères génériques en début et fin de chaîne (par exemple, draft*).

Exemples de requêtes

Pour l'authentification par API Key, transmettez le nom de l'instance et l'API Key via les en-têtes de requête x-ots-instancename et x-ots-apikey.

### Importer un seul fichier depuis OSS

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/manual.pdf",
      "metadata": {"author": "John Doe", "date": "2026-01-22 10:00:59", "score": 80}
    }
  ]
}'

### Importation par lot depuis un répertoire OSS

Le paramètre ossKey spécifie un chemin de répertoire (se terminant par /). Le système analyse récursivement tous les fichiers du répertoire et les filtre selon le modèle de nom de fichier grâce aux paramètres inclusionFilters et exclusionFilters.

curl -X POST https://<endpoint>/AddDocuments \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/",
      "inclusionFilters": ["*.pdf", "*.docx"],
      "exclusionFilters": ["*draft*"]
    }
  ]
}'

Réponse

Champ

Type

Description

documentDetails

list<object>

Résultat d'acceptation de chaque document. Un code HTTP 200 avec le code SUCCESS ne signifie pas que tous les documents ont été traités avec succès ; vous devez vérifier le statut de chaque élément. Le statut succeed indique uniquement que la tâche a été acceptée, pas que l'indexation est terminée. En cas d'échec, vérifiez le champ failureReason de l'élément concerné. Pour les documents acceptés avec succès, utilisez le docId renvoyé pour appeler GetDocument afin de consulter le statut (transmettez le même subspace si celui-ci est activé) et attendez le statut completed avant de récupérer les données. En cas de retour failed, traitez la raison de l'échec ; définissez un délai d'expiration global pour l'interrogation.

documentDetails[].docId

string

ID du document.

documentDetails[].ossKey

string

Chemin OSS du document.

documentDetails[].status

string

succeed ou failed

documentDetails[].failureReason

string

Raison de l'échec (uniquement en cas d'échec).

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65", "status": "succeed", "ossKey": "oss://example-bucket/docs/manual.pdf"}
    ]
  },
  "message": "succeed"
}