Partager via

Mettre à jour l’index (API REST Azure AI Search)

  • Article

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)

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 ».

Voir aussi