Rövid útmutató: Kulcsszókeresés REST használatával

Cikk
07/04/2024

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. Az utasításokat a Fájlok GitHubról való letöltésénél találja.

Ú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ásvégpont lekérése

A keresési szolgáltatás végpontja az Azure Portalon található.

Jelentkezzen be az Azure Portalra , és keresse meg a keresési szolgáltatást.
Az Áttekintés kezdőlapon keresse meg az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.

Ezt a végpontot egy későbbi lépésben illeszti be a fájlba vagy .http a .rest fájlba.

Hozzáférés konfigurálása

A keresési végpontra irányuló kéréseket hitelesíteni és engedélyezni kell. Ehhez a feladathoz API-kulcsokat vagy szerepköröket használhat. A kulcsokkal könnyebb kezdeni, de a szerepkörök biztonságosabbak.

Szerepköralapú kapcsolat esetén az alábbi utasítások szerint az Ön identitása alatt kell csatlakoznia az Azure AI Search szolgáltatáshoz, nem pedig egy ügyfélalkalmazás identitásához.

1. lehetőség: Kulcsok használata

Válassza a Beállításkulcsok>lehetőséget, majd másolja a rendszergazdai kulcsot. A rendszergazdai 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. További információ: Csatlakozás az Azure AI Search szolgáltatáshoz kulcshitelesítés használatával.

Ezt a kulcsot egy későbbi lépésben illeszti be a .rest fájlba..http

2. lehetőség: Szerepkörök használata

Győződjön meg arról, hogy a keresési szolgáltatás szerepköralapú hozzáférésre van konfigurálva. Előre konfigurált szerepkör-hozzárendelésekkel kell rendelkeznie a fejlesztői hozzáféréshez. A szerepkör-hozzárendeléseknek engedélyt kell adniuk a keresési indexek létrehozására, betöltésére és lekérdezésére.

Ebben a szakaszban szerezze be a személyes identitás jogkivonatát az Azure CLI, az Azure PowerShell vagy az Azure Portal használatával.

Jelentkezzen be az Azure CLI-be.
```
az login
```

Szerezze be a személyes identitás jogkivonatát.

az account get-access-token --scope https://search.azure.com/.default

A személyes identitás jogkivonatát egy későbbi lépésben illeszti be a .rest .http fájlba.

Feljegyzés

Ez a szakasz feltételezi, hogy egy helyi ügyfelet használ, amely az Ön nevében csatlakozik az Azure AI Search szolgáltatáshoz. Egy másik módszer egy jogkivonat lekérése az ügyfélalkalmazáshoz, feltéve, hogy az alkalmazás regisztrálva van a Microsoft Entra-azonosítóval.

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 .http fájlkiterjesztéssel .rest ellátott fájlt.

Illessze be az alábbi példába, ha API-kulcsokat használ. Cserélje le a @baseUrl helyőrzőket @apiKey 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}}

Vagy illessze be ezt a példát, ha szerepköröket használ. Cserélje le a @baseUrl helyőrzőket @token a korábban másolt értékekre.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2023-11-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

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őt HTTP/1.1.
- Send request a kérés felett kell megjelennie.

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-quickstart index 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
  Authorization: Bearer {{token}}

    {
        "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 és api-key kö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
  Authorization: Bearer {{token}}

    {
        "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ális searchFields paramé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
  Authorization: Bearer {{token}}

  {
      "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 select utasí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
  Authorization: Bearer {{token}}

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.

Rövid útmutató: Vektorkeresés REST használatával

Megosztás a következőn keresztül: