Azure Cognitive Search Service REST

Azure Cognitive Search är en fullständigt hanterad molnsökningstjänst som ger en omfattande sökupplevelse över användarägt innehåll. Ett sätt att lägga till sökfunktionen är via REST-API:er för sökning, med åtgärder som skapar och hanterar index, läser in data, implementerar sökfunktioner, kör frågor och hanterar resultat.

Ett separat REST-API för hantering kan användas för att skapa eller ändra själva tjänsten. Du kan också använda portalen för många tjänst- och innehållshanteringsuppgifter. Kom igång genom att läsa Skapa en söktjänst i Azure Portal.

Viktiga begrepp

Cognitive Search har begreppen söktjänster , index och dokument:

  • En söktjänst innehåller ett eller flera index.
  • Ett index ger beständig lagring av sökdokument.
  • Sökdokument läses in från externa källor i form av JSON-dokument och skickas till ett index för att göra det sökbart.

Du kan också skapa en indexerare för att automatisera indexering. En indexerare har en datakälla och pekar på ett index. Alternativt kan den också ha en kompetensuppsättning som lägger till AI i indexerarens pipeline.

AI-berikning är ett tillägg av indexerare som lägger till maskininlärningstransformer som extraherar eller genererar text eller lägger till struktur i innehåll så att det kan indexeras av en söktjänst. Konstruktionen som driver AI-berikning kallas för en kompetensuppsättning. Under datainmatning definierar den en sekvens med steg som identifierar, strukturerar eller transformerar innehåll som annars inte kan sökas (till exempel bildinnehåll).

Tillsammans finns det fem typer av åtgärder som kan köras mot tjänsten:

Åtgärd Description
Index Skapa, ta bort, uppdatera eller konfigurera ett sökindex.
Dokument Lägg till, uppdatera eller ta bort dokument i indexet, fråga indexet eller leta upp specifika dokument efter ID.
Indexerare Automatisera aspekter av en indexeringsåtgärd genom att konfigurera en datakälla och en indexerare som du kan schemalägga eller köra på begäran. Den här funktionen stöds för ett begränsat antal typer av datakällor i Azure.
Skillset En del av en AI-berikningsarbetsbelastning definierar en kompetensuppsättning en serie berikningsbearbetning som extraherar eller skapar sökbar text från ostrukturerad text, programfiler eller bildfiler. En kompetensuppsättning anropas av en indexerare.
Synonymkarta En synonymkarta är en resurs på tjänstnivå som innehåller användardefinierade synonymer. Den här resursen 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).

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äranden måste innehålla API-versionen i URI:n. Värdet måste anges till en version som stöds och formateras enligt följande exempel: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Begärandehuvuden måste innehålla en API-nyckel som genererades för söktjänsten som du etablerade. 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 också ange rubriken Acceptera HTTP. Om rubriken inte har angetts antas standardvärdet vara application/json.

Nyckelautentisering

Varje HTTP-begäran till söktjänsten autentiseras baserat på två typer av information: en söktjänst-URL och en API-nyckel som visar att begäran kommer från en betrodd entitet. Det finns två typer av API-nycklar för olika åtgärdsnivåer.

Nyckel Beskrivning Gränser
Administratör Admin nycklar ger fullständig behörighet till alla åtgärder, inklusive möjligheten att hantera tjänsten, hämta status- och objektdefinitioner och skapa och ta bort index, indexerare och datakällor.

Två api-nycklar för administratörer, som kallas primära och sekundära nycklar i portalen, genereras automatiskt när tjänsten skapas och kan återskapas individuellt på begäran. Med två nycklar kan du rulla över en nyckel medan du använder den andra nyckeln för fortsatt åtkomst till tjänsten.

Admin nycklar anges endast i HTTP-begärandehuvuden. Du kan inte placera en api-nyckel för administratör i en URL.
Maximalt 2 per tjänst
Söka i data Frågenycklar ger skrivskyddad åtkomst till innehåll i ett index (dokument) och distribueras vanligtvis till klientprogram som utfärdar sökbegäranden.

Frågenycklar skapas på begäran. Du kan skapa dem manuellt i portalen eller programmatiskt via REST API för hantering.

Frågenycklar kan anges i ett HTTP-begärandehuvud för sökning, förslag eller sökning. Du kan också skicka en frågenyckel som en parameter på en URL. Beroende på hur klientprogrammet formulerar begäran kan det vara enklare att skicka nyckeln som en frågeparameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 per tjänst

Visuellt finns det ingen skillnad mellan en administratörsnyckel eller frågenyckel. Båda nycklarna är strängar som består av 32 slumpmässigt genererade alfanumeriska tecken. Om du förlorar kontrollen över vilken typ av nyckel som anges i ditt program kan du kontrollera nyckelvärdena i portalen eller använda REST API för hantering för att returnera värdet och nyckeltypen.

Anteckning

Det anses vara en dålig säkerhetspraxis att skicka känsliga data, till exempel en api-key i begärande-URI:n. Därför accepterar Azure Cognitive Search bara en frågenyckel som en api-key i frågesträngen, och du bör undvika att göra det om inte innehållet i ditt index ska vara offentligt tillgängligt. Som en allmän regel rekommenderar vi att du skickar din api-key som ett begärandehuvud.

Auktorisering

Cognitive Search stöder rollbaserad åtkomstkontroll i Azure (Azure RBAC) för söktjänstadministration, via rollerna Ägare, Deltagare och Läsare.

Om du vill kan du använda Azure RBAC för att styra åtkomsten till index och andra objekt i en söktjänst om du vill använda förhandsgranskningsfunktioner. Den här metoden kräver en söktjänst som konfigurerats för Azure RBAC på dataplanet och ett auktoriseringshuvud för REST API-anrop som autentiseras med Azure Active Directory.

Se även