Referenční informace k rozhraní REST API služby Azure AI Search
Azure AI Search (dříve označovaná jako Azure Cognitive Search) je plně spravovaná cloudová vyhledávací služba, která poskytuje načítání informací z obsahu vlastněného uživatelem.
Rozhraní REST API roviny dat se používají k indexování a dotazování pracovních postupů a jsou zdokumentovaná v této části.
Operace řídicí roviny pro správu služby jsou popsané v samostatném rozhraní REST API pro správu.
Dokumentace k rozhraní API s verzemi
Dokumentace k rozhraní REST API je teď ve verzích. Když otevřete stránku s referenčními informacemi k rozhraní API, nad obsahem se zobrazí selektor verzí. Ujistěte se, že reference k rozhraní API pocházejí ze složky Referenční > rovina dat .
Klíčové koncepty
Azure AI Search má koncepty vyhledávacích služeb, indexů, dokumentů, indexerů, zdrojů dat, sad dovedností a map synonym.
- Vyhledávací služba hostuje indexy, indexery, zdroje dat, sady dovedností a mapy synonym jako objekty nejvyšší úrovně.
- Index vyhledávání poskytuje trvalé úložiště dokumentů hledání. Prohledávat dokumenty jsou vaše data, vyjádřená jako kolekce polí, načtená z externích zdrojů a vložená do indexu, aby je bylo možné prohledávat.
- Vyhledávací indexer přidává automatizaci, čte data v nativních formátech a serializuje je do formátu JSON.
- Indexer má zdroj dat a odkazuje na index.
- Indexer může mít také sadu dovedností, která do kanálu indexování přidává rozšiřování AI a integrovanou vektorizaci . Sady dovedností jsou vždy připojeny k indexeru. Volají strojové učení, aby extrahovali nebo blokovali text, vektorizovali obsah, odvozovali funkce nebo přidávali strukturu obsahu, aby ho bylo možné indexovat vyhledávací službou.
Celkem můžete ve vyhledávací službě vytvořit následující objekty:
| Objekty | Description |
|---|---|
| Zdroje dat | Připojení ke zdroji dat používané indexerem k načítání a aktualizaci dokumentů pro indexování. Zdroje dat mají .type Můžete použít připojení poskytovaná Microsoftem pro Azure nebo konektory třetích stran prostřednictvím partnerů. Úplný seznam najdete v galerii zdrojů dat . |
| dokumenty. | Dokument je v indexu entitou. Mapování tohoto konceptu na známější databázové ekvivalenty: index vyhledávání se rovná tabulce a dokumenty jsou zhruba ekvivalentní řádkům v tabulce. Dokumenty existují pouze v indexu a načítají se pouze prostřednictvím dotazů, které cílí na kolekci dokumentů (/docs) indexu. Všechny operace prováděné s kolekcí, jako je nahrávání, slučování, odstraňování nebo dotazování dokumentů, probíhají v kontextu jednoho indexu, takže operace s dokumentem ve formátu adresy URL budou vždy zahrnovat /indexes/[index name]/docs pro daný název indexu. |
| Indexy | Index je uložený ve službě Search a naplněný dokumenty JSON, které se indexují a tokenizují pro načtení informací. Kolekce polí indexu definuje strukturu dokumentu hledání. Pole mají název, datové typy a atributy, které určují, jak se používají. searchable Například pole se používají při fulltextovém vyhledávání, a proto se tokenizují během indexování. Index také definuje další konstrukce, jako jsou profily bodování pro ladění relevance, návrhy, sémantické konfigurace a vlastní analyzátory. |
| Indexery | Indexery poskytují automatizaci indexování. Indexer se připojí ke zdroji dat, přečte data a předá je vyhledávacímu webu k indexování do cílového indexu vyhledávání. Indexery čtou z externího zdroje pomocí informací o připojení ve zdroji dat a serializují příchozí data do dokumentů json pro vyhledávání. Kromě zdroje dat vyžaduje index také index. Index určuje pole a atributy dokumentů hledání. |
| Sady dovedností | Sada dovedností přidává do provádění indexeru kroky externího zpracování a obvykle se používá k přidání modelů AI nebo hlubokého učení, které analyzují nebo transformují obsah, aby bylo možné ho prohledávat v indexu. Obsahem sady dovedností je jedna nebo více dovedností, které můžou být předdefinované dovednosti vytvořené microsoftem, vlastní dovednosti nebo kombinace obojího. Existují integrované dovednosti pro analýzu obrázků, včetně OCR, a zpracování přirozeného jazyka. Mezi další příklady předdefinovaných dovedností patří rozpoznávání entit, extrakce klíčových frází, rozdělení textu do logických stránek a další. Sada dovedností je samostatný objekt vysoké úrovně, který existuje na úrovni ekvivalentní indexům, indexerům a zdrojům dat, ale funguje pouze v rámci zpracování indexeru. Jako objekt vysoké úrovně můžete sadu dovedností navrhnout jednou a pak na ni odkazovat ve více indexerech. |
| Mapy synonym | Mapa synonym je objekt na úrovni služby, který obsahuje uživatelem definovaná synonyma. Tento objekt se udržuje nezávisle na indexech vyhledávání. Po nahrání můžete na mapu synonym nasměrovat libovolné prohledávatelné pole (jedno na každé pole). |
Oprávnění a řízení přístupu
Prostřednictvím Microsoft Entra ID můžete použít ověřování na základě klíčů nebo na základě rolí.
Ověřování na základě klíčů spoléhá na klíče rozhraní API, které se vygenerují pro vyhledávací službu. Platný klíč vytváří na základě žádosti vztah důvěryhodnosti mezi aplikací, která žádost odeslala, a službou, která ji zpracovává. Klíč rozhraní API Správa můžete použít pro operace čtení i zápisu nebo klíč rozhraní API pro dotazy pro přístup ke čtení ke kolekci dokumentů indexu vyhledávání.
Microsoft Entra ID ověřování a řízení přístupu na základě role vyžaduje, abyste měli vytvořeného tenanta ve Microsoft Entra ID s objekty zabezpečení a přiřazeními rolí. Členové následujících rolí mají přístup k rovině dat. Pokud předdefinované role nestačí, můžete vytvořit vlastní role.
Role Access Přispěvatel Vyhledávací služby Přístup k objektům, ale žádný přístup k obsahu indexu Tato role vytvoří index vyhledávání a další objekty nejvyšší úrovně, ale nemůže dotazovat index vyhledávání ani přidávat, odebírat nebo aktualizovat dokumenty v indexu vyhledávání. Tato role je určená vývojářům, kteří vytvářejí, aktualizují a odstraňují definice objektů. Je také pro správce, kteří potřebují spravovat objekty, ale nemají možnost zobrazit data objektů nebo přistupovat k datům objektů. Přispěvatel indexu dat vyhledávání Přístup pro čtení i zápis k obsahu indexu. Tato role je pro vývojáře nebo vlastníky indexů, kteří potřebují importovat, aktualizovat nebo dotazovat kolekci dokumentů indexu. Čtečka indexu vyhledávacích dat Oprávnění ke čtení obsahu indexu Tato role je určená pro aplikace a uživatele, kteří spouštějí dotazy.
Při použití rolí v připojení klientská aplikace zobrazí nosný token v autorizační hlavičce. Nápovědu k tomuto nastavení najdete v tématu Autorizace přístupu k aplikaci Vyhledávací služby pomocí Microsoft Entra ID.
Můžete zakázat ověřování na základě klíčů nebo ověřování na základě rolí. Pokud zakážete ověřování na základě rolí, bude platit pouze pro operace roviny dat. Operace řídicí roviny, jako je správa služeb, vždy používají ověřování na základě rolí. Podrobnosti najdete v tématu Microsoft Entra ID ověřování a řízení přístupu na základě role pro Azure AI Search.
Volání rozhraní API
Rozhraní API zdokumentovaná v této části poskytují přístup k operacím s daty vyhledávání, jako je vytvoření indexu a populace, nahrávání dokumentů a dotazy. Při volání rozhraní API mějte na paměti následující body:
Požadavky musí být vydávány přes protokol HTTPS (na výchozím portu 443).
Identifikátory URI požadavků musí obsahovat verzi api. Hodnota musí být nastavená na podporovanou verzi ve formátu, jak je znázorněno v tomto příkladu:
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01Hlavičky požadavku musí obsahovat klíč rozhraní API nebo nosný token pro ověřená připojení. Volitelně můžete nastavit hlavičku Accept HTTP . Pokud hlavička typu obsahu není nastavená, předpokládá se, že výchozí hodnota je
application/json.