Rest API-referens för Azure AI Search

  • Artikel

Azure AI Search- (kallades tidigare Azure Cognitive Search) är en fullständigt hanterad molnsökningstjänst som tillhandahåller informationshämtning över användarägt innehåll.

REST-API:er för dataplan används för indexering och frågearbetsflöden och dokumenteras i det här avsnittet.

Kontrollplansåtgärder för tjänstadministration omfattas av en separat Management REST API.

Versionshanterade API-dokument

REST API-dokument är nu versionshanterade. När du öppnar en API-referenssida visas en versionsväljare ovanför innehållsförteckningen. Kontrollera att API-referensen kommer från mappen Reference > Data Plane.

Skärmbild av versionsväljaren.

Viktiga begrepp

Azure AI Search innehåller begreppen söktjänster, index, dokument, indexerare, datakällor, kunskapsuppsättningaroch synonymkartor.

  • En söktjänst är värd för index, indexerare, datakällor, kompetensuppsättningar och synonymkartor som objekt på den översta nivån.
  • Ett sökindex ger beständig lagring av sökdokument. Sökdokument är dina data, formulerade som en samling fält, som läses in från externa källor och skickas till ett index för att göra dem sökbara.
  • En sökindexerare lägger till automatisering, läser data i inbyggda format och serialiserar dem i JSON.
  • En indexerare har en datakälla och pekar på ett index.
  • En indexerare kan också ha en kompetensuppsättning som lägger till AI-berikning och integrerad vektorisering till indexeringspipelinen. Kunskapsuppsättningar är alltid kopplade till en indexerare. De anropar maskininlärning för att extrahera eller segmentera text, vektorisera innehåll, härleda funktioner eller lägga till struktur i innehåll för förbättrad indexering av en söktjänst.

Du kan skapa följande objekt i en söktjänst:

Objekt Beskrivning
Datakällor En datakällaanslutning som används av en indexerare för att hämta och uppdatera dokument för indexering. Datakällor har en type. Du kan använda Anslutningar som tillhandahålls av Microsoft för Azure eller partneranslutningar. Se galleriet Datakällor för den fullständiga listan.
Dokument Konceptuellt är ett dokument en entitet i ditt index. Mappa det här konceptet till mer välbekanta databasekvivalenter: ett sökindex motsvarar en tabell och dokument motsvarar i stort sett rader i en tabell. Dokument finns bara i ett index och hämtas endast via frågor som riktar sig till dokumentsamlingen (/docs) för ett index. Alla åtgärder som utförs i samlingen, till exempel överföring, sammanslagning, borttagning eller frågekörning av dokument, sker i kontexten för ett enda index, så dokumentåtgärderna i URL-format innehåller alltid /indexes/[index name]/docs för ett visst indexnamn.
Index Ett index lagras i söktjänsten och fylls i med JSON-dokument som indexeras och tokeniseras för informationshämtning. Fältsamlingen för ett index definierar sökdokumentets struktur. Fält har ett namn, datatyper och attribut som avgör användningen. Till exempel används searchable fält i fulltextsökning och därmed tokeniseras under indexering. Ett index definierar även andra konstruktioner, till exempel bedömningsprofiler för relevansjustering, förslagsgivare, semantiska konfigurationer och anpassade analysverktyg.
Indexerare Indexerare tillhandahåller indexeringsautomatisering. En indexerare ansluter till en datakälla, läser in data och skickar dem till en sökmotor för indexering till ett målsökindex. Indexerare läser från en extern källa med hjälp av anslutningsinformation i en datakälla och serialiserar inkommande data till JSON-sökdokument. Förutom en datakälla kräver en indexerare också ett index. Indexet anger fälten och attributen för sökdokumenten.
Kompetensuppsättningar En kompetensuppsättning lägger till externa bearbetningssteg för indexeringskörning och används för att använda AI- eller djupinlärningsmodeller för att analysera eller transformera innehåll för förbättrad sökbarhet i ett index. Innehållet i en kompetensuppsättning är en eller flera kunskaper, som kan inbyggda kunskaper som skapats av Microsoft, anpassade kunskaper eller en kombination av båda. Inbyggda kunskaper finns för bildanalys, inklusive OCR och bearbetning av naturligt språk. Andra exempel på inbyggda kunskaper är entitetsigenkänning, extrahering av nyckelfraser, segmentering av text i logiska sidor, bland annat. En kompetensuppsättning är fristående objekt på hög nivå som finns på en nivå som motsvarar index, indexerare och datakällor, men som endast används inom indexerarens bearbetning. Som ett objekt på hög nivå kan du utforma en kompetensuppsättning en gång och sedan referera till den i flera indexerare.
Synonymkartor En synonymkarta är ett objekt på tjänstnivå som innehåller användardefinierade synonymer. Det här objektet underhålls oberoende av sökindex. När du har laddat upp kan du peka alla sökbara fält på synonymkartan (ett per fält).

Behörigheter och åtkomstkontroll

Du kan använda nyckelbaserad autentisering eller rollbaserad via Microsoft Entra-ID.

  • nyckelbaserad autentisering förlitar sig på API-nycklar som genereras för söktjänsten. Att ha en giltig nyckel upprättar förtroende per begäran mellan programmet som skickar begäran och den tjänst som hanterar den. Du kan använda en admin-API-nyckel för skrivåtgärder eller en fråge-API-nyckel för läsåtkomst till dokumentsamlingen för ett sökindex.

  • Microsoft Entra ID-autentisering och rollbaserad åtkomstkontroll kräver att du har en etablerad klientorganisation i Microsoft Entra-ID med säkerhetsobjekt och rolltilldelningar. Medlemmar i följande roller har åtkomst till dataplanet. Du kan skapa anpassade roller om de inbyggda rollerna inte räcker till.

    Roll Tillträde
    Söktjänstdeltagare Åtkomst till objekt, men ingen åtkomst till indexinnehåll. Den här rollen skapar ett sökindex och andra objekt på den översta nivån, men kan inte köra frågor mot ett sökindex eller lägga till, ta bort eller uppdatera dokument i ett sökindex. Den här rollen är till för utvecklare som skapar, uppdaterar och tar bort objektdefinitioner. Det är också för administratörer som behöver hantera objekt, men utan möjlighet att visa eller komma åt objektdata.
    Search Data Index-deltagare Läs- och skrivåtkomst till indexinnehåll. Den här rollen är avsedd för utvecklare eller indexägare som behöver importera, uppdatera eller köra frågor mot dokumentsamlingen för ett index.
    Search Data Index Reader Läsåtkomst till indexinnehåll. Den här rollen gäller för appar och användare som kör frågor.

När du använder roller i anslutningen visar klientappen en ägartoken i auktoriseringshuvudet. Se Auktorisera åtkomst till en sökapp med hjälp av Microsoft Entra-ID om du behöver hjälp med att konfigurera detta.

Du kan inaktivera nyckelbaserad autentisering eller rollbaserad autentisering. Om du inaktiverar rollbaserad autentisering gäller det bara för dataplansåtgärder. Kontrollplansåtgärder, till exempel tjänstadministration, använder alltid rollbaserad autentisering. Mer information finns i Microsoft Entra ID-autentisering och rollbaserad åtkomstkontroll för Azure AI Search-.

Anropa API:erna

API:erna som beskrivs i det här avsnittet ger åtkomst till åtgärder för sökdata, till exempel skapande av index och population, dokumentuppladdning och frågor. Tänk på följande när du anropar API:er:

  • Begäranden måste utfärdas via HTTPS (på standardporten 443).

  • Begärande-URI:er måste innehålla api-version. Värdet måste anges till en version som stöds, formaterad enligt följande exempel: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01

  • Begärandehuvuden måste innehålla antingen en API-nyckel eller en ägartoken för autentiserade anslutningar. Du kan också ange rubriken Acceptera HTTP. Om innehållstyprubriken inte har angetts antas standardvärdet vara application/json.

Se även