Referens för REST API för Azure AI Search

  • Artikel

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

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

Kontrollplansåtgärder nås via ett separat REST-API för hantering.

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 Referensdataplan>.

Skärmbild av versionsväljaren.

Viktiga begrepp

Azure AI Search har begreppen söktjänster, index, dokument, indexerare, datakällor, kompetensuppsättningar och 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. Search dokument är dina data, formulerade som en samling fält, lästs in från externa källor och push-överförts till ett index för att göra dem sökbara.
  • En sökindexerare lägger till automatisering, läser data i interna format och serialiserar dem till 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 i indexeringspipelinen. Kompetensuppsä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 så att det kan indexeras av en söktjänst.

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

Objekt Description
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 från Microsoft för Azure eller anslutningsappar från tredje part via partner. Den fullständiga listan finns i galleriet Datakällor .
Dokument Konceptuellt är ett dokument en entitet i ditt index. Det här konceptet mappas till mer välbekanta databasmotsvarigheter: ett sökindex motsvarar en tabell och dokument är ungefär likvärdiga med 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 på samlingen, till exempel överföring, sammanslagning, borttagning eller frågekörning av dokument, utförs i kontexten för ett enda index, så DOKUMENTåtgärder i URL-format kommer alltid att inkluderas /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 hur de används. Till exempel searchable används 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örslagstagare, 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 vanligtvis för att lägga till AI- eller djupinlärningsmodeller för att analysera eller transformera innehåll så att det blir sökbart i ett index. Innehållet i en kompetensuppsättning är en eller flera färdigheter, som kan vara inbyggda färdigheter som skapats av Microsoft, anpassade färdigheter eller en kombination av båda. Inbyggda kunskaper finns för bildanalys, inklusive OCR och bearbetning av naturligt språk. Andra exempel på inbyggda färdigheter är entitetsigenkänning, extrahering av nyckelfraser, segmentering av text i bland annat logiska sidor. En kompetensuppsättning är fristående objekt på hög nivå som finns på en nivå som motsvarar index, indexerare och datakällor, men den fungerar bara 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 är beroende av API-nycklar som genereras för söktjänsten. En giltig nyckel upprättar förtroende, i varje begäran, mellan programmet som skickar begäran och tjänsten som hanterar den. Du kan använda en Admin API-nyckel för läs- och 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 Access
    Search-tjänstdeltagare Åtkomst till objekt, men ingen åtkomst till indexinnehåll. Den här rollen kan inte fråga ett sökindex eller lägga till, ta bort eller uppdatera dokument i ett sökindex. Den här rollen är avsedd för administratörer som behöver hantera objekt, men utan möjlighet att visa eller komma åt objektdata.
    Search dataindexdeltagare 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 fråga dokumentsamlingen för ett index.
    Search dataindexläsare Läsbehörighet till indexinnehåll. Den här rollen är avsedd 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. Mer information om hur du konfigurerar detta finns i Auktorisera åtkomst till en sökapp med hjälp av Microsoft Entra ID.

Du kan inaktivera nyckelbaserad autentisering eller rollbaserad autentisering. Om du inaktiverar rollbaserad autentisering har vissa inbyggda roller fortfarande åtkomst. Mer information finns i Microsoft Entra ID autentisering och rollbaserad åtkomstkontroll för Azure AI-Search.

Anropa API:erna

API:erna som dokumenteras i det här avsnittet ger åtkomst till åtgärder för sökdata, till exempel skapande av index och befolkning, 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-versionen. Värdet måste anges till en version som stöds, formaterad enligt det som visas i det här exemplet: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

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

Se även