Delen via

Gegevens laden in een zoekindex in Azure AI Search

In dit artikel wordt uitgelegd hoe u documenten importeert in een vooraf gedefinieerde zoekindex. In Azure AI Search wordt eerst een zoekindex gemaakt met gegevensimport als tweede stap. De uitzondering hierop zijn de importwizards in de Azure portal en de indexeerpijplijnen, waarmee een index in de workflow wordt gemaakt en geladen.

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 behulp van een 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.

De Azure-portal gebruiken

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

  1. Meld u aan bij Azure Portal met uw Azure-account en zoek uw zoekservice.

  2. Selecteer op de pagina Overzichtgegevens importeren of Gegevens importeren (nieuw) op de opdrachtbalk om een zoekindex te maken en in te vullen.

    Schermopname van de opdracht Gegevens importeren.

    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.

Aanbeveling

Met de wizards importeren worden indexeerfuncties gemaakt en uitgevoerd. Als indexeerfuncties al zijn gedefinieerd, kunt u een indexeerfunctie opnieuw instellen en uitvoeren vanuit Azure Portal. Dit is handig als u velden incrementeel toevoegt. Opnieuw instellen zorgt ervoor dat de indexeerfunctie opnieuw wordt gestart, zodat alle velden uit alle brondocumenten worden opgehaald.

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-index/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.

    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

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.

De Azure SDK voor .NET biedt de volgende API's voor eenvoudige en bulksgewijs uploaden van documenten naar een index:

Er zijn verschillende voorbeelden die indexering illustreren in de context van eenvoudige en grootschalige indexering:

Zie ook

  • Last updated on