Gegevens laden in een zoekindex in Azure AI Search

In dit artikel wordt uitgelegd hoe u documenten importeert in een vooraf gedefinieerde zoekindex met behulp van REST API's, Azure SDK's of Azure Portal.

Vereiste voorwaarden

• Een Azure AI Search-service (een willekeurige laag). Maak een service of zoek een bestaande service.

• Een bestaande zoekindex. In dit artikel wordt ervan uitgegaan dat u al een index hebt gemaakt. Als u in één stap moet maken en laden, gebruikt u de wizard Importeren of een indexeerfunctie.

• Machtigingen voor het laden van documenten:

  • Verificatie op basis van sleutels: een beheer-API-sleutel voor uw zoekservice.
  • Verificatie op basis van rollen: de rol Inzender voor zoekindexgegevens in de zoekservice.

• Installeer voor SDK-ontwikkeling de Azure Search-clientbibliotheek:

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

De Azure-portal gebruiken

Gebruik de wizard Importeren in Azure Portal om indexen in een naadloze werkstroom te maken en te laden. Als u een bestaande index wilt laden, kiest u een alternatieve benadering.

1. Ga naar uw zoekservice in Azure Portal.

2. Selecteer op de pagina Overzichtgegevens importeren op de opdrachtbalk om een zoekindex te maken en in te vullen.

   

   U kunt deze koppelingen volgen om de werkstroom te bekijken: Quickstart: Een Azure AI Search-index en quickstart: Geïntegreerde vectorisatie maken.

3. Nadat de wizard is voltooid, gebruikt u Search Explorer om te controleren op resultaten.

De REST API’s gebruiken

Documenten - Index is de REST API voor het importeren van gegevens in een zoekindex.

De hoofdtekst van de aanvraag bevat een of meer documenten die moeten worden geïndexeerd. Documenten worden uniek geïdentificeerd via een hoofdlettergevoelige sleutel. Elk document is gekoppeld aan een actie: 'uploaden', 'verwijderen', 'samenvoegen' of 'mergeOrUpload'. Uploadaanvragen moeten de documentgegevens bevatten als een set sleutel-waardeparen.

REST API's zijn handig voor het testen van het proof-of-concept, waar u indexeringswerkstromen kunt testen zonder veel code te hoeven schrijven. De @search.action parameter bepaalt of documenten volledig of gedeeltelijk worden toegevoegd in termen van nieuwe of vervangende waarden voor specifieke velden.

Quickstart: Zoeken in volledige tekst met REST legt de stappen uit. Het volgende voorbeeld is een gewijzigde versie van het voorbeeld. De waarde wordt ingekort voor kortheid en de eerste HotelId-waarde wordt gewijzigd om te voorkomen dat een bestaand document wordt overschreven.

1. Formuleer een POST-aanroep die de indexnaam, het eindpunt docs/index en een aanvraagbody bevat die de @search.action parameter bevat.

   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. Stel de @search.action parameter in om een document te upload maken of te overschrijven. Stel deze optie merge in op of uploadOrMerge als u gericht bent op updates voor specifieke velden in het document. In het vorige voorbeeld ziet u beide acties.

   Actie	Gevolg
   uploaden	Vergelijkbaar met een upsert waarin het document wordt ingevoegd als het nieuw is en bijgewerkt of vervangen als het bestaat. Als het document ontbrekende waarden bevat die de index vereist, wordt de waarde van het documentveld ingesteld op null.
   samenvoegen	Werkt een document bij dat al bestaat en geeft een foutmelding voor een document dat niet kan worden gevonden. Samenvoegen vervangt bestaande waarden. Zorg er daarom voor dat u controleert op verzamelingsvelden die meerdere waarden bevatten, zoals velden van het type Collection(Edm.String). Als een tags veld bijvoorbeeld begint met een waarde van ["budget"] en u een samenvoegbewerking ["economy", "pool"]uitvoert, is tagsde uiteindelijke waarde van het ["economy", "pool"] veld. Het is niet ["budget", "economy", "pool"].
   mergeOrUpload	Gedraagt zich als samenvoegen als het document bestaat en uploadt of het document nieuw is. Dit is de meest voorkomende actie voor incrementele updates.
   delete	Verwijderen verwijdert het opgegeven document uit de index. Elk veld dat u opgeeft in een verwijderbewerking, met uitzondering van het sleutelveld, wordt genegeerd. Als u een afzonderlijk veld uit een document wilt verwijderen, gebruikt u in plaats daarvan samenvoegen en stelt u het veld expliciet in op null. Zie Documenten verwijderen in een zoekindex voor meer informatie.

   Er zijn geen bestelgaranties waarvoor actie in de aanvraagbody eerst wordt uitgevoerd. Het is niet raadzaam om meerdere samenvoegacties te hebben die zijn gekoppeld aan hetzelfde document in één aanvraagbody. Als er meerdere "samenvoegacties" nodig zijn voor hetzelfde document, voer de samenvoegingen aan de clientzijde uit voordat u het document bijwerkt in de zoekindex.

   Als het document in primitieve verzamelingen een veld Tags van het type Collection(Edm.String) bevat met de waarde ["budget"], en u een samenvoeging uitvoert met de waarde ["economy", "pool"] voor Tag, is de uiteindelijke waarde van het veld Tags ["economy", "pool"]. Het is niet ["budget", "economie", "pool"].

   Als het document in complexe verzamelingen een complex verzamelingsveld bevat met de naam Ruimten met de waarde [{ "Type": "Budgetruimte", "BaseRate": 75.0 }] en u voert een samenvoeging uit met de waarde [{ "Type": "Standaardruimte" }, { "Type": "Budgetruimte", "BaseRate": 60,5 }], de uiteindelijke waarde van het veld Ruimten is [{ "Type": "Standaardruimte" }, { "Type": "BudgetRuimte", "BaseRate": 60,5 }]. Dit is geen van de volgende opties:

   • [{ "Type": "Budget room", "BaseRate": 75.0 }, { "Type": "Standaard kamer" }, { "Type": "Budget room", "BaseRate": 60.5 }] (toevoegelementen)

   • [{ "Type": "Standaardruimte", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60,5 }] (voeg elementen op volgorde samen en voeg eventuele extra's toe)

   Opmerking

   Wanneer u DateTimeOffset-waarden uploadt met tijdzonegegevens naar uw index, normaliseert Azure AI Search deze waarden naar UTC. Bijvoorbeeld: 2025-01-13T14:03:00-08:00 wordt opgeslagen als 2025-01-13T22:03:00Z. Als u tijdzonegegevens wilt opslaan, voegt u een extra kolom toe aan uw index.

3. Verzend de aanvraag.

   In de volgende tabel worden de verschillende statuscodes per document uitgelegd die in het antwoord kunnen worden geretourneerd. Sommige statuscodes geven problemen aan met de aanvraag zelf, terwijl andere tijdelijke foutvoorwaarden aangeven. De laatste moet u opnieuw proberen na een vertraging.

   Statuscode	Meaning	Opnieuw proberen	Opmerkingen
   200	Het document is met succes gewijzigd of verwijderd.	n.v.t.	Verwijderbewerkingen zijn idempotent. Zelfs als er geen documentsleutel in de index bestaat, resulteert een verwijderbewerking met die sleutel in een statuscode van 200.
   201	Het document is succesvol aangemaakt.	n.v.t.
   400	Er is een fout opgetreden in het document waardoor het niet kon worden geïndexeerd.	Nee.	Het foutbericht in het antwoord geeft aan wat er mis is met het document.
   404	Het document kan niet worden samengevoegd omdat de opgegeven sleutel niet in de index bestaat.	Nee.	Deze fout treedt niet op bij uploads, omdat ze nieuwe documenten maken, en niet bij verwijderingen omdat ze idempotent zijn.
   409	Er is een versieconflict gedetecteerd bij een poging om een document te indexeren.	Yes	Dit kan voorkomen wanneer u hetzelfde document meer dan één keer achter elkaar probeert te indexeren.
   422	De index is tijdelijk niet beschikbaar omdat deze is bijgewerkt met de vlag 'allowIndexDowntime' ingesteld op 'true'.	Yes
   429	Geeft aan dat u het quotum voor het aantal documenten per index hebt overschreden.	Nee.	U moet een nieuwe index maken of upgraden voor hogere capaciteitslimieten.
   503	Uw zoekservice is tijdelijk niet beschikbaar, mogelijk vanwege zware belasting.	Yes	In dit geval moet de code wachten voordat u het opnieuw probeert, anders riskeert u dat de service nog langer niet beschikbaar is.

   Opmerking

   Als uw clientcode vaak een 207-antwoord tegenkomt, is een mogelijke reden dat het systeem wordt belast. U kunt dit bevestigen door de statusCode eigenschap voor 503 te controleren. Als dit het geval is, raden we u aan om indexeringsaanvragen te beperken. Als het indexeringsverkeer niet afzakt, kan het systeem alle aanvragen met 503-error weigeren.

4. Zoek de documenten op die u zojuist hebt toegevoegd als validatiestap:

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

Verwijzing:Documenten - Index, Documenten - Ophalen

Een geslaagde indexaanvraag retourneert HTTP 200 (OK) voor een batch waarin alle documenten zijn geslaagd, of HTTP 207 (Multi-Status) als sommige documenten zijn mislukt. De hoofdtekst van het antwoord bevat de status voor elk document:

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

Wanneer de documentsleutel of -id nieuw is, wordt null de waarde voor een veld dat niet is opgegeven in het document. Voor acties in een bestaand document vervangen bijgewerkte waarden de vorige waarden. Velden die niet zijn opgegeven in een "merge" of "mergeUpload" worden intact gelaten in de zoekindex.

De Azure SDK's gebruiken

Programmeerbaarheid wordt geleverd in de volgende Azure SDK's.

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");

Controleer uw gegevensinvoer

Controleer na het laden van documenten of de gegevens correct zijn geïndexeerd.

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}");

Hoe gegevens importeren werkt

Een zoekservice accepteert JSON-documenten die voldoen aan het indexschema. Een zoekservice kan inhoud met tekst zonder opmaak en vectorinhoud importeren en indexeren in JSON-documenten.

• Inhoud zonder opmaak wordt opgehaald uit velden in de externe gegevensbron, uit metagegevenseigenschappen of van verrijkte inhoud die wordt gegenereerd door een vaardighedenset. Vaardigheden kunnen tekstbeschrijvingen extraheren of afleiden uit afbeeldingen en ongestructureerde inhoud.

• Vectorinhoud wordt opgehaald uit een gegevensbron die deze levert, of wordt gemaakt door een vaardighedenset die geïntegreerde vectorisatie implementeert in een Azure AI Search-indexeerworkload.

U kunt deze documenten zelf voorbereiden, maar als inhoud zich in een ondersteunde gegevensbron bevindt, kunt u een indexeerfunctie uitvoeren of met de wizard Importeren het ophalen van documenten, JSON-serialisatie en indexering automatiseren.

Zodra gegevens zijn geïndexeerd, worden de fysieke gegevensstructuren van de index vergrendeld. Zie Een index bijwerken en herbouwen voor hulp bij wat wel en niet kan worden gewijzigd.

Indexering is geen achtergrondproces. Een zoekservice balanceert indexerings- en queryworkloads, maar als de querylatentie te hoog is, kunt u capaciteit toevoegen of perioden met een lage queryactiviteit identificeren voor het laden van een index.

Zie Strategieën voor gegevensimport voor meer informatie.

Veelvoorkomende fouten oplossen