Delen via

Naslaginformatie over REST API voor Azure AI Search

  • Artikel

Azure AI Search (voorheen bekend als Azure Cognitive Search) is een volledig beheerde cloudzoekservice die informatie biedt over inhoud die eigendom is van de gebruiker.

REST API's voor gegevensvlak worden gebruikt voor het indexeren en opvragen van werkstromen en worden beschreven in deze sectie.

Besturingsvlakbewerkingen voor servicebeheer worden behandeld in een afzonderlijke Management REST API-.

Api-documenten met versiebeheer

REST API-documenten zijn nu geversied. Wanneer u een API-referentiepagina opent, wordt boven de inhoudsopgave een versiekiezer weergegeven. Zorg ervoor dat de API-verwijzing afkomstig is uit de map Reference > Data Plane.

Schermopname van de versiekiezer.

Sleutelbegrippen

Azure AI Search heeft de concepten van zoekservices, indexen, documenten, indexeerfuncties, gegevensbronnen, vaardighedensetsen synoniemenkaarten.

  • Een zoekservice host indexen, indexeerfuncties, gegevensbronnen, vaardighedensets en synoniementoewijzingen als objecten op het hoogste niveau.
  • Een zoekindex biedt permanente opslag van zoekdocumenten. Zoekdocumenten zijn uw gegevens, geformuleerd als een verzameling velden, geladen uit externe bronnen en naar een index gepusht om deze doorzoekbaar te maken.
  • Een zoekindexeerfunctie voegt automatisering toe, leest gegevens in systeemeigen indelingen en serialiseert deze in JSON.
  • Een indexeerfunctie heeft een gegevensbron en verwijst naar een index.
  • Een indexeerfunctie kan ook een vaardighedenset hebben waarmee AI-verrijking en geïntegreerde vectorisatie aan de indexeringspijplijn worden toegevoegd. Vaardighedensets worden altijd gekoppeld aan een indexeerfunctie. Ze roepen machine learning aan om tekst te extraheren of te segmenteren, inhoud te vectoriseren, functies af te stellen of structuur toe te voegen aan inhoud voor verbeterde indexering door een zoekservice.

In totaal kunt u de volgende objecten in een zoekservice maken:

Objecten Beschrijving
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 partnerconnectors gebruiken. 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 komt overeen met 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 de URL-indeling altijd /indexes/[index name]/docs voor een bepaalde indexnaam bevatten.
Indexen Een index wordt opgeslagen in uw zoekservice en gevuld met JSON-documenten die zijn geïndexeerd en tokeniseerd voor het ophalen van gegevens. De verzameling velden van een index definieert de structuur van het zoekdocument. Velden hebben een naam, gegevenstypen en kenmerken die het gebruik bepalen. searchable velden worden bijvoorbeeld 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 vereist een indexeerfunctie ook een index. 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 gebruikt voor het toepassen van AI- of Deep Learning-modellen om inhoud te analyseren of te transformeren voor een betere doorzoekbaarheid in een index. De inhoud van een vaardighedenset is een of meer vaardigheden, die kunnen worden ingebouwde vaardigheden gemaakt door Microsoft, 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, segmentering van tekst in logische pagina's. Een vaardighedenset is een zelfstandig object op hoog niveau dat gelijk is aan indexen, indexeerfuncties en gegevensbronnen, maar het is alleen operationeel binnen de verwerking van de indexeerfunctie. Als object op hoog niveau kunt u een vaardighedenset één keer ontwerpen en vervolgens ernaar verwijzen in meerdere indexeerfuncties.
Synoniemenkaarten Een synoniementoewijzing is een serviceniveauobject dat door de gebruiker gedefinieerde synoniemen bevat. Dit object wordt onafhankelijk van zoekindexen onderhouden. Zodra het is geüpload, kunt u elk doorzoekbaar veld naar de synoniemenkaart (één per veld) laten wijzen.

Machtigingen en toegangsbeheer

U kunt verificatie op basis van sleutels of rollen gebruiken via Microsoft Entra-id.

  • verificatie op basis van sleutels is afhankelijk van API-sleutels die worden gegenereerd voor de zoekservice. Als u een geldige sleutel hebt, wordt er per aanvraag een vertrouwensrelatie tot stand brengt tussen de toepassing die de aanvraag verzendt en de service waarmee deze wordt verwerkt. U kunt een Admin 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 vereist dat u een bestaande tenant in Microsoft Entra-id hebt, met beveiligingsprinciplen en roltoewijzingen. Leden van de volgende rollen hebben toegang tot het gegevensvlak. U kunt aangepaste rollen maken als de ingebouwde rollen onvoldoende zijn.

    Rol Toegang
    Inzender voor zoekservice Toegang tot objecten, maar geen toegang tot indexinhoud. Met deze rol maakt u een zoekindex en andere objecten op het hoogste niveau, maar u kunt geen query's uitvoeren op een zoekindex of documenten toevoegen, verwijderen of bijwerken in een zoekindex. Deze rol is bedoeld voor ontwikkelaars die objectdefinities maken, bijwerken en verwijderen. Het is ook bedoeld voor beheerders die objecten moeten beheren, maar zonder de mogelijkheid om objectgegevens weer te geven of te openen.
    Inzender voor zoekgegevensindex Lees-schrijftoegang tot indexinhoud. Deze rol is bedoeld voor ontwikkelaars of indexeigenaren die de documentenverzameling van een index moeten importeren, vernieuwen of er query's op moeten uitvoeren.
    Zoekgegevensindexlezer Leestoegang tot indexinhoud. Deze rol is bedoeld voor apps en gebruikers die query's uitvoeren.

Wanneer u rollen gebruikt voor de verbinding, geeft uw client-app een bearer-token weer 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, is dit alleen van toepassing op bewerkingen in het gegevensvlak. Besturingsvlakbewerkingen, zoals servicebeheer, gebruiken altijd verificatie op basis van rollen. 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 voor 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-versiebevatten. De waarde moet worden ingesteld op een ondersteunde versie, opgemaakt zoals wordt weergegeven in dit voorbeeld: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01

  • aanvraagheaders moeten een API-sleutel of een Bearer-token voor geverifieerde verbindingen bevatten. U kunt eventueel de HTTP-header Accepteren instellen. Als de koptekst van het inhoudstype niet is ingesteld, wordt ervan uitgegaan dat de standaardwaarde wordt application/json.

Zie ook