Mettre à jour l’index (API REST Azure AI Search)
La modification d’un index existant nécessite généralement une suppression et une reconstruction d’index, à l’exception des modifications de schéma suivantes :
Ajouter de nouveaux champs à une collection fields
Ajouter des champs nouvellement créés à un suggesteur
Ajouter ou modifier des profils de scoring
Ajouter ou modifier des clés de chiffrement
Ajouter de nouveaux analyseurs personnalisés
Modifier les options CORS
Modifiez les champs existants avec l’une de ces trois modifications :
- Modifier
retrievable
(les valeurs sont true ou false) - Modification
searchAnalyzer
(utilisée au moment de la requête) - Ajouter ou modifier
synonymMaps
(utilisé au moment de la requête)
- Modifier
Pour ajouter ces mises à jour, placez le nom de l’index sur l’URI de la demande. Dans le corps de la demande, incluez une définition d’index entièrement spécifiée avec vos modifications.
PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Les champs existants et la plupart des attributs de champ ne peuvent pas être supprimés ou modifiés, ni ajoutés aux suggesteurs. Seuls les champs nouvellement créés peuvent être ajoutés à un suggester
.
Lorsqu’un nouveau champ est ajouté, tous les documents existants obtiennent automatiquement une valeur null pour ce champ. Aucun autre espace de stockage n’est consommé jusqu’à ce que l’une des deux choses se produise : une valeur est fournie pour le nouveau champ (à l’aide de la fusion) ou de nouveaux documents sont ajoutés.
Les analyseurs, les générateurs de jetons, les filtres de jetons et les filtres char existants ne peuvent pas être modifiés. L’ajout de nouveaux index à un index déjà existant n’est possible que lorsque l’indicateur allowIndexDowntime
est activé dans la demande de mise à jour d’index. La même règle s’applique lors de l’ajout d’un champ vectoriel initial à un index préexistant qui a été établi à l’aide d’une API qui ne prenait pas en charge la recherche vectorielle, en particulier avant la version 2023-07-01 Preview de l’API REST.
PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true
Cette opération met votre index hors connexion pendant quelques secondes. L’indexation et les requêtes échouent lorsque l’index est hors connexion. Les performances et les opérations d’écriture peuvent être temporairement altérées pendant plusieurs minutes après la remise en ligne de l’index.
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. L’URI de requête spécifie le nom de l’index à mettre à jour. |
api-version | Obligatoire. Consultez Versions d’API pour obtenir la liste des versions prises en charge. |
allowIndexDowntime | facultatif. False par défaut. Définissez sur true pour certaines mises à jour, telles que l’ajout ou la modification d’un analyseur, d’un générateur de jetons, d’un filtre de jetons, d’un filtre char ou d’une propriété de similarité. L’index est mis hors connexion pendant la mise à jour, généralement pas plus de quelques secondes. |
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. Les demandes de mise à jour doivent inclure un api-key en-tête défini sur votre clé d’administration (par opposition à une clé de requête). Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé . |
Corps de la demande
La syntaxe du corps de la requête est la même que pour Créer un index.
Lorsque vous mettez à jour un index existant, le corps doit inclure la définition complète du schéma, y compris toutes les définitions d’origine que vous souhaitez conserver. En général, le meilleur modèle pour les mises à jour consiste à récupérer la définition d’index avec un GET, à la modifier, puis à la mettre à jour avec PUT.
response
Pour une demande réussie, le code d'état « 204 Pas de contenu » doit s'afficher.
Par défaut, le corps de la réponse est vide. Toutefois, si l’en-tête Prefer
de requête est défini sur return=representation
, le corps de la réponse contient le JSON de l’index mis à jour. Dans ce cas, la réussite status code est « 200 OK ».