Dela via

Snabbstart: Skapa ett sökindex i PowerShell med hjälp av REST-API:er

  • Artikel

I den här azure AI Search-snabbstarten lär du dig hur du skapar, läser in och frågar ett sökindex med hjälp av PowerShell och REST-API:er för Azure AI Search. Den här artikeln beskriver hur du kör PowerShell-kommandon interaktivt. Du kan också ladda ned och köra ett PowerShell-skript som utför samma åtgärder.

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.

Förutsättningar

Följande tjänster och verktyg krävs för den här snabbstarten:

Kopiera en söktjänstnyckel och URL

I den här snabbstarten innehåller REST-anrop tjänst-URL:en och en åtkomstnyckel för varje begäran. En söktjänst skapas med båda, så om du har lagt till Azure AI Search i din prenumeration följer du de här stegen för att hämta nödvändig information.

  1. Logga in på Azure-portalen. Hämta URL:en på sidan Översikt för söktjänsten. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

  2. Välj Inställningar>Nycklar och hämta sedan en administratörsnyckel för fullständiga rättigheter för tjänsten. Två utbytbara administratörsnycklar tillhandahålls för affärskontinuitet om du behöver rulla över en. Du kan använda antingen den primära eller sekundära nyckeln på begäranden för att lägga till, ändra och ta bort objekt.

    Skärmbild som visar hur du hämtar en HTTP-slutpunkt och åtkomstnyckel.

Alla begäranden kräver en API-nyckel för varje begäran som skickas till din tjänst. Att ha en giltig nyckel upprättar förtroende per begäran mellan programmet som skickar begäran och den tjänst som hanterar den.

  1. I PowerShell skapar du ett $headers objekt för att lagra innehållstypen och API-nyckeln. Ersätt administratörs-API-nyckeln (YOUR-ADMIN-API-KEY) med en nyckel som är giltig för din söktjänst. Du behöver bara ange den här rubriken en gång under hela sessionen, men du lägger till den i varje begäran.

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

  2. Skapa ett $url objekt som anger tjänstens indexsamling. Ersätt tjänstnamnet (YOUR-SEARCH-SERVICE-NAME) med en giltig söktjänst.

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

  3. Kör Invoke-RestMethod för att skicka en GET-begäran till tjänsten och verifiera anslutningen. Lägg till ConvertTo-Json så att du kan visa svaren som skickas tillbaka från tjänsten.

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

    Om tjänsten är tom och inte har några index liknar resultatet följande exempel. Annars visas en JSON-representation av indexdefinitioner.

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

            ]
}

Skapa ett index

Om du inte använder portalen måste det finnas ett index i tjänsten innan du kan läsa in data. Det här steget definierar indexet och push-överför det till tjänsten. REST-API:et Create Index används för det här steget.

Obligatoriska element i ett index innehåller ett namn och en fältsamling. Fältsamlingen definierar strukturen för ett dokument. Varje fält har ett namn, en typ och attribut som avgör hur det används (till exempel om det kan sökas i fulltext, filtreras eller hämtas i sökresultat). I ett index måste ett av fälten av typen Edm.String anges som nyckel för dokumentidentitet.

Det här indexet namnges hotels-quickstart och har de fältdefinitioner som du ser i följande kod. Det är en delmängd av ett större Hotell-index som används i andra genomgångsartiklar. Fältdefinitionerna trimmas i den här snabbstarten för korthet.

  1. Klistra in det här exemplet i PowerShell för att skapa ett $body objekt som innehåller indexschemat.

    $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. Ange URI:n till indexsamlingen på din tjänst och indexet hotels-quickstart .

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

  3. Kör kommandot med $url, $headersoch $body för att skapa indexet för tjänsten.

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

    Resultaten bör se ut ungefär som i det här exemplet, som endast visar de två första fälten för korthet:

    {
    "@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":  ""
                },
                . . .
    ]
}

Dricks

För verifiering kan du också kontrollera indexlistan i portalen.

Läsa in dokument

Om du vill skicka dokument använder du en HTTP POST-begäran till indexets URL-slutpunkt. REST-API:et för den här uppgiften är Indexdokument.

  1. Klistra in det här exemplet i PowerShell för att skapa ett $body objekt som innehåller de dokument som du vill ladda upp.

    Den här begäran innehåller två fullständiga poster och en partiell post. Den partiella posten visar att du kan ladda upp ofullständiga dokument. Parametern @search.action anger hur indexering görs. Giltiga värden är upload, merge, mergeOrUploadoch delete. Beteendet mergeOrUpload skapar antingen ett nytt dokument för hotelId = 3 eller uppdaterar innehållet om det redan finns.

    $body = @"
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Stay-Kay City Hotel",
    "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": "Old Century Hotel",
    "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": "Gastronomic 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 Palace Hotel",
    "Description": "Sublime Palace 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 Palace 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. Ange slutpunkten till dokumentsamlingen hotels-quickstart och inkludera indexåtgärden (indexes/hotels-quickstart/docs/index).

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

  3. Kör kommandot med $url, $headersoch $body för att läsa in dokument i indexet hotels-quickstart .

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

    Resultaten bör se ut ungefär som i följande exempel. Du bör se statuskoden 201.

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

Sök i ett index

Det här steget visar hur du frågar efter ett index med hjälp av API:et Sökdokument.

Se till att använda enkla citattecken vid sökning $urls. Frågesträngar innehåller $ tecken, och du kan utelämna att behöva ta bort dem om hela strängen omges av enkla citattecken.

  1. Ange slutpunkten till dokumentsamlingen hotels-quickstart och lägg till en search parameter för att skicka in en frågesträng.

    Den här strängen kör en tom sökning (search=*), som returnerar en orankad lista (sökpoäng = 1,0) godtyckliga dokument. Som standard returnerar Azure AI Search 50 matchningar åt gången. Som strukturerad returnerar den här frågan en hel dokumentstruktur och värden. Lägg till $count=true för att få ett antal av alla dokument i resultatet.

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

  2. Kör kommandot för att skicka $url till tjänsten.

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

    Resultaten bör se ut ungefär som följande utdata:

    {
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "HotelId":  "2",
                  "HotelName":  "Old Century Hotel",
                  "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":  "Gastronomic 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}"
              },
            . . .
    ]
}

Prova några andra frågeexempel för att få en känsla för syntaxen. Du kan göra en strängsökning, ordagranna $filter frågor, begränsa resultatuppsättningen, begränsa sökningen till specifika fält med mera.

# 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=2024-07-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=2024-07-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=2024-07-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=2024-07-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

Rensa resurser

När du arbetar i din egen prenumeration kan det dock vara klokt att i slutet av ett projekt kontrollera om du fortfarande behöver de resurser som du skapade. Resurser som fortsätter att köras kostar pengar. Du kan ta bort enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

Du kan hitta och hantera resurser i portalen med hjälp av länken Alla resurser eller Resursgrupper i det vänstra fönstret.

Om du använder en kostnadsfri tjänst ska du komma ihåg att du är begränsad till tre index, indexerare och datakällor. Du kan ta bort enskilda objekt i portalen för att hålla dig under gränsen.

Nästa steg

I den här snabbstarten använde du PowerShell för att gå igenom det grundläggande arbetsflödet för att skapa och komma åt innehåll i Azure AI Search. Med begreppen i åtanke rekommenderar vi att du går vidare till mer avancerade scenarier, till exempel indexering från Azure-datakällor:

REST-självstudie: Indexera och söka efter halvstrukturerade data (JSON-blobar) i Azure AI Search