Rövid útmutató: Keresési index létrehozása a PowerShellben REST API-k használatával

  • Cikk

Ebben az Azure AI Search rövid útmutatójában megtudhatja, hogyan hozhat létre, tölthet be és kérdezhet le keresési indexeket a PowerShell és az Azure AI Search REST API-k használatával. Ez a cikk a PowerShell-parancsok interaktív futtatását ismerteti. Másik lehetőségként letölthet és futtathat egy PowerShell-szkriptet , amely ugyanazokat a műveleteket hajtja végre.

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Előfeltételek

Ehhez a rövid útmutatóhoz a következő szolgáltatásokra és eszközökre van szükség:

Keresési szolgáltatáskulcs és URL-cím másolása

Ebben a rövid útmutatóban a REST-hívások tartalmazzák a szolgáltatás URL-címét és egy hozzáférési kulcsot minden kéréshez. Mindkét szolgáltatással létrejön egy keresési szolgáltatás, ezért ha hozzáadta az Azure AI Search szolgáltatást az előfizetéséhez, az alábbi lépésekkel szerezheti be a szükséges információkat.

  1. Jelentkezzen be az Azure Portalra. A keresési szolgáltatás áttekintési lapján kérje le az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.

  2. Válassza a Gépház> Keys elemet, majd szerezze be a teljes jogokat a szolgáltatáshoz. Két felcserélhető rendszergazdai kulcs áll rendelkezésre az üzletmenet folytonosságához, ha át kell gördítenie egyet. Az elsődleges vagy a másodlagos kulcsot használhatja objektumok hozzáadására, módosítására és törlésére vonatkozó kérelmekhez.

    A HTTP-végpont és a hozzáférési kulcs lekérését bemutató képernyőkép.

Minden kéréshez api-kulcs szükséges a szolgáltatásnak küldött összes kérelemhez. Az érvényes kulcs kérésenként megbízhatóságot hoz létre a kérelmet küldő alkalmazás és az azt kezelő szolgáltatás között.

  1. A PowerShellben hozzon létre egy $headers objektumot a tartalomtípus és az API-kulcs tárolásához. Cserélje le a rendszergazdai API-kulcsot (YOUR-ADMIN-API-KEY) a keresési szolgáltatásra érvényes kulcsra. Ezt a fejlécet csak egyszer kell beállítania a munkamenet idejére, de minden kéréshez hozzá kell adnia.

    $headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

  2. Hozzon létre egy $url objektumot, amely meghatározza a szolgáltatás indexgyűjteményét. Cserélje le a szolgáltatásnevet (YOUR-SEARCH-SERVICE-NAME) egy érvényes keresési szolgáltatásra.

    $url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"

  3. Futtassa Invoke-RestMethod a GET kérés küldését a szolgáltatásnak, és ellenőrizze a kapcsolatot. Adja hozzá ConvertTo-Json , hogy megtekinthesse a szolgáltatásból visszaküldött válaszokat.

    Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

    Ha a szolgáltatás üres, és nincs indexe, az eredmények hasonlóak az alábbi példához. Ellenkező esetben az indexdefiníciók JSON-ábrázolása jelenik meg.

    {
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}

Index létrehozása

Ha nem használja a portált, az adatok betöltése előtt indexnek kell lennie a szolgáltatásban. Ez a lépés határozza meg az indexet, és leküldi a szolgáltatásba. Ehhez a lépéshez az Index létrehozása REST API-t használjuk.

Az index kötelező elemei közé tartozik egy név és egy mezőgyűjtemény. A mezők gyűjteménye határozza meg a dokumentum struktúráját. Minden mezőnek van egy neve, típusa és attribútuma, amely meghatározza a használat módját (például hogy teljes szöveges kereshető, szűrhető vagy lekérdezhető-e a keresési eredményekben). Egy indexen belül a típusmezők Edm.String egyikét meg kell jelölni a dokumentumdentitás kulcsának .

Az index neve hotels-quickstart és meződefiníciói az alábbi kódban láthatók. Ez egy nagyobb hotels index részhalmaza, amelyet más útmutató cikkekben használnak. A meződefiníciókat ebben a rövid útmutatóban vágja le a rendszer a rövidítés érdekében.

  1. Illessze be ezt a példát a PowerShellbe az $body indexsémát tartalmazó objektum létrehozásához.

    $body = @"
{
    "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}
        ]
     }
  ]
}
"@

  2. Állítsa az URI-t a szolgáltatás és az index indexgyűjteményére hotels-quickstart .

    $url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"

  3. Futtassa a parancsot a , $headersparanccsal$url, és $body hozza létre az indexet a szolgáltatásban.

    Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

    Az eredményeknek a példához hasonlóan kell kinéznie, amely csak az első két mezőt jeleníti meg a rövidség kedvéért:

    {
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
    "name":  "hotels-quickstart",
    "defaultScoringProfile":  null,
    "fields":  [
                {
                    "name":  "HotelId",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  true,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  true,
                    "key":  true,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                {
                    "name":  "HotelName",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  false,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  false,
                    "key":  false,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                . . .
    ]
}

Tipp.

Az ellenőrzéshez az Indexek listát is ellenőrizheti a portálon.

Dokumentumok betöltése

Dokumentumok leküldéséhez használjon HTTP POST-kérést az index URL-végpontjára. A feladat REST API-ja a Dokumentumok hozzáadása, frissítése vagy törlése.

  1. Illessze be ezt a példát a PowerShellbe, és hozzon létre egy $body objektumot, amely tartalmazza a feltölteni kívánt dokumentumokat.

    Ez a kérés két teljes rekordot és egy részleges rekordot tartalmaz. A részleges rekord azt mutatja, hogy hiányos dokumentumokat tölthet fel. A @search.action paraméter az indexelés módját határozza meg. Az érvényes értékek a következők: upload, merge, mergeOrUploadés delete. A mergeOrUpload viselkedés vagy létrehoz egy új dokumentumot, hotelId = 3 vagy frissíti a tartalmat, ha már létezik.

    $body = @"
{
    "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"
        }
    }
]
}
"@

  2. Állítsa a végpontot a hotels-quickstart dokumentumgyűjteményre, és adja meg az indexműveletet (indexes/hotels-quickstart/docs/index).

    $url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"

  3. Futtassa a parancsot az , paranccsal$url, és $body töltse be a dokumentumokat az hotels-quickstart indexbe. $headers

    Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

    Az eredményeknek az alábbi példához hasonlóan kell kinéznie. Ekkor megjelenik egy 201-ből álló állapotkód.

    {
    "@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
    "value":  [
                {
                    "key":  "1",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "2",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "3",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "4",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                }
            ]
}

Keresés az indexekben

Ez a lépés bemutatja, hogyan kérdezhet le egy indexet a Search Documents API használatával.

A keresés $urlssorán mindenképpen használjon egyetlen idézőjelet. A lekérdezési sztringek karaktereket tartalmaznak $ , és kihagyhatja, hogy ki kell őket lépnie, ha a teljes sztring egyetlen idézőjelek közé van zárva.

  1. Állítsa a végpontot a hotels-quickstart dokumentumgyűjteményre, és adjon hozzá egy search paramétert, amely egy lekérdezési sztringet ad át.

    Ez a sztring egy üres keresést (search=*) hajt végre, amely tetszőleges dokumentumokból álló üres listát (keresési pontszám = 1,0) ad vissza. Az Azure AI Search alapértelmezés szerint egyszerre 50 találatot ad vissza. Strukturáltként ez a lekérdezés egy teljes dokumentumstruktúrát és értékeket ad vissza. Hozzáadás $count=true az eredményekben szereplő összes dokumentum számának lekéréséhez.

    $url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'

  2. Futtassa a parancsot a $url szolgáltatásnak való küldéshez.

    Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

    Az eredményeknek az alábbi kimenethez hasonlóan kell kinéznie:

    {
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "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.6,
                  "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
              },
              {
                  "@search.score":  0.009068266,
                  "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\u0027s restaurant services.",
                  "Category":  "Resort and Spa",
                  "Tags":  "air conditioning bar continental breakfast",
                  "ParkingIncluded":  true,
                  "LastRenovationDate":  "2015-09-20T00:00:00Z",
                  "Rating":  4.8,
                  "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
              },
            . . .
    ]
}

Próbálkozzon néhány további lekérdezési példával, hogy jobban érezze magát a szintaxisban. Sztringkeresést, szó szerinti $filter lekérdezéseket végezhet, korlátozhatja a találatokat, hatókörbe helyezheti a keresést adott mezőkre stb.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

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.

Ha ingyenes szolgáltatást használ, ne feledje, hogy három indexre, indexelőre és adatforrásra korlátozódik. A portálon törölheti az egyes elemeket, hogy a korlát alatt maradjon.

Következő lépések

Ebben a rövid útmutatóban a PowerShell használatával végigvezette az Azure AI Searchben található tartalom létrehozására és elérésére szolgáló alapvető munkafolyamaton. A fogalmakat szem előtt tartva javasoljuk, hogy lépjen tovább a fejlettebb forgatókönyvekre, például az Azure-adatforrásokból történő indexelésre:

REST-oktatóanyag: Részben strukturált adatok (JSON-blobok) indexelése és keresése az Azure AI Searchben