Schnellstart: Erstellen eines Suchindex in PowerShell mithilfe von REST-APIs

  • Artikel

In diesem Schnellstart zu Azure KI-Suche erfahren Sie, wie Sie mithilfe von PowerShell und den Azure KI-Suche-REST-APIs einen Suchindex erstellen, laden und abfragen. In diesem Artikel wird erläutert, wie Sie PowerShell-Befehle interaktiv ausführen können. Alternativ können Sie ein PowerShell-Skript herunterladen und ausführen, das die gleichen Vorgänge ausführt.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Voraussetzungen

Für diesen Schnellstart sind die folgenden Dienste und Tools erforderlich:

Kopieren eines Suchdienstschlüssels und einer URL

In diesem Schnellstart beinhalten REST-Aufrufe für jede Anforderung die Dienst-URL und einen Zugriffsschlüssel. Hierfür wird jeweils ein Suchdienst erstellt. Wenn Sie Azure KI-Suche also Ihrem Abonnement hinzugefügt haben, können Sie diese Schritte ausführen, um die erforderlichen Informationen zu erhalten.

  1. Melden Sie sich beim Azure-Portal an. Rufen Sie auf der Seite Übersicht des Suchdiensts die URL ab. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.

  2. Wählen Sie Einstellungen>Schlüssel aus, und rufen Sie dann einen Administratorschlüssel für vollständige Rechte für den Dienst ab. Zwei austauschbare Administratorschlüssel werden aus Gründen der Geschäftskontinuität bereitgestellt, wenn Sie einen Rollover für einen Schlüssel durchführen müssen. Für Anforderungen zum Hinzufügen, Ändern und Löschen von Objekten können Sie den primären oder den sekundären Schlüssel verwenden.

    Screenshot: Wie ein HTTP-Endpunkt und ein Zugriffsschlüssel abgerufen werden

Für alle an Ihren Dienst gesendeten Anforderungen ist ein API-Schlüssel erforderlich. Ein gültiger Schlüssel stellt auf Anforderungsbasis eine Vertrauensstellung zwischen der Anwendung, die die Anforderung sendet, und dem Dienst, der sie verarbeitet, her.

  1. Erstellen Sie in PowerShell ein $headers-Objekt zum Speichern des Inhaltstyps und des API-Schlüssels. Ersetzen Sie den Administrator-API-Schlüssel (YOUR-ADMIN-API-KEY) durch einen für Ihren Suchdienst gültigen Schlüssel. Sie müssen diesen Header für die Dauer der Sitzung nur einmal festlegen, fügen ihn jedoch jeder Anforderung hinzu.

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

  2. Erstellen Sie ein $url-Objekt, das die Indexsammlung des Diensts angibt. Ersetzen Sie den Dienstnamen (YOUR-SEARCH-SERVICE-NAME) durch einen gültigen Suchdienst.

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

  3. Führen Sie Invoke-RestMethod aus, um eine GET-Anforderung an den Dienst zu senden und die Verbindung zu überprüfen. Fügen Sie ConvertTo-Json hinzu, damit Sie die Antworten, die vom Dienst zurückgesendet werden, verfolgen können.

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

    Wenn der Dienst leer ist und keine Indizes aufweist, ähneln die Ergebnisse dem folgenden Beispiel. Andernfalls wird eine JSON-Darstellung der Indexdefinitionen angezeigt.

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

            ]
}

Erstellen eines Index

Sofern Sie nicht das Portal verwenden, muss im Dienst ein Index vorhanden sein, bevor Sie Daten laden können. In diesem Schritt wird der Index definiert und per Pushvorgang an den Dienst übertragen. Für diesen Schritt wird Index erstellen (REST-API) verwendet.

Erforderliche Elemente eines Index sind beispielsweise ein Name und eine Feldsammlung. Mit der Feldsammlung wird die Struktur eines Dokuments definiert. Jedes Feld verfügt über Name, Typ und Attribute zur Bestimmung der Nutzung (z. B. Volltextsuche, Filterbarkeit oder Abrufbarkeit in Suchergebnissen). In einem Index muss eines der Felder vom Typ Edm.String als Schlüssel für die Dokumentidentität angegeben werden.

Dieser Index hat den Namen hotels-quickstart und weist die Felddefinitionen auf, die Sie im folgenden Code sehen. Es ist eine Teilmenge eines größeren Hotelindexes, der in anderen Artikeln mit exemplarischen Vorgehensweisen verwendet wird. Die Felddefinitionen werden aus Platzgründen in dieser Schnellstartanleitung gekürzt.

  1. Fügen Sie dieses Beispiel in PowerShell ein, um ein $body-Objekt, welches das Indexschema enthält, zu erstellen.

    $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. Legen Sie den URI auf die Indexsammlung Ihres Diensts und den Index hotels-quickstart fest.

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

  3. Führen Sie den Befehl mit $url, $headersund $body aus, um den Index für den Dienst zu erstellen.

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

    Die Ergebnisse sollten ähnlich wie in diesem Beispiel aussehen, das aus Platzgründen nur die ersten beiden Felder enthält:

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

Zur Verifizierung können Sie auch die Liste Indizes im Portal überprüfen.

Laden von Dokumenten

Senden Sie eine HTTP POST-Anforderung an den URL-Endpunkt Ihres Index, um Dokumente per Pushvorgang zu übertragen. Die REST-API für diese Aufgabe ist Index.

  1. Fügen Sie dieses Beispiel in PowerShell ein, um ein $body-Objekt mit den hochzuladenden Dokumenten zu erstellen.

    Diese Anforderung enthält zwei vollständige Datensätze und einen Teildatensatz. Der partielle Datensatz veranschaulicht, dass Sie unvollständige Dokumente hochladen können. Mit dem Parameter @search.action wird angegeben, wie das Indizieren durchgeführt wird. Gültige Werte sind u.a. upload, merge, mergeOrUploadund delete. Das Verhalten mergeOrUpload erstellt entweder ein neues Dokument für hotelId = 3 oder aktualisiert den Inhalt, wenn dieser bereits vorhanden ist.

    $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. Legen Sie den Endpunkt auf die hotels-quickstart-Dokumentensammlung fest, und schließen Sie den Indexvorgang (indexes/hotels-quickstart/docs/index) ein.

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

  3. Führen Sie den Befehl mit $url, $headers und $body aus, um Dokumente in den Index hotels-quickstart zu laden.

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

    Die Ergebnisse sollten in etwa dem folgenden Beispiel entsprechen. Der Statuscode 201 sollte angezeigt werden.

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

Durchsuchen eines Index

In diesem Schritt wird beschrieben, wie Sie einen Index mithilfe der API zum Durchsuchen von Dokumenten abfragen.

Achten Sie darauf, bei der Suche $urls einfache Anführungszeichen zu verwenden. Abfragezeichenfolgen enthalten das Zeichen $, und Sie können das Escapezeichen weglassen, wenn die gesamte Zeichenfolge in einfache Anführungszeichen eingeschlossen ist.

  1. Legen Sie den Endpunkt auf die Dokumentensammlung hotels-quickstart fest, und fügen Sie einen search-Parameter für die Übergabe in einer Abfragezeichenfolge hinzu.

    Diese Zeichenfolge führt eine leere Suche (search=*) aus und gibt eine unsortierte Liste (search score = 1.0) beliebiger Dokumente zurück. Standardmäßig gibt Azure KI Search 50 Übereinstimmungen auf einmal zurück. In einer strukturierten Ausgabe werden von der Abfrage eine vollständige Dokumentstruktur sowie Werte zurückgegeben. Fügen Sie $count=true hinzu, um eine Anzahl aller Dokumente in den Ergebnissen abzurufen.

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

  2. Führen Sie den Befehl aus, um $url an den Dienst zu senden.

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

    Die Ergebnisse sollten in etwa wie in der folgenden Ausgabe aussehen:

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

Probieren Sie einige andere Abfragebeispiele aus, um ein Gefühl für die Syntax zu bekommen. Sie können eine Zeichenfolgensuche oder wörtliche $filter-Abfragen durchführen, die Ergebnisse eingrenzen, den Bereich auf bestimmte Felder beschränken usw.

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

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können einzelne Ressourcen oder die gesamte Ressourcengruppe mit allen darin enthaltenen Ressourcen löschen.

Ressourcen können im Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich gesucht und verwaltet werden.

Denken Sie bei Verwendung eines kostenlosen Diensts an die Beschränkung auf maximal drei Indizes, Indexer und Datenquellen. Sie können einzelne Elemente über das Portal löschen, um unter dem Limit zu bleiben.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie mit PowerShell den grundlegenden Workflow für die Erstellung und den Zugriff auf Inhalte in Azure KI Search durchlaufen. Fahren Sie mit komplexeren Szenarien (etwa der Indizierung aus Azure-Datenquellen) fort, und behalten Sie dabei diese Konzepte im Hinterkopf:

REST-Tutorial: Indizieren und Durchsuchen von teilweise strukturierten Daten (JSON-Blobs) in Azure KI-Suche