Schnellstart: Stichwortsuche mit REST

Artikel
11/29/2024

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. Anweisungen 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.

Abrufen eines Suchdienstendpunkts

Den Suchdienstendpunkt finden Sie im Azure-Portal.

Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Sie finden die URL auf der Startseite Übersicht. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.

Sie fügen diesen Endpunkt in einem späteren Schritt in die Datei .rest oder .http ein.

Konfigurieren des Zugriffs

Anforderungen an den Suchendpunkt müssen authentifiziert und autorisiert werden. Sie können für diese Aufgabe API-Schlüssel oder Rollen verwenden. Schlüssel sind für ein Einstieg einfacher, Rollen sind jedoch sicherer.

Bei einer rollenbasierten Verbindung können Sie die folgenden Anweisungen verwenden, um eine Verbindung mit Azure KI-Suche unter Ihrer Identität herzustellen, aber nicht unter der Identität einer Client-App.

Option 1: Verwenden von Schlüsseln

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. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe der Schlüsselauthentifizierung.

Sie fügen diesen Schlüssel in einem späteren Schritt in die Datei .rest oder .http ein.

Option 2: Verwenden von Rollen

Stellen Sie sicher, dass Ihr Suchdienst für den rollenbasierten Zugriff konfiguriert ist. Sie benötigen vorkonfigurierte Rollenzuweisungen für den Entwicklerzugriff. Ihre Rollenzuweisungen müssen die Berechtigungen zum Erstellen, Laden und Abfragen eines Suchindex gewähren.

Rufen Sie in diesem Abschnitt das Token Ihrer persönlichen Identität entweder über die Azure-Befehlszeilenschnittstelle, Azure PowerShell oder das Azure-Portal ab.

Melden Sie sich bei der Azure-Befehlszeilenschnittstelle an.
```
az login
```

Rufen Sie das Token Ihrer persönlichen Identität ab.

az account get-access-token --scope https://search.azure.com/.default

Sie fügen das Token Ihrer persönlichen Identität in einem späteren Schritt in die Datei .rest oder .http ein.

Hinweis

In diesem Abschnitt wird davon ausgegangen, dass Sie einen lokalen Client verwenden, der in Ihrem Namen eine Verbindung mit Azure KI-Suche herstellt. Ein alternativer Ansatz besteht darin, ein Token für die Client-App abzurufen. Dies ist aber nur möglich, wenn Ihre Anwendung ist bei Microsoft Entra ID registriert ist.

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 .rest oder .http.

Fügen Sie das folgende Beispiel ein, wenn Sie API-Schlüssel verwenden. Ersetzen Sie die Textplatzhalter @baseUrl und @apiKey durch die Werte, die Sie zuvor kopiert haben (ohne Anführungszeichen).

@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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

Oder fügen Sie dieses Beispiel ein, wenn Sie Rollen verwenden. Ersetzen Sie die Textplatzhalter @baseUrl und @token durch die Werte, die Sie zuvor kopiert haben (ohne Anführungszeichen).

@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

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 OK lautet, können Sie die nächsten Schritte ausführen.

Wenn WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation." ausgegeben wird, entfernen Sie die Anführungszeichen um das Token, speichern Sie die Datei, und wiederholen Sie die Anforderung.

Die wichtigsten Punkte:
- Parameter werden mit dem Präfix @ angegeben.
- ### kennzeichnet einen REST-Aufruf. Die nächste Zeile enthält die Anforderung, die HTTP/1.1 enthalten muss.
- Oberhalb der Anforderung sollte Send request angezeigt werden.

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-quickstart für Ihren Suchdienst zu erstellen.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "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 Created angezeigt 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 zwischen api-key und 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

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

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/index eingeschlossen 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 Parameter searchFields, mit dem die Textsuche auf bestimmte Felder eingeschränkt wird.

### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "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 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.",
      "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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

Ü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 Azure-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=2024-07-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.

Schnellstart: Vektorsuche mit REST-APIs

Freigeben über