Index bijwerken (Azure AI Search REST API)

  • Artikel

Als u een bestaande index wilt wijzigen, moet u de index doorgaans verwijderen en opnieuw opbouwen, met uitzondering van de volgende schemawijzigingen:

  • Nieuwe velden toevoegen aan een verzameling velden

  • Nieuw gemaakte velden toevoegen aan een suggestiefunctie

  • Scoreprofielen toevoegen of wijzigen

  • Versleutelingssleutels toevoegen of wijzigen

  • Nieuwe aangepaste analysen toevoegen

  • CORS-opties wijzigen

  • Wijzig bestaande velden met een van deze drie wijzigingen:

    • Wijzigen retrievable (waarden zijn waar of onwaar)
    • Wijzigen searchAnalyzer (gebruikt tijdens de query)
    • Toevoegen of wijzigen synonymMaps (gebruikt tijdens query's)

Als u deze updates wilt toevoegen, plaatst u de indexnaam in de aanvraag-URI. Neem in de aanvraagtekst een volledig opgegeven indexdefinitie op met uw wijzigingen.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

Bestaande velden en de meeste veldkenmerken kunnen niet worden verwijderd of gewijzigd, en velden kunnen ook niet worden toegevoegd aan suggesties. Alleen nieuw gemaakte velden kunnen worden toegevoegd aan een suggester.

Wanneer een nieuw veld wordt toegevoegd, krijgen alle bestaande documenten automatisch een null-waarde voor dat veld. Er wordt geen andere opslagruimte gebruikt totdat een van de volgende twee dingen gebeurt: er wordt een waarde opgegeven voor het nieuwe veld (via samenvoeging) of er worden nieuwe documenten toegevoegd.

Bestaande analysen, tokenizers, tokenfilters en char-filters kunnen niet worden gewijzigd. Nieuwe toevoegen aan een bestaande index is alleen mogelijk wanneer de allowIndexDowntime vlag is ingeschakeld in de indexupdateaanvraag. Dezelfde regel is van toepassing wanneer u een beginvectorveld toevoegt aan een bestaande index die is gemaakt met behulp van een API die geen ondersteuning biedt voor vectorzoekopdrachten, met name vóór de REST API-versie 2023-07-01 Preview.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

Met deze bewerking wordt de index een paar seconden offline gehaald. Indexering en queryaanvragen mislukken terwijl de index offline is. Prestaties en schrijfbewerkingen kunnen gedurende enkele minuten tijdelijk worden beperkt nadat de index weer online is.

URI-parameters

Parameter Beschrijving
servicenaam Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice.
indexnaam Vereist. De aanvraag-URI geeft de naam op van de index die moet worden bijgewerkt.
api-versie Vereist. Zie API-versies voor een lijst met ondersteunde versies.
allowIndexDowntime Optioneel. Standaard onwaar. Stel in op true voor bepaalde updates, zoals het toevoegen of wijzigen van een analyzer, tokenizer, tokenfilter, tekenfilter of gelijkenis-eigenschap. De index wordt offline gehaald tijdens de update, meestal niet meer dan enkele seconden.

Aanvraagheaders

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Velden Description
Content-Type Vereist. Stel dit in op application/json
api-sleutel Optioneel als u Azure-rollen gebruikt en er een bearer-token wordt opgegeven voor de aanvraag, anders is een sleutel vereist. Bijwerkaanvragen moeten een api-key header bevatten die is ingesteld op uw beheerderssleutel (in plaats van een querysleutel). Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie.

Aanvraagbody

De syntaxis van de aanvraagtekst is hetzelfde als voor Index maken.

Wanneer u een bestaande index bijwerkt, moet de hoofdtekst de volledige schemadefinitie bevatten, inclusief eventuele oorspronkelijke definities die u wilt behouden. Over het algemeen is het beste patroon voor updates om de indexdefinitie op te halen met een GET, deze te wijzigen en vervolgens bij te werken met PUT.

Antwoord

Voor een geslaagde aanvraag ziet u '204 Geen inhoud'.

De antwoordtekst is standaard leeg. Als de Prefer aanvraagheader echter is ingesteld op return=representation, bevat de antwoordtekst de JSON van de bijgewerkte index. In dit geval is de statuscode '200 OK'.

Zie ook