Schnellstart: Erstellen eines Azure Cognitive Search-Index mithilfe von REST-APIs
In diesem Artikel wird erläutert, wie Sie die Azure Cognitive Search-REST-APIs und einen REST-Client zum Senden und Empfangen von Anforderungen dazu verwenden, interaktiv Anforderungen zu formulieren.
In diesem Artikel kommt die Desktopanwendung Postman zum Einsatz. Sie können eine Postman-Sammlung herunterladen und importieren, wenn Sie lieber vordefinierte Anforderungen verwenden möchten.
Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Voraussetzungen
Die Postman-Desktop-App wird zum Senden von Anforderungen an Azure Cognitive Search verwendet.
Erstellen Sie einen Dienst für die kognitive Azure-Suche, oder suchen Sie nach einem vorhandenen Dienst in Ihrem aktuellen Abonnement. Für diesen Schnellstart können Sie einen kostenlosen Dienst verwenden.
Kopieren eines Schlüssels und einer URL
Für REST-Aufrufe sind die Dienst-URL und ein Zugriffsschlüssel für jede Anforderung erforderlich. Ein Suchdienst wird mit beidem erstellt. Gehen Sie daher wie folgt vor, um die erforderlichen Informationen zu erhalten, falls Sie Azure Cognitive Search Ihrem Abonnement hinzugefügt haben:
Melden Sie sich beim Azure-Portal an, und rufen Sie auf der Seite Übersicht Ihres Suchdiensts die URL ab. Ein Beispiel für einen Endpunkt ist
https://mydemo.search.windows.net.Rufen Sie unter Einstellungen>Schlüssel einen Administratorschlüssel ab, um Vollzugriff auf den Dienst zu erhalten. Es gibt zwei austauschbare Administratorschlüssel – diese wurden zum Zweck der Geschäftskontinuität bereitgestellt, falls 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.
Für alle an Ihren Dienst gesendeten Anforderungen ist ein API-Schlüssel erforderlich. Ein gültiger Schlüssel stellt anforderungsbasiert eine Vertrauensstellung her zwischen der Anwendung, die die Anforderung versendet, und dem Dienst, der sie verarbeitet.
Herstellen einer Verbindung mit Azure Cognitive Search
Verbindungsinformationen werden im URI-Endpunkt angegeben. Sammlungsvariablen repräsentieren den Namen des Suchdienstes und die API-Schlüssel. Ein typischer URI in diesem Schnellstart sieht wie folgt aus:
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30
Beachten Sie das HTTPS-Präfix, den Dienstnamen (Variable), den Namen eines Objekts (in diesem Fall der Name eines Indexes in der Sammlung „indexes“) und die API-Version. Die API-Version muss angegeben werden.
Der Anforderungsheader setzt sich aus zwei Elementen zusammen: Content-Type und api-key für die Authentifizierung bei Azure Cognitive Search. Der api-key wird als Variable angegeben und ist ebenfalls erforderlich.
Damit die Anforderungen erfolgreich sind, müssen Sie den Dienstnamen und den API-Schlüssel als Sammlungsvariablen angeben.
Öffnen Sie die Postman Desktop-App, und importieren Sie die Sammlung.
Wählen Sie das Zugriffsmenü der Sammlung aus, klicken Sie auf Bearbeiten, und geben Sie den Dienstnamen und den Schlüssel für Ihren Suchdienst ein.
1\. Erstellen eines Index
In Azure Cognitive Search wird der Index für gewöhnlich vor dem Laden von Daten erstellt. Für diese Aufgabe wird die REST-API für die Indexerstellung verwendet.
Die URL wird um den Indexnamen hotels-quickstart erweitert.
Legen Sie das Verb auf PUT fest.
Fügen Sie diese URL ein:
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30.Geben Sie die Indexdefinition (den Code zum Kopieren finden Sie weiter unten) im Text der Anforderung an.
Wählen Sie Send (Senden) aus.
Indexdefinition
Die Feldsammlung definiert die Dokumentstruktur. Jedes Dokument muss über diese Felder verfügen, und jedes Feld muss einen Datentyp besitzen. Zeichenfolgenfelder werden in der Volltextsuche verwendet. Wenn numerische Daten durchsuchbar sein müssen, müssen Sie die numerischen Daten in Zeichenfolgen umwandeln.
Die Attribute im Feld bestimmen die zulässige Aktion. Die REST-APIs ermöglichen standardmäßig viele Aktionen. Beispielsweise sind alle Zeichenfolgen durchsuchbar, abrufbar, filterbar und facettierbar. Häufig müssen Sie Attribute 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}
]
}
]
}
Wenn Sie diese Anforderung senden, sollten Sie die Antwort „HTTP 201“ erhalten, mit der angezeigt wird, dass die Erstellung des Index erfolgreich war. Sie können diese Aktion im Portal überprüfen, aber Sie sollten berücksichtigen, dass für die Portalseite bestimmte Aktualisierungsintervalle gelten. Es kann also ein oder zwei Minuten dauern, bis alles angezeigt wird.
Tipp
Falls Sie eine "HTTP 504"-Antwort erhalten, prüfen Sie, ob die 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. "HTTP 403" deutet in der Regel auf ein Problem mit dem api-key hin (entweder ein ungültiger Schlüssel oder ein Syntaxproblem bei der Angabe des API-Schlüssels).
2\. Laden von Dokumenten
Das Erstellen und das Auffüllen des Index sind separate Schritte. In Azure Cognitive Search enthält der Index alle durchsuchbaren Daten. In diesem Szenario werden die Daten als JSON-Dokumente bereitgestellt. Für diese Aufgabe wird die REST-API zum Hinzufügen, Aktualisieren oder Löschen von Dokumenten verwendet.
Die URL wird um die Sammlungen vom Typ docs sowie um den Vorgang index erweitert.
Legen Sie das Verb auf POST fest.
Fügen Sie diese URL ein:
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2020-06-30.Geben Sie die JSON-Dokumente im Text der Anforderung an (den Code zum Kopieren finden Sie nachstehend).
Wählen Sie Send (Senden) aus.
JSON-Dokumente, die in den Index geladen werden sollen
Der Anforderungstext enthält vier Dokumente, die zum Index "hotels" hinzugefügt werden sollen.
{
"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"
}
}
]
}
Innerhalb weniger Sekunden sollten Sie eine HTTP 201-Antwort in der Sitzungsliste sehen. Dies bedeutet, dass die Dokumente erfolgreich erstellt wurden.
Falls Sie eine 207-Antwort erhalten, ist der Upload von mindestens einem Dokument fehlgeschlagen. Wenn Sie eine 404-Antwort erhalten, ist entweder im Header oder im Text der Anforderung ein Syntaxfehler enthalten: Vergewissern Sie sich, dass Sie den Endpunkt so geändert haben, dass er /docs/index enthält.
Tipp
Für ausgewählte Datenquellen können Sie als Alternative auch den Indexer-Ansatz verwenden, bei dem die für die Indizierung erforderliche Menge an Code vereinfacht und reduziert wird. Weitere Informationen finden Sie unter Indexer operations (Indexer-Vorgänge).
3\. Durchsuchen eines Index
Nachdem Sie einen Index und Dokumente geladen haben, können Sie nun über die Search Documents-REST-API Abfragen ausführen.
Die URL wird um einen Abfrageausdruck erweitert, der unter Verwendung des Suchoperators angegeben wird.
Legen Sie das Verb auf GET fest.
Fügen Sie diese URL ein:
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2020-06-30.Wählen Sie Send (Senden) aus.
Diese Abfrage ist leer und gibt die Anzahl der Dokumente in den Suchergebnissen zurück. Die Anforderung und die Antwort sollten für Postman in etwa wie im folgenden Screenshot aussehen, nachdem Sie auf Senden geklickt haben. Der Statuscode sollte 200 lauten.
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 on restaurant and wifi
# Return only the HotelName, Description, and Tags fields
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=restaurant wifi&$count=true&$select=HotelName,Description,Tags&api-version=2020-06-30
# Query example 2 - Apply a filter to the index to find hotels rated 4 or highter
# Returns the HotelName and Rating. Two documents match
https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=*&$filter=Rating gt 4&$select=HotelName,Rating&api-version=2020-06-30
# Query example 3 - Take the top two results, and show only HotelName and Category in the results
https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=boutique&$top=2&$select=HotelName,Category&api-version=2020-06-30
# Query example 4 - Sort by a specific field (Address/City) in ascending order
https://{service-name}}.search.windows.net/indexes/hotels-quickstart/docs?search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating&api-version=2020-06-30
Abfragen von Indexeigenschaften
Sie können auch Statistik abrufen verwenden, um die Anzahl der Dokumente und die Indexgröße abzufragen:
https://{{service-name}}.search.windows.net/indexes/hotels-quickstart/stats?api-version=2020-06-30
Wenn Sie Ihrer URL /stats hinzufügen, werden Indexinformationen zurückgegeben. In Postman sollte Ihre Anforderung in etwa wie folgt aussehen, und die Antwort enthält dann eine Anzahl von Dokumenten und den belegten Speicher in Byte.
Beachten Sie, dass die Syntax für die API-Version hier anders ist. Verwenden Sie für diese Anforderung ?, um die API-Version anzufügen. ? trennt den URL-Pfad von der Abfragezeichenfolge; „&“ trennt die einzelnen Name-Wert-Paare in der Abfragezeichenfolge. Für diese Abfrage ist die API-Version das erste und einzige Element in der Abfragezeichenfolge.
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 entweder einzelne Ressourcen oder aber die Ressourcengruppe löschen, um den gesamten Ressourcensatz zu entfernen.
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
Nachdem Sie nun wissen, wie Sie grundlegende Aufgaben ausführen, können Sie mit weiteren REST-API-Aufrufen fortfahren, um sich komplexere Features wie Indexer anzusehen oder eine Anreicherungspipeline einzurichten, die der Indizierung Inhaltstransformationen hinzufügt. Als nächsten Schritt empfehlen wir den folgenden Link: