Ajouter, mettre à jour ou supprimer des documents (API REST Recherche Azure AI)
Vous pouvez importer des documents de recherche dans un index spécifié à l’aide de HTTP POST. Pour une mise à jour importante, le traitement par lots (jusqu’à 1 000 documents par lot, soit environ 16 Mo par lot) est recommandé et améliore considérablement les performances d’indexation.
POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Pour les sources de données Azure prises en charge, les indexeurs offrent une alternative plus simple pour l’ajout et la mise à jour de documents. Pour en savoir plus, consultez la section relative aux opérations de l’indexeur.
Paramètres URI
| Paramètre | Description |
|---|---|
| nom du service | Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche. |
| nom de l'index | Obligatoire sur l’URI, spécifiant l’index à publier des documents. Vous pouvez publier des documents uniquement dans un index à la fois. |
| api-version | Obligatoire. La version stable actuelle est api-version=2020-06-30. Pour plus d’informations, consultez Versions de l’API . |
En-têtes de requête
Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.
| Champs | Description |
|---|---|
| Content-Type | Obligatoire. À définir avec la valeur application/json |
| api-key | Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la demande auprès de votre service de recherche. Le chargement de documents nécessite une clé API d’administrateur. Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé . |
Corps de la demande
Le corps de la requête contient un ou plusieurs documents à indexer. Les documents sont identifiés par une clé unique respectant la casse. Chaque document est associé à une action : « charger », « supprimer », « fusionner » ou « mergeOrUpload ». Les demandes de téléchargement doivent inclure les données du document sous forme de paires clé/valeur.
{
"value": [
{
"@search.action": "upload (default) | merge | mergeOrUpload | delete",
"key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)
"field_name": field_value (key/value pairs matching index schema)
...
},
...
]
}
| Propriété | Description |
|---|---|
| @search.action | Obligatoire. Les valeurs valides sont « upload », « delete », « merge » ou « mergeOrUpload ». La valeur par défaut est « upload ». Vous pouvez combiner des actions, une par document, dans le même lot.
« charger » : une action de chargement est similaire à une « upsert » où le document sera inséré s’il est nouveau et mis à jour/remplacé s’il existe. Tous les champs sont remplacés dans le cas de mise à jour. « delete » : supprime le document spécifié de l’index. Tout champ que vous spécifiez dans une opération de suppression, autre que le champ de clé, sera ignoré. Si vous souhaitez supprimer un champ individuel d’un document, utilisez merge à la place et définissez le champ explicitement sur null.
« mergeOrUpload » : cette action se comporte comme une fusion si un document avec la clé donnée existe déjà dans l’index. Si le document n’existe pas, il se comporte comme un chargement avec un nouveau document. « merge » : la fusion met à jour un document existant avec les champs spécifiés. Si le document n’existe pas, la fusion échoue. N'importe quel champ que vous spécifiez dans une fusion remplace le champ existant dans le document. Cela s’applique également aux collections de types primitifs et complexes. Dans les collections primitives, si le document contient un champ Tags de type Collection (Edm.String) avec la valeur ["budget"] et que vous exécutez une fusion avec la valeur ["economy », « pool"] pour Tag, la valeur finale du champ Balises sera ["economy », « pool"]. et non [« budget », « économie », « pool »]. Dans les collections complexes, si le document contient un champ de collection complexe nommé Rooms avec la valeur [{ « Type » : « Budget Room », « BaseRate » : 75.0 }], et vous exécutez une fusion avec une valeur de [{ « Type » : « Standard Room » }, { « Type » : « Budget Room », « BaseRate » : 60.5 }], la valeur finale du champ Salles sera [{ « Type » : « Standard Room » }, { « Type » : « Budget Room », « BaseRate » : 60.5 }]. Il ne sera pas l’un des éléments suivants : [{ « Type » : « Budget Room », « BaseRate » : 75.0 }, { « Type » : « Standard Room » }, { « Type » : « Budget Room », « BaseRate » : 60.5 }] (append elements) [{ « Type » : « Standard Room », « BaseRate » : 75.0 }, { « Type » : « Budget Room », « BaseRate » : 60.5 }] (fusionner les éléments dans l’ordre, puis ajouter des extras) |
| key_field_name | Obligatoire. Définition de champ dans l’index qui sert de clé de document et contient uniquement des valeurs uniques. Les clés de document ne peuvent contenir que des lettres, des chiffres, des tirets ("-"), des traits de soulignement ("_") et des signes égaux ("=") et respectent la casse. Pour plus d’informations, consultez Règles de nommage. |
| Field_name | Obligatoire. Paires nom-valeur, où le nom du champ correspond à un nom de champ dans la définition d’index. La valeur est définie par l’utilisateur, mais doit être valide pour le type de champ. |
Notes
Il n’existe aucune garantie de classement pour laquelle l’action dans le corps de la requête est exécutée en premier. Il n’est pas recommandé d’avoir plusieurs actions de « fusion » associées au même document dans un seul corps de requête. Si plusieurs actions de fusion sont requises pour le même document, effectuez la fusion côté client avant de mettre à jour le document dans l’index de recherche.
response
Code d’état : 200 est retourné pour une réponse réussie, ce qui signifie que tous les éléments ont été stockés durablement et commencent à être indexés. L’indexation s’exécute en arrière-plan et rend de nouveaux documents disponibles (c’est-à-dire, interrogeables et interrogeables) quelques secondes après la fin de l’opération d’indexation. Le délai spécifique dépend de la charge sur le service.
L’indexation réussie est indiquée par la propriété status définie sur true pour tous les éléments, ainsi que par la propriété statusCode définie sur 201 (pour les documents récemment chargés) ou 200 (pour les documents fusionnés ou supprimés) :
{
"value": [
{
"key": "unique_key_of_new_document",
"status": true,
"errorMessage": null,
"statusCode": 201
},
{
"key": "unique_key_of_merged_document",
"status": true,
"errorMessage": null,
"statusCode": 200
},
{
"key": "unique_key_of_deleted_document",
"status": true,
"errorMessage": null,
"statusCode": 200
}
]
}
Code d’état : 207 est retourné quand au moins un élément n’a pas été correctement indexé. Les éléments qui n’ont pas été indexés ont la valeur false pour le champ status. Les propriétés errorMessage et statusCode indiquent la raison de l’erreur d’indexation :
{
"value": [
{
"key": "unique_key_of_document_1",
"status": false,
"errorMessage": "The search service is too busy to process this document. Please try again later.",
"statusCode": 503
},
{
"key": "unique_key_of_document_2",
"status": false,
"errorMessage": "Document not found.",
"statusCode": 404
},
{
"key": "unique_key_of_document_3",
"status": false,
"errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
"statusCode": 422
}
]
}
La propriété errorMessage indique si possible la raison de l’erreur d’indexation.
Le tableau suivant explique les différents codes status par document qui peuvent être retournés dans la réponse. Certains codes status indiquent des problèmes avec la requête elle-même, tandis que d’autres indiquent des conditions d’erreur temporaires. Dans ce dernier cas, il est recommandé de réessayer l’opération après un certain délai.
| Code d’état | Signification | Renouvelable | Remarques |
|---|---|---|---|
| 200 | Le document a été correctement modifié ou supprimé. | n/a | Les opérations de suppression sont idempotentes. Autrement dit, même si une clé de document n’existe pas dans l’index, la tentative d’opération de suppression avec cette clé aboutit à un code de 200 status. |
| 201 | Le document a été créé avec succès. | n/a | |
| 400 | Le document a rencontré une erreur qui a empêché son indexation. | No | Le message d’erreur dans la réponse indique ce qui ne va pas dans le document. |
| 404 | Impossible de fusionner le document, car la clé donnée n’existe pas dans l’index. | No | Cette erreur ne se produit pas pour les chargements, car ils créent de nouveaux documents, et il ne se produit pas pour les suppressions, car ils sont idempotents. |
| 409 | Un conflit de version a été détecté lors de la tentative d’indexation d’un document. | Yes | Cela peut se produire lorsque vous essayez d’indexer le même document plusieurs fois simultanément. |
| 422 | L’index est temporairement indisponible car il a été mis à jour avec l’indicateur « allowIndexDowntime » défini sur « true ». | Yes | |
| 503 | Votre service de recherche est temporairement indisponible, probablement en raison d’une charge importante. | Yes | Votre code doit attendre avant d’effectuer une nouvelle tentative, au risque de prolonger l’indisponibilité du service. |
Notes
Si votre code client génère fréquemment une réponse 207, une raison possible est que le système est chargé. Vous pouvez vous en assurer en vérifiant la propriété statusCode pour 503. Si c'est le cas, nous vous recommandons de limiter des demandes d'indexation. Sinon, si le trafic d'indexation ne diminue pas, le système peut commencer à rejeter toutes les requêtes avec des erreurs 503.
Code d'état : 429 indique que vous avez dépassé votre quota du nombre de documents par index. Vous devez créer un autre index ou effectuer une mise à niveau pour bénéficier de limites de capacité supérieures.
Exemples
Exemple : Charger deux documents entièrement définis
{
"value": [
{
"@search.action": "upload",
"HotelId": "1",
"HotelName": "Secret Point Motel",
"Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York.",
"Category": "Boutique",
"Tags": [ "pool", "air conditioning", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1970-01-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "677 5th Ave",
"City": "New York",
"StateProvince": "NY",
"PostalCode": "10022",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -73.975403, 40.760586 ]
},
"Rooms": [
{
"Description": "Budget Room, 1 Queen Bed (Cityside)",
"Description_fr": "Chambre Économique, 1 grand lit (côté ville)",
"Type": "Budget Room",
"BaseRate": 96.99,
"BedOptions": "1 Queen Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd" ]
},
{
"Description": "Budget Room, 1 King Bed (Mountain View)",
"Description_fr": "Chambre Économique, 1 très grand lit (Mountain View)",
"Type": "Budget Room",
"BaseRate": 80.99,
"BedOptions": "1 King Bed",
"SleepsCount": 2,
"SmokingAllowed": true,
"Tags": [ "vcr/dvd", "jacuzzi tub" ]
}
]
},
{
"@search.action": "upload",
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
"Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
"Category": "Boutique",
"Tags": [ "pool", "free wifi", "concierge" ],
"ParkingIncluded": false,
"LastRenovationDate": "1979-02-18T00:00:00Z",
"Rating": 3.60,
"Address": {
"StreetAddress": "140 University Town Center Dr",
"City": "Sarasota",
"StateProvince": "FL",
"PostalCode": "34243",
"Country": "USA"
},
"Location": {
"type": "Point",
"coordinates": [ -82.452843, 27.384417 ]
},
"Rooms": [
{
"Description": "Suite, 2 Double Beds (Mountain View)",
"Description_fr": "Suite, 2 lits doubles (vue sur la montagne)",
"Type": "Suite",
"BaseRate": 250.99,
"BedOptions": "2 Double Beds",
"SleepsCount": 2,
"SmokingAllowed": false,
"Tags": [ "Room Tags" ]
}
]
},
{
"@search.action": "merge",
"HotelId": "3",
"Rating": 2.39,
"Description": "Surprisingly expensive",
"LastRenovationDate": null
},
{
"@search.action": "delete",
"hotelId": "4"
}
]
}
Notes
Lorsque vous chargez DateTimeOffset des valeurs avec des informations de fuseau horaire dans votre index, Recherche Azure AI normalise ces valeurs au format UTC. Par exemple, 2019-01-13T14 :03 :00-08 :00 sera stocké sous la forme 2019-01-13T22 :03 :00Z. Si vous devez stocker des informations de fuseau horaire, vous devez ajouter une colonne supplémentaire à votre index.