Naslaginformatie over azure AI Search REST API
Azure AI Search (voorheen bekend als Azure Cognitive Search) is een volledig beheerde service voor zoeken in de cloud waarmee informatie wordt opgehaald via inhoud die eigendom is van de gebruiker.
REST API's voor gegevensvlakken worden gebruikt voor het indexeren en uitvoeren van querywerkstromen. Deze worden in deze sectie beschreven.
Besturingsvlakbewerkingen zijn toegankelijk via een afzonderlijke Management REST API.
Api-documenten met versiebeheer
REST API-documenten zijn nu geversied. Wanneer u een API-verwijzingspagina opent, wordt er een versiekiezer boven de inhoudsopgave weergegeven. Zorg ervoor dat de API-verwijzing afkomstig is uit de map Verwijzingsgegevensvlak>.
Belangrijkste concepten
Azure AI Search bevat de concepten van zoekservices, indexen, documenten, indexeerfuncties, gegevensbronnen, vaardighedensets en synoniemenkaarten.
- Een zoekservice host indexen, indexeerfuncties, gegevensbronnen, vaardighedensets en synoniementoewijzingen als objecten op het hoogste niveau.
- Een zoekindex biedt permanente opslag van zoekdocumenten. Search documenten zijn uw gegevens, geformuleerd als een verzameling velden, geladen uit externe bronnen en gepusht naar een index om ze doorzoekbaar te maken.
- Een zoekindexeerfunctie voegt automatisering toe, waarbij gegevens in systeemeigen indelingen worden gelezen en geserialiseerd in JSON.
- Een indexeerfunctie heeft een gegevensbron en verwijst naar een index.
- Een indexeerfunctie kan ook een vaardighedenset hebben die AI-verrijking en geïntegreerde vectorisatie toevoegt aan de indexeringspijplijn. Vaardighedensets zijn altijd gekoppeld aan een indexeerfunctie. Ze roepen machine learning aan om tekst te extraheren of te segmenteren, inhoud te vectoriseren, functies af te maken of structuur toe te voegen aan inhoud, zodat deze kan worden geïndexeerd door een zoekservice.
In totaal kunt u de volgende objecten maken in een zoekservice:
| Objecten | Description |
|---|---|
| Gegevensbronnen | Een gegevensbronverbinding die door een indexeerfunctie wordt gebruikt om documenten op te halen en te vernieuwen voor indexering. Gegevensbronnen hebben een type. U kunt de door Microsoft geleverde verbindingen voor Azure of connectors van derden gebruiken via partners. Zie Galerie met gegevensbronnen voor de volledige lijst. |
| Documenten | Conceptueel gezien is een document een entiteit in uw index. Dit concept toewijzen aan meer vertrouwde database-equivalenten: een zoekindex is gelijk aan een tabel en documenten zijn ongeveer gelijk aan rijen in een tabel. Documenten bestaan alleen in een index en worden alleen opgehaald via query's die gericht zijn op de verzameling documenten (/docs) van een index. Alle bewerkingen die worden uitgevoerd op de verzameling, zoals het uploaden, samenvoegen, verwijderen of opvragen van documenten, vinden plaats in de context van één index, zodat documentbewerkingen in url-indeling altijd voor een bepaalde indexnaam worden opgenomen /indexes/[index name]/docs . |
| Indexen | Een index wordt opgeslagen in uw zoekservice en gevuld met JSON-documenten die zijn geïndexeerd en tokenized voor het ophalen van informatie. De verzameling velden van een index bepaalt de structuur van het zoekdocument. Velden hebben een naam, gegevenstypen en kenmerken die bepalen hoe het wordt gebruikt. Velden worden bijvoorbeeld searchable gebruikt in zoekopdrachten in volledige tekst en dus tokenized tijdens het indexeren. Een index definieert ook andere constructies, zoals scoreprofielen voor het afstemmen van relevantie, suggesties, semantische configuraties en aangepaste analysefuncties. |
| Indexeerfuncties | Indexeerfuncties bieden automatisering van indexering. Een indexeerfunctie maakt verbinding met een gegevensbron, leest de gegevens in en geeft deze door aan een zoekmachine voor indexering in een doelzoekindex. Indexeerfuncties lezen uit een externe bron met behulp van verbindingsgegevens in een gegevensbron en serialiseren de binnenkomende gegevens in JSON-zoekdocumenten. Naast een gegevensbron is voor een indexeerfunctie ook een index vereist. De index geeft de velden en kenmerken van de zoekdocumenten op. |
| Vaardighedensets | Een vaardighedenset voegt externe verwerkingsstappen toe aan de uitvoering van de indexeerfunctie en wordt meestal gebruikt om AI- of Deep Learning-modellen toe te voegen om inhoud te analyseren of te transformeren, zodat deze doorzoekbaar is in een index. De inhoud van een vaardighedenset bestaat uit een of meer vaardigheden. Dit kunnen ingebouwde vaardigheden zijn die door Microsoft zijn gemaakt, aangepaste vaardigheden of een combinatie van beide. Er bestaan ingebouwde vaardigheden voor afbeeldingsanalyse, waaronder OCR, en verwerking van natuurlijke taal. Andere voorbeelden van ingebouwde vaardigheden zijn onder andere entiteitsherkenning, sleuteltermextractie, het indelen van tekst in logische pagina's. Een vaardighedenset is een zelfstandig object op hoog niveau dat bestaat op een niveau dat gelijk is aan indexen, indexeerfuncties en gegevensbronnen, maar het is alleen operationeel binnen de verwerking van indexeerfuncties. Als object op hoog niveau kunt u eenmaal een vaardighedenset ontwerpen en er vervolgens naar verwijzen in meerdere indexeerfuncties. |
| Synoniemenkaarten | Een synoniemtoewijzing is een object op serviceniveau dat door de gebruiker gedefinieerde synoniemen bevat. Dit object wordt onafhankelijk van zoekindexen onderhouden. Na het uploaden kunt u elk doorzoekbaar veld verwijzen naar de synoniemenkaart (één per veld). |
Machtigingen en toegangsbeheer
U kunt verificatie op basis van sleutels of op rollen gebaseerd via Microsoft Entra ID.
Verificatie op basis van sleutels is afhankelijk van API-sleutels die worden gegenereerd voor de zoekservice. Met een geldige sleutel stelt u per aanvraag een vertrouwensrelatie in tussen de toepassing die de aanvraag verzendt en de service die de aanvraag afhandelt. U kunt een Beheer API-sleutel gebruiken voor lees-schrijfbewerkingen of een Query-API-sleutel voor leestoegang tot de documentenverzameling van een zoekindex.
Microsoft Entra ID verificatie en op rollen gebaseerd toegangsbeheer is vereist dat u een bestaande tenant in Microsoft Entra ID hebt, met beveiligingsprincipals en roltoewijzingen. Leden van de volgende rollen hebben toegang tot het gegevensvlak. U kunt aangepaste rollen maken als de ingebouwde rollen onvoldoende zijn.
Rol Access Search-servicebijdrager Toegang tot objecten, maar geen toegang tot indexinhoud. Deze rol kan geen query's uitvoeren op een zoekindex of documenten toevoegen, verwijderen of bijwerken in een zoekindex. Deze rol is bedoeld voor beheerders die objecten moeten beheren, maar zonder de mogelijkheid om objectgegevens weer te geven of te openen. Search Inzender voor gegevensindexen Lees-schrijftoegang tot indexinhoud. Deze rol is bedoeld voor ontwikkelaars of indexeigenaren die de documentenverzameling van een index moeten importeren, vernieuwen of opvragen. Search Data Index Reader Leestoegang tot indexinhoud. Deze rol is voor apps en gebruikers die query's uitvoeren.
Wanneer u rollen gebruikt voor de verbinding, presenteert uw client-app een bearer-token in de autorisatieheader. Zie Toegang tot een zoek-app autoriseren met behulp van Microsoft Entra ID voor hulp bij het instellen hiervan.
U kunt verificatie op basis van sleutels of verificatie op basis van rollen uitschakelen. Als u verificatie op basis van rollen uitschakelt, hebben sommige ingebouwde rollen nog steeds toegang. Zie Microsoft Entra ID verificatie en op rollen gebaseerd toegangsbeheer voor Azure AI Search voor meer informatie.
De API's aanroepen
De API's die in deze sectie worden beschreven, bieden toegang tot bewerkingen op zoekgegevens, zoals het maken van indexen en populaties, het uploaden van documenten en query's. Houd bij het aanroepen van API's rekening met de volgende punten:
Aanvragen moeten worden uitgegeven via HTTPS (op de standaardpoort 443).
Aanvraag-URI's moeten de API-versie bevatten. De waarde moet worden ingesteld op een ondersteunde versie, opgemaakt zoals in dit voorbeeld:
GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30Aanvraagheaders moeten een API-sleutel of een Bearer-token bevatten voor geverifieerde verbindingen. U kunt desgewenst de HTTP-header Accepteren instellen. Als de header van het inhoudstype niet is ingesteld, wordt ervan uitgegaan dat de standaardwaarde is
application/json.