Schnellstart: Textsuche mithilfe von REST-APIs
Die REST-APIs in der Azure KI-Suche bieten programmatischen Zugriff auf alle Funktionen, einschließlich der Vorschaufunktionen, und sie sind ein einfacher Weg, um zu lernen, wie die Features funktionieren. In dieser Schnellstartanleitung erfahren Sie, wie Sie die REST-APIs für die Suche aufrufen, um in der Azure KI-Suche einen Suchindex zu erstellen, zu laden und abzufragen.
Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Voraussetzungen
- Visual Studio Code mit einem REST-Client.
- Azure KI Search. Erstellen oder suchen Sie nach einer vorhandenen Ressource für Azure KI Search in Ihrem aktuellen Abonnement. Für diesen Schnellstart können Sie einen kostenlosen Dienst verwenden.
Herunterladen von Dateien
Laden Sie ein REST-Beispiel von GitHub herunter, um die Anforderungen in dieser Schnellstartanleitung zu senden. Weitere Informationen finden Sie unter Herunterladen von Dateien von GitHub.
Sie können auch eine neue Datei auf Ihrem lokalen System anlegen und die Abfragen manuell anhand der Anleitung in diesem Artikel erstellen.
Kopieren eines Suchdienstschlüssels und einer URL
Für REST-Aufrufe sind der Suchdienstendpunkt sowie ein API-Schlüssel für jede Anforderung erforderlich. Diese Werte erhalten Sie im Azure-Portal.
Melden Sie sich beim Azure-Portal an. Wechseln Sie dann zur Seite Übersicht des Suchdiensts, und kopieren Sie die URL. Ein Beispiel für einen Endpunkt ist
https://mydemo.search.windows.net.Wählen Sie Einstellungen>Schlüssel aus, und kopieren Sie dann einen Administratorschlüssel. Mit einem Administratorschlüssel können Sie Objekte hinzufügen, ändern und löschen. Es gibt zwei austauschbare Administratorschlüssel. Kopieren Sie einen der beiden Schlüssel.
Einrichten von Visual Studio Code
Wenn Sie noch keine Erfahrung mit dem REST-Client für Visual Studio Code besitzen, finden Sie in diesem Abschnitt Informationen zum Setup, mit denen Sie die Aufgaben in dieser Anleitung ausführen können.
Starten Sie Visual Studio Code, und wählen Sie die Kachel Erweiterungen aus.
Suchen Sie nach dem REST-Client, und wählen Sie Installieren aus.
Öffnen oder erstellen Sie eine neue Datei mit der Dateierweiterung
.restoder.http.Fügen Sie das folgende Beispiel ein. Ersetzen Sie die Basis-URL und den API-Schlüssel durch die Werte, die Sie zuvor kopiert haben.
@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}}Klicken Sie auf Anforderung senden. Im angrenzenden Bereich sollte eine Antwort angezeigt werden. Sind Indizes vorhanden, werden diese aufgelistet. Andernfalls ist die Liste leer. Wenn der HTTP-Code
200 OKlautet, können Sie die nächsten Schritte ausführen.
Die wichtigsten Punkte:
- Parameter werden mit dem Präfix
@angegeben. ###kennzeichnet einen REST-Aufruf. Die nächste Zeile enthält die Anforderung, dieHTTP/1.1enthalten muss.- Oberhalb der Anforderung sollte
Send requestangezeigt werden.
- Parameter werden mit dem Präfix
Erstellen eines Index
Fügen Sie Ihrer .rest-Datei eine zweite Anforderung hinzu. Mit der REST-API für die Indexerstellung werden ein Suchindex erstellt und die physischen Datenstrukturen für Ihren Suchdienst eingerichtet.
Fügen Sie das folgende Beispiel ein, um den Index
hotels-quickstartfür Ihren Suchdienst zu erstellen.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "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} ] } ] }Klicken Sie auf Anforderung senden. Es sollte die Antwort
HTTP/1.1 201 Createdangezeigt werden, deren Antworttext die JSON-Darstellung des Indexschemas enthält.Wenn ein Fehler vom Typ
Header name must be a valid HTTP token ["{"]angezeigt wird, vergewissern Sie sich, dass sich zwischenapi-keyund dem Anforderungstext eine leere Zeile befindet. Falls Sie einen „HTTP 504“-Fehler erhalten, prüfen Sie, ob die angegebene URL mit HTTPS beginnt. Wenn Sie eine "HTTP 400"- oder "HTTP 404"-Antwort erhalten, prüfen Sie den Hauptteil der Anforderung auf Fehler, die durch Kopieren und Einfügen entstanden sind. Ein „HTTP 403“-Fehler weist in der Regel auf ein Problem mit dem API-Schlüssel hin. Es handelt sich entweder um einen ungültigen Schlüssel oder um ein Syntaxproblem bei der Angabe des API-Schlüssels.Ihre Datei enthält nun mehrere Anforderungen. Beachten Sie, dass
###eine neue Anforderung einleitet und dass jede Anforderung unabhängig ausgeführt wird.
Informationen zur Indexdefinition
Innerhalb des Indexschemas definiert die Auflistung der Felder die Dokumentstruktur. Jedes Dokument, das Sie hochladen, muss über diese Felder verfügen. Jedes Feld muss einem Entitätsdatenmodell (EDM)zugewiesen werden. Zeichenfolgenfelder werden in der Volltextsuche verwendet. Sollen die numerischen Daten durchsuchbar sein, verwenden Sie den Datentyp Edm.String. Andere Datentypen, z. B. Edm.Int32, können gefiltert, sortiert, facettiert und abgerufen werden, sind jedoch nicht für die Volltextsuche geeignet.
Die Attribute der Felder bestimmen die zulässigen Aktionen. Die REST-APIs lassen standardmäßig viele Aktionen zu. Beispielsweise sind alle Zeichenfolgen standardmäßig durchsuchbar und abrufbar. Bei REST-APIs müssen Sie Attribute möglicherweise nur festlegen, wenn Sie ein Verhalten deaktivieren möchten.
{
"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}
]
}
]
}
Laden von Dokumenten
Das Erstellen und das Laden des Index erfolgt in zwei separaten Schritten. In Azure KI-Suche enthält der Index alle durchsuchbaren Daten und Abfragen, die im Suchdienst ausgeführt werden. Für REST-Aufrufe werden die Daten als JSON-Dokumente bereitgestellt. Verwenden Sie für diese Aufgabe die REST-API Dokumente – Index.
Der URI wird um die Sammlungen vom Typ docs sowie um den Vorgang index erweitert.
Fügen Sie das folgende Beispiel ein, um JSON-Dokumente in den Suchindex hochzuladen.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "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" } } ] }Klicken Sie auf Anforderung senden. Innerhalb weniger Sekunden sollte im angrenzenden Bereich eine Antwort vom Typ „HTTP 201“ angezeigt werden.
Falls Sie eine 207-Antwort erhalten, ist der Upload von mindestens einem Dokument fehlgeschlagen. Wenn Sie eine 404-Antwort erhalten, enthält entweder der Header oder der Text Ihrer Anforderung einen Syntaxfehler. Stellen Sie sicher, dass Sie den Endpunkt so geändert haben, dass
/docs/indexeingeschlossen wird.
Ausführen von Abfragen
Nachdem Sie Dokumente geladen haben, können Sie nun mithilfe der POST-REST-API für die Dokumentsuche Abfragen für diese Dokumente ausführen.
Der URI wird um einen Abfrageausdruck erweitert, der unter Verwendung des Operators /docs/search angegeben wird.
Fügen Sie das folgende Beispiel ein, um den Suchindex abzufragen. Wählen Sie anschließend Anforderung senden aus. Eine Textsuchanforderung enthält immer einen
search-Parameter. Dieses Beispiel enthält den optionalen ParametersearchFields, mit dem die Textsuche auf bestimmte Felder eingeschränkt wird.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }Überprüfen Sie die Antwort im angrenzenden Bereich. Sie sollten einen Zähler haben, der die Anzahl der im Index gefundenen Übereinstimmungen angibt, einen Suchwert, der die Relevanz angibt, und Werte für jedes in der
select-Anweisung aufgeführte Feld.{ "@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" ] } ] }
Abfragen von Indexeigenschaften
Sie können auch Statistik abrufen verwenden, um die Anzahl der Dokumente und die Indexgröße abzufragen.
Fügen Sie das folgende Beispiel ein, um den Suchindex abzufragen. Wählen Sie anschließend Anforderung senden aus.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Überprüfen Sie die Antwort. Mit diesem Vorgang erhalten Sie auf einfache Weise Details zum Indexspeicher.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
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.
Sie können auch diesen DELETE-Befehl ausprobieren:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Nächster Schritt
Nachdem Sie nun mit dem REST-Client und REST-Aufrufen für Azure KI Search vertraut sind, fahren Sie mit der nächsten Schnellstartanleitung zur Vektorunterstützung fort.