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í přes obsah vlastněný 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žeb jsou popsány v samostatném rozhraní REST API služby Management.
Dokumentace k rozhraní API s verzí
Dokumentace k rozhraní REST API je teď ve verzi. Když otevřete referenční stránku rozhraní API, zobrazí se nad obsahem selektor verze. Ujistěte se, že odkaz rozhraní API pochází ze složky Reference > Rovina dat.
Klíčové koncepty
Azure AI Search má koncepty vyhledávacích služeb, indexů, dokumentů, indexerů, zdrojů dat, dovednostía mapy 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í. Vyhledávací dokumenty jsou vaše data, vyjádřená jako kolekce polí, načtená z externích zdrojů a vložená do indexu, aby bylo možné je prohledávat.
- Indexer vyhledávání přidává automatizaci, čtení dat v nativních formátech a serializaci 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á
rozšiřování umělé inteligence a integrované vektor izace. Sady dovedností jsou vždy připojeny k indexeru. Volají strojové učení za účelem extrakce nebo vytváření bloků textu, vektorizace obsahu, odvození funkcí nebo přidání struktury do obsahu pro lepší indexování vyhledávací službou.
Úplně můžete ve vyhledávací službě vytvořit následující objekty:
| Objekty | Popis |
|---|---|
| Zdroje dat | Připojení ke zdroji dat, které indexer používá k načtení a aktualizaci dokumentů pro indexování. Zdroje dat mají type. Můžete použít připojení poskytovaná Microsoftem pro Azure nebo partnerské konektory. Úplný seznam najdete v galerii zdrojů dat . |
| Dokumenty | Koncepčně je dokument entitou v indexu. Mapování tohoto konceptu na známé databázové ekvivalenty: index vyhledávání odpovídá 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 formátem adresy URL vždy obsahují /indexes/[index name]/docs pro daný název indexu. |
| Indexy | Index je uložený ve vyhledávací službě a naplněný dokumenty JSON, které jsou indexovány a tokenizovány pro načítání informací. Kolekce polí indexu definuje strukturu hledaného dokumentu. Pole mají název, datové typy a atributy, které určují využití. Například searchable pole se používají při fulltextové vyhledávání a tokenizují se při 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. |
| Indexování | Indexery poskytují automatizaci indexování. Indexer se připojí ke zdroji dat, přečte je a předá ho vyhledávacímu webu pro indexování do cílového vyhledávacího indexu. Indexery čtou z externího zdroje pomocí informací o připojení ve zdroji dat a serializují příchozí data do dokumentů hledání JSON. Kromě zdroje dat vyžaduje indexer také index. Index určuje pole a atributy vyhledávacích dokumentů. |
| Sady dovedností | Sada dovedností přidává kroky externího zpracování ke spuštění indexeru a používá se k použití modelů umělé inteligence nebo hlubokého učení k analýze nebo transformaci obsahu pro lepší prohledávání v indexu. Obsah sady dovedností je jedna nebo více dovedností, které mohou být předdefinované dovednosti vytvořené Microsoftem, vlastními dovednostmi nebo kombinací 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í, dělení textu na logické stránky mimo jiné. 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 jednou navrhnout sadu dovedností a pak na ni odkazovat ve více indexerech. |
| Mapy synonym | Mapa synonym je objekt na úrovni služby, který obsahuje uživatelsky definované synonyma. Tento objekt se udržuje nezávisle na indexech vyhledávání. Po nahrání můžete namapovat libovolné prohledávatelné pole na mapu synonym (jednu na jedno pole). |
Oprávnění a řízení přístupu
Ověřování na základě klíčů nebo na základě role můžete použít prostřednictvím ID Microsoft Entra.
ověřování založené na klíčích spoléhá na klíče rozhraní API generované pro vyhledávací službu. Když bude platný klíč navazovat vztah důvěryhodnosti na základě jednotlivých požadavků, mezi aplikací, která požadavek odešle, a službou, která ji zpracovává. Klíč rozhraní API pro správu můžete použít pro operace čtení a zápisu nebo klíč rozhraní API pro dotazu pro přístup pro čtení ke kolekci dokumentů indexu vyhledávání.
ověřování Microsoft Entra ID a řízení přístupu na základě role vyžaduje, abyste měli v Microsoft Entra ID vytvořeného tenanta 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 nejsou dostatečné, můžete vytvořit vlastní role.
Role Přístup Přispěvatel vyhledávací služby Přístup k objektům, ale bez přístupu k obsahu indexu Tato role vytvoří vyhledávací index a další objekty nejvyšší úrovně, ale nemůže dotazovat index vyhledávání, 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 to také pro správce, kteří potřebují spravovat objekty, ale bez možnosti zobrazit nebo přistupovat k datům objektu. Přispěvatel indexu vyhledávacích dat Přístup pro čtení a zápis k obsahu indexu Tato role je určená 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 Čtení přístupu k 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í zobrazí klientská aplikace v autorizační hlavičce nosný token. Nápovědu k nastavení najdete v tématu Autorizace přístupu k vyhledávací aplikaci pomocí Microsoft Entra ID.
Ověřování na základě klíčů nebo ověřování na základě role můžete zakázat. Pokud zakážete ověřování na základě role, platí jenom pro operace roviny dat. Operace roviny řízení, jako je správa služeb, vždy používají ověřování na základě role. Podrobnosti najdete v tématu ověřování Microsoft Entra ID a řízení přístupu na základě role pro službu Azure AI Search.
Volání rozhraní API
Rozhraní API zdokumentovaná v této části poskytují přístup k operacím s vyhledávacími daty, jako jsou vytváření indexů a počet obyvatel, 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 vystavené přes PROTOKOL HTTPS (na výchozím portu 443).
Identifikátory URI požadavků musí obsahovat
api-version . Hodnota musí být nastavená na podporovanou verzi, formátovaná tak, 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í obsahovatapi-key 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.