Rövid útmutató: Szövegkeresés REST használatával
Az Azure AI Search REST API-jai programozott hozzáférést biztosítanak az összes funkcióhoz, beleértve az előzetes verziójú funkciókat is, és könnyen elsajátíthatják a funkciók működését. Ebben a rövid útmutatóban megtudhatja, hogyan hívhatja meg a Search REST API-kat keresési indexek létrehozásához, betöltéséhez és lekérdezéséhez az Azure AI Searchben.
Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.
Előfeltételek
- Visual Studio Code REST-ügyféllel.
- Azure AI Search. Hozzon létre vagy keressen egy meglévő Azure AI Search-erőforrást az aktuális előfizetése alatt. Ehhez a rövid útmutatóhoz ingyenes szolgáltatást használhat.
Fájlok letöltése
Töltsön le egy REST-mintát a GitHubról a kérések elküldéséhez ebben a rövid útmutatóban. További információ: Fájlok letöltése a GitHubról.
Új fájlt is elindíthat a helyi rendszeren, és manuálisan is létrehozhat kéréseket a jelen cikk utasításainak megfelelően.
Keresési szolgáltatáskulcs és URL-cím másolása
A REST-hívásokhoz minden kéréshez szükség van a keresési szolgáltatás végpontjára és egy API-kulcsra. Ezeket az értékeket az Azure Portalon szerezheti be.
Jelentkezzen be az Azure Portalra. Ezután nyissa meg a keresési szolgáltatás áttekintési oldalát, és másolja ki az URL-címet. A végpontok például a következőképpen nézhetnek ki:
https://mydemo.search.windows.net.Válassza a Gépház> Kulcsok lehetőséget, majd másolja a rendszergazdai kulcsot. Rendszergazda kulcsok objektumok hozzáadására, módosítására és törlésére szolgálnak. Két felcserélhető rendszergazdai kulcs van. Másolja valamelyiket.
A Visual Studio Code telepítése
Ha nem ismeri a Visual Studio Code REST-ügyfelét, ez a szakasz a telepítést is tartalmazza, hogy elvégezhesse a feladatokat ebben a rövid útmutatóban.
Indítsa el a Visual Studio Code-ot, és válassza a Bővítmények csempét .
Keresse meg a REST-ügyfelet, és válassza a Telepítés lehetőséget.
Nyisson meg vagy hozzon létre egy új, vagy
.httpfájlkiterjesztéssel.restellátott fájlt.Illessze be a következő példába. Cserélje le az alap URL-címet és az API-kulcsot a korábban másolt értékekre.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2023-11-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Válassza a Kérés elküldése elemet. A válasznak egy szomszédos panelen kell megjelennie. Ha már rendelkezik meglévő indexel, azok szerepelnek a listában. Ellenkező esetben a lista üres. Ha a HTTP-kód az
200 OK, készen áll a következő lépésekre.
Összefoglalás:
- A paraméterek egy előtag használatával
@vannak megadva. ###EGY REST-hívást jelöl ki. A következő sor tartalmazza a kérést, amelynek tartalmaznia kell a következőtHTTP/1.1.Send requesta kérés felett kell megjelennie.
- A paraméterek egy előtag használatával
Index létrehozása
Adjon hozzá egy második kérést a fájlhoz .rest . Az Index létrehozása (REST) létrehoz egy keresési indexet, és beállítja a fizikai adatstruktúrákat a keresési szolgáltatásban.
Illessze be az alábbi példába az
hotels-quickstartindex létrehozásához a keresési szolgáltatásban.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] }Válassza a Kérés elküldése elemet. Válasznak kell lennie
HTTP/1.1 201 Created, és a válasz törzsének tartalmaznia kell az indexséma JSON-ábrázolását.Ha hibaüzenetet
Header name must be a valid HTTP token ["{"]kap, győződjön meg arról, hogy üres sor van a kérés törzse ésapi-keyközött. Ha HTTP 504-et kap, ellenőrizze, hogy az URL-cím a HTTPS-t adja-e meg. Ha 400-as vagy 404-es HTTP-válasz jelenik meg, akkor ellenőrizze, hogy a kérelem törzsében nincsenek-e beillesztési hibák. A HTTP 403 általában az API-kulccsal kapcsolatos problémát jelez. Érvénytelen kulcs vagy szintaxisbeli probléma az API-kulcs megadásának módjával kapcsolatban.Most már több kérés is szerepel a fájlban. Ne feledje, hogy
###egy új kérést indít el, és minden kérés egymástól függetlenül fut.
Az indexdefiníció ismertetése
Az indexsémán belül a mezők gyűjteménye határozza meg a dokumentumstruktúrát. Minden feltöltött dokumentumnak rendelkeznie kell ezekkel a mezőkkel. Minden mezőt hozzá kell rendelni egy entity data model (EDM) adattípushoz. A sztringmezők a teljes szöveges keresésben használatosak. Ha azt szeretné, hogy a numerikus adatok kereshetők legyenek, győződjön meg arról, hogy az adattípus .Edm.String Más adattípusok, például Edm.Int32 szűrhető, rendezhető, facetable és lekérdezhető, de nem teljes szöveges kereshetőek.
A mező attribútumai határozzák meg az engedélyezett műveleteket. A REST API-k alapértelmezés szerint számos műveletet engedélyeznek. Az összes sztring például alapértelmezés szerint kereshető és lekérdezhető. A REST API-k esetében előfordulhat, hogy csak akkor rendelkezik attribútumokkal, ha ki kell kapcsolnia egy viselkedést.
{
"name": "hotels-quickstart",
"fields": [
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
{"name": "Address", "type": "Edm.ComplexType",
"fields": [
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
]
}
]
}
Dokumentumok betöltése
Az index létrehozása és betöltése külön lépések. Az Azure AI Searchben az index tartalmazza a keresési szolgáltatásban futtatott összes kereshető adatot és lekérdezést. REST-hívások esetén az adatok JSON-dokumentumokként vannak megadva. Dokumentumok – Indexelje a REST API-t ehhez a feladathoz.
Az URI ki van terjesztve a gyűjteményekre és index a docs műveletekre.
Illessze be az alábbi példában a JSON-dokumentumok keresési indexbe való feltöltéséhez.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Secret Point Motel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Twin Dome Motel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Triple Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }Válassza a Kérés elküldése elemet. Néhány másodperc múlva http 201-választ kell látnia a szomszédos panelen.
Ha a 207-es HTTP-válasz jelenik meg, legalább egy dokumentumot nem sikerült feltölteni. Ha a 404-es válasz jelenik meg, akkor a kérelem fejlécében vagy törzsében szintaktikai hiba van. Ellenőrizze, hogy módosította-e a végpontot a belefoglalásra
/docs/index.
Lekérdezések futtatása
A dokumentumok betöltése után lekérdezéseket állíthat ki ellenük a Dokumentumok – Keresés utáni (REST) funkcióval.
Az URI ki van terjesztve egy lekérdezési kifejezésre, amelyet az /docs/search operátor használ.
Illessze be a következő példába a keresési index lekérdezéséhez. Ezután válassza a Kérés küldése lehetőséget. A szöveges keresési kérések mindig tartalmaznak egy paramétert
search. Ez a példa tartalmaz egy opcionálissearchFieldsparamétert, amely a szövegkeresést bizonyos mezőkre korlátozza.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }Tekintse át a választ a szomszédos panelen. Rendelkeznie kell egy számlálóval, amely az indexben található egyezések számát, egy relevanciát jelző keresési pontszámot és az
selectutasításban felsorolt mezők értékeit jelzi.{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
Indextulajdonságok lekérése
A Dokumentumok számának és az index méretének lekérdezéséhez a Statisztika lekérése parancsot is használhatja.
Illessze be a következő példába a keresési index lekérdezéséhez. Ezután válassza a Kérés küldése lehetőséget.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Tekintse meg a választ. Ezzel a művelettel egyszerűen lekérheti az indextároló részleteit.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
Az erőforrások eltávolítása
Ha a saját előfizetésében dolgozik, érdemes az egyes projektek végén eldöntenie, hogy szüksége lesz-e még a létrehozott erőforrásokra. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.
Az erőforrásokat a portálon a bal szélső panel Minden erőforrás vagy Erőforráscsoport hivatkozásával keresheti meg és kezelheti.
Ezt a DELETE parancsot is kipróbálhatja:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Következő lépés
Most, hogy már ismeri a REST-ügyfelet, és REST-hívásokat indít az Azure AI Search szolgáltatásba, próbálkozzon egy másik gyorsútmutatóval, amely bemutatja a vektorok támogatását.