Quickstart: Een zoekindex maken in PowerShell met behulp van REST API's

Artikel
03/25/2024

In deze quickstart van Azure AI Search leert u hoe u een zoekindex maakt, laadt en query's uitvoert met behulp van PowerShell en de REST API's van Azure AI Search. In dit artikel wordt uitgelegd hoe u PowerShell-opdrachten interactief uitvoert. U kunt ook een PowerShell-script downloaden en uitvoeren waarmee dezelfde bewerkingen worden uitgevoerd.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Voor deze quickstart zijn de volgende services en hulpprogramma's vereist:

PowerShell 7.3 of hoger met invoke-RestMethod voor opeenvolgende en interactieve stappen.
Maak een Azure AI-Search-service of zoek een bestaande service onder uw huidige abonnement. U kunt een gratis service voor deze quickstart gebruiken.

Een zoekservicesleutel en -URL kopiëren

In deze quickstart bevatten REST-aanroepen de service-URL en een toegangssleutel voor elke aanvraag. Er wordt een zoekservice gemaakt met beide, dus als u Azure AI Search aan uw abonnement hebt toegevoegd, volgt u deze stappen om de benodigde informatie op te halen.

Meld u aan bij het Azure-portaal. Haal de URL op de overzichtspagina van de zoekservice op. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Selecteer Instellingen> Sleutels en haal vervolgens een beheerderssleutel op voor volledige rechten op de service. Er zijn twee uitwisselbare beheersleutels beschikbaar voor bedrijfscontinuïteit als u er een wilt overdraaien. U kunt de primaire of secundaire sleutel gebruiken op aanvragen voor het toevoegen, wijzigen en verwijderen van objecten.

Voor alle aanvragen is een API-sleutel vereist voor elke aanvraag die naar uw service wordt verzonden. Als u een geldige sleutel hebt, wordt er per aanvraag een vertrouwensrelatie tot stand brengt tussen de toepassing die de aanvraag verzendt en de service waarmee deze wordt verwerkt.

Verbinding maken naar Azure AI Search

Maak in PowerShell een $headers object om het inhoudstype en de API-sleutel op te slaan. Vervang de api-sleutel van de beheerder (YOUR-ADMIN-API-KEY) door een sleutel die geldig is voor uw zoekservice. U hoeft deze header slechts één keer in te stellen voor de duur van de sessie, maar u voegt deze toe aan elke aanvraag.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Maak een $url object waarmee de verzameling indexen van de service wordt opgegeven. Vervang de servicenaam (YOUR-SEARCH-SERVICE-NAME) door een geldige zoekservice.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Voer Invoke-RestMethod deze opdracht uit om een GET-aanvraag naar de service te verzenden en de verbinding te verifiëren. Voeg ConvertTo-Json toe zodat u de antwoorden kunt bekijken die vanuit de service zijn verzonden.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Als de service leeg is en geen indexen bevat, dan lijken de resultaten op het volgende voorbeeld. Anders ziet u een JSON-weergave van indexdefinities.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Een index maken

Tenzij u de portal gebruikt, moet er een index aanwezig zijn in de service voordat u gegevens kunt laden. In deze stap wordt de index gedefinieerd en gepusht naar de service. De API REST API index maken wordt gebruikt voor deze stap.

De vereiste elementen van een index zijn een naam en een verzameling velden. Met de verzameling velden wordt de structuur van een document gedefinieerd. Elk veld heeft een naam, type en kenmerken die bepalen hoe het wordt gebruikt (bijvoorbeeld of het doorzoekbaar is voor volledige tekst, filterbaar of ophaalbaar is in zoekresultaten). In een index moet een van de velden van het type Edm.String worden ingesteld als de sleutel voor de documentidentiteit.

Deze index heeft de naam hotels-quickstart en bevat de velddefinities die u in de volgende code ziet. Het is een subset van een grotere Hotels-index die wordt gebruikt in andere walkthrough-artikelen. De velddefinities worden in deze quickstart ingekort voor beknoptheid.

Plak dit voorbeeld in PowerShell om een $body object te maken dat het indexschema bevat.

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

Stel de URI in op de verzameling indexen in uw service en de hotels-quickstart index.

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

Voer de opdracht uit met $url, $headersen $body maak de index op de service.

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

De resultaten moeten er ongeveer uitzien als in dit voorbeeld, waarin alleen de eerste twee velden voor beknoptheid worden weergegeven:

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

Tip

Voor verificatie kunt u ook de lijst indexen in de portal controleren.

Documenten laden

Voor het pushen van documenten gebruikt u een HTTP POST-aanvraag in het URL-eindpunt van uw index. De REST API voor deze taak is Documenten toevoegen, bijwerken of verwijderen.

Plak dit voorbeeld in PowerShell om een $body object te maken dat de documenten bevat die u wilt uploaden.

Deze aanvraag bevat twee volledige records en één gedeeltelijke record. De gedeeltelijke record laat zien dat u onvolledige documenten kunt uploaden. De parameter @search.action geeft aan hoe indexering verloopt. Geldige waarden zijn onder andere upload, merge, mergeOrUploaden delete. Het mergeOrUpload gedrag maakt een nieuw document voor hotelId = 3 of werkt de inhoud bij als deze al bestaat.

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

Stel het eindpunt in op de hotels-quickstart docs-verzameling en neem de indexbewerking (indexes/hotels-quickstart/docs/index) op.
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Voer de opdracht uit met $url, $headersen $body om documenten in de hotels-quickstart index te laden.

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

De resultaten moeten er ongeveer uitzien als in het volgende voorbeeld. Normaal gezien ziet u een statuscode 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
                }
            ]
}

Een index doorzoeken

In deze stap ziet u hoe u een query uitvoert op een index met behulp van de API Documenten zoeken.

Zorg ervoor dat u enkele aanhalingstekens gebruikt bij het zoeken $urls. Queryreeksen bevatten $ tekens en u kunt deze weglaten als de hele tekenreeks tussen enkele aanhalingstekens staat.

Stel het eindpunt in op de hotels-quickstart docs-verzameling en voeg een search parameter toe om een querytekenreeks door te geven.

Deze tekenreeks voert een lege zoekopdracht uit (search=*), retourneert een ongerankeerde lijst (zoekscore = 1,0) van willekeurige documenten. Azure AI Search retourneert standaard 50 overeenkomsten tegelijk. Volgens de structuur worden met deze query een gehele documentstructuur en waarden geretourneerd. Voeg toe $count=true om het aantal documenten in de resultaten op te halen.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Voer de opdracht uit om de $url service te verzenden.

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

De resultaten moeten er ongeveer uitzien als in de volgende uitvoer:

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

Probeer een paar andere queryvoorbeelden uit om een idee te krijgen van de syntaxis. U kunt een tekenreeks zoeken, exacte $filter query's uitvoeren, de resultatenset beperken, de zoekopdracht beperken tot specifieke velden en meer.

# 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'

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in de portal met behulp van de koppeling Alle resources of resourcegroepen in het meest linkse deelvenster.

Als u een gratis service gebruikt, moet u er rekening mee houden dat u beperkt bent tot drie indexen, indexeerfuncties en gegevensbronnen. U kunt afzonderlijke items in de portal verwijderen om onder de limiet te blijven.

Volgende stappen

In deze quickstart hebt u PowerShell gebruikt om de basiswerkstroom te doorlopen voor het maken en openen van inhoud in Azure AI Search. Met de concepten in gedachten raden we u aan verder te gaan met geavanceerdere scenario's, zoals indexeren vanuit Azure-gegevensbronnen:

REST-zelfstudie: Semi-gestructureerde gegevens (JSON-blobs) indexeren en doorzoeken in Azure AI Search