Charger des données dans un index de recherche dans la Recherche Azure AI

Cet article explique comment importer des documents dans un index de recherche prédéfini à l’aide d’API REST, de kits de développement logiciel (SDK) Azure ou du portail Azure.

Prerequisites

• Un service de recherche d’intelligence artificielle Azure (quel que soit le niveau). Créez un service ou recherchez-en un existant.

• Index de recherche existant. Cet article part du principe que vous avez déjà créé un index. Si vous devez créer et charger en une seule étape, utilisez l’Assistant Importation ou un indexeur.

• Autorisations pour charger des documents :

  • Authentification basée sur des clés : clé API d’administration pour votre service de recherche.
  • Authentification basée sur les rôles : Recherchez le rôle Contributeur aux données d’indexation sur le service de recherche.

• Pour le développement SDK, installez la bibliothèque cliente Azure Search :

  • .NET : Azure.Search.Documents
  • Python : azure-search-documents
  • JavaScript : @azure/search-documents
  • Java : azure-search-documents

Utilisation du portail Azure

Dans le portail Azure, utilisez l’Assistant Importation pour créer et charger des index dans un flux de travail fluide. Si vous souhaitez charger un index existant, choisissez une autre approche.

1. Accédez à votre service Search dans le Portail Microsoft Azure.

2. Dans la page Vue d’ensemble , sélectionnez Importer des données dans la barre de commandes pour créer et remplir un index de recherche.

   

   Vous pouvez suivre ces liens pour passer en revue le flux de travail : Démarrage rapide : Créer un index Recherche Azure AI et Démarrage rapide : Vectorisation intégrée.

3. Une fois l’assistant terminé, utilisez Explorateur de recherche pour vérifier les résultats.

Utiliser les API REST

Documents – Index est l’API REST permettant d’importer des données dans un index de recherche.

Le corps de la requête contient un ou plusieurs documents à indexer. Les documents sont identifiés de manière unique par le biais dune clé sensible à la casse. Chaque document est associé à une action : « upload », « delete », « merge » ou « mergeOrUpload ». Les demandes de chargement doivent inclure les données de document sous la forme d’un ensemble de paires clé/valeur.

Les API REST sont utiles pour les tests de preuve de concept initiaux, où vous pouvez tester les workflows d’indexation sans avoir à écrire beaucoup de code. Le paramètre @search.action détermine si les documents sont ajoutés en totalité ou partiellement en termes de valeurs nouvelles ou de remplacement pour des champs spécifiques.

Démarrage rapide : Recherche en texte intégral à l’aide de REST explique les étapes. Ce qui suit est une version modifiée de l’exemple. La valeur est rognée pour la concision et la première valeur HotelId est modifiée pour éviter de remplacer un document existant.

1. Formulez un appel POST spécifiant le nom de l’index, le point de terminaison « docs/index » et un corps de demande qui comprend le paramètre @search.action.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2025-09-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Définissez le paramètre @search.action sur upload pour créer ou remplacer un document. Définissez-le sur merge ou uploadOrMerge si vous ciblez des mises à jour sur des champs spécifiques dans le document. L’exemple précédent montre les deux actions.

   Action	Effet
   téléverser	Similaire à un « upsert » où le document est inséré s’il est nouveau et mis à jour ou remplacé s’il existe. Si les valeurs requises par l’index sont manquantes dans le document, la valeur du champ du document est définie sur Null.
   fusion	Met à jour un document qui existe déjà et échoue un document introuvable. Merge remplace les valeurs existantes. Pour cette raison, veillez à rechercher les champs de collection qui contiennent plusieurs valeurs, telles que les champs de type Collection(Edm.String). Par exemple, si un champ tags commence par la valeur ["budget"] et que vous exécutez une fusion avec la valeur ["economy", "pool"] , la valeur finale du champ tagsest ["economy", "pool"]. Ce n’est pas ["budget", "economy", "pool"]le cas.
   FusionnerOuTéléverser	Se comporte comme fusion si le document existe et charge si le document est nouveau. Il s’agit de l’action la plus courante pour les mises à jour incrémentielles.
   delete	Supprimer supprime le document spécifié de l’index. Tout champ que vous spécifiez dans une opération de suppression, autre que le champ clé, est ignoré. Si vous souhaitez supprimer un champ individuel d'un document, utilisez plutôt une fusion en définissant explicitement la valeur du champ sur null. Pour plus d’informations, consultez Supprimer des documents dans un index de recherche.

   Il n’existe aucune garantie de classement quant à l’action dans le corps de la demande qui sera exécutée en premier. Il n’est pas recommandé d’avoir plusieurs actions de « fusion » associées au même document dans un corps de requête unique. S’il existe plusieurs actions de « fusion » requises pour le même document, effectuez la fusion côté client avant de mettre à jour le document dans l’index de recherche.

   Dans les collections primitives, si le document contient un champ Balises 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"]. Ce n’est pas « 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 la valeur [{ « 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 s'agira pas de l'une ou l'autre des opérations suivantes :

   • [{ « Type » : « Budget Room », « BaseRate » : 75.0 }, { « Type » : « Standard Room » }, { « Type » : « Budget Room », « BaseRate » : 60.5 }] (ajout d’éléments)

   • [{ « Type » : « Standard Room », « BaseRate » : 75.0 }, { « Type » : « Budget Room », « BaseRate » : 60.5 }] (fusionner des éléments dans l’ordre, puis ajouter des extras)

   Note

   Lorsque vous chargez des valeurs DateTimeOffset avec des informations de fuseau horaire dans votre index, Recherche Azure AI normalise ces valeurs au format UTC. Par exemple, 2025-01-13T14:03:00-08:00 sera stocké sous la forme 2025-01-13T22:03:00Z. Si vous devez stocker des informations de fuseau horaire, ajoutez une colonne supplémentaire à votre index.

3. Envoyez la demande.

   Le tableau suivant décrit les différents codes d’état par document qui peuvent être retournés dans la réponse. Certains codes d’état indiquent des problèmes au niveau de la requête proprement dite, 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 de statut	Meaning	Nouvelle tentative possible	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, toute tentative de suppression à l’aide de cette clé génère le code d’état 200.
   201	Le document a été créé avec succès.	n/a
   400	Le document a rencontré une erreur qui a empêché son indexation.	Non	Le message d’erreur dans la réponse indique le problème survenu au niveau du document.
   404	Le document n’a pas pu être fusionné, car la clé spécifiée n’existe pas dans l’index.	Non	Cette erreur ne s’applique pas aux téléchargements, dans la mesure où ils créent de nouveaux documents, de même qu’elle ne se produit pas pour les suppressions, car elles sont idempotentes.
   409	Un conflit de version a été détecté lors de la tentative d’indexation d’un document.	Oui	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 ».	Oui
   429	Indique que vous avez dépassé votre quota sur le nombre de documents par index.	Non	Vous devez soit créer un nouvel index, soit mettre à niveau un index existant pour augmenter les limites de capacité.
   503	Votre service de recherche est temporairement indisponible, probablement en raison d’une charge importante.	Oui	Votre code doit attendre avant d’effectuer une nouvelle tentative, au risque de prolonger l’indisponibilité du service.

   Note

   Si votre code client génère fréquemment une réponse 207, l’une des raisons possibles est que le système est soumis à une charge élevée. Vous pouvez le confirmer en vérifiant la statusCode propriété pour 503. Si c’est le cas, nous vous recommandons de limiter les 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.

4. En guise d’étape de validation, recherchez les documents que vous venez d’ajouter :

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2025-09-01
   

Référence :Documents - Index, Documents - Obtenir

Une requête d’index réussie retourne HTTP 200 (OK) pour un lot où tous les documents ont réussi ou HTTP 207 (état multiple) si certains documents ont échoué. Le corps de la réponse contient l’état de chaque document :

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Lorsque la clé de document ou l’ID est nouveau, null devient la valeur de tout champ qui n’est pas spécifié dans le document. Pour les actions sur un document existant, les valeurs mises à jour remplacent les valeurs précédentes. Tout champ non spécifié dans une opération « merge » ou « mergeUpload » est laissé intact dans l’index de recherche.

utiliser les kits SDK Azure ;

La programmabilité est fournie dans les Kits de développement logiciel (SDK) Azure suivants.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Vérifier le chargement de vos données

Après le chargement des documents, vérifiez que les données sont indexées correctement.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2025-09-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Fonctionnement de l’importation de données

Un service de recherche accepte les documents JSON qui sont conformes au schéma de l’index. Un service de recherche peut importer et indexer du contenu de texte brut et du contenu vectoriel dans des documents JSON.

• Le contenu en texte brut est récupéré à partir de champs de la source de données externe, des propriétés de métadonnées ou du contenu enrichi généré par un ensemble de compétences. Les compétences peuvent extraire ou déduire des descriptions textuelles à partir d’images et de contenu non structuré.

• Le contenu vectoriel est récupéré à partir d’une source de données qui le fournit, ou il est créé par un ensemble de compétences qui implémente la vectorisation intégrée dans une charge de travail d’indexeur Recherche Azure AI.

Vous pouvez préparer ces documents vous-même, mais si le contenu réside dans une source de données prise en charge, l’exécution d’un indexeur ou l’utilisation de l’Assistant Importation peut automatiser la récupération de documents, la sérialisation JSON et l’indexation.

Une fois les données indexées, les structures de données physiques de l’index sont verrouillées. Pour obtenir de l’aide sur ce qui peut et ne peut pas être modifié, consultez Mettre à jour et reconstruire un index.

L’indexation n’est pas un processus en arrière-plan. Un service de recherche équilibre l’indexation et les charges de travail de requête, mais si la latence de requête est trop élevée, vous pouvez ajouter de la capacité ou identifier des périodes d’activité de requête faible pour le chargement d’un index.

Pour plus d’informations, consultez Stratégies d’importation de données.

Résoudre les erreurs courantes