Freigeben über

Referenz zur REST-API für Azure AI Search

Azure AI Search (ehemals Azure Cognitive Search) ist ein vollständig verwalteter Cloudsuchdienst, der informationen zum Abrufen von Informationen über benutzereigene Inhalte bereitstellt.

Rest-APIs für Datenebene werden für Indizierungs- und Abfrageworkflows verwendet und werden in diesem Abschnitt dokumentiert.

Steuerungsebenenvorgänge für die Dienstverwaltung werden in einer separaten REST-API für die Suchverwaltung behandelt.

Versionsierte API-Dokumente

Eine Versionsauswahl wird oberhalb des Inhaltsverzeichnisses angezeigt, wenn Sie einen API-Referenzartikel auswählen. Stellen Sie sicher, dass die API aus dem Ordner "Referenzdatenebene>" stammt.

Screenshot der Versionsauswahl.

Schlüsselkonzepte

Azure AI Search verfügt über die Konzepte von Suchdiensten, Indizes, Dokumenten, Indexern, Datenquellen, Skillsets und Synonymzuordnungen.

  • Ein Suchdienst hostet Index, Indexer, Datenquellen, Skillsets und Synonymzuordnungen als Objekte der obersten Ebene.
  • Ein Suchindex bietet beständigen Speicher von Suchdokumenten. Suchdokumente sind Ihre Daten, die als Sammlung von Feldern formuliert, aus externen Quellen geladen und an einen Index verschoben werden, um sie durchsuchbar zu machen.
  • Ein Suchindexer fügt Automatisierung hinzu, liest Daten in systemeigenen Formaten und serialisiert sie in JSON.
  • Ein Indexer weist eine Datenquelle auf und zeigt auf einen Index.
  • Ein Indexer kann auch über ein Skillset verfügen, das der Indizierungspipeline KI-Anreicherung und integrierte Vektorisierung hinzufügt. Skillsets werden immer an einen Indexer angefügt. Sie rufen maschinelles Lernen auf, um Text zu extrahieren oder zu blockieren, Inhalte zu vektorisieren, Features abzuleiten oder Inhalten Struktur für eine verbesserte Indizierung durch einen Suchdienst hinzuzufügen.

Insgesamt können Sie die folgenden Objekte in einem Suchdienst erstellen:

Objekte Beschreibung
Datenquellen Eine Datenquellenverbindung, die von einem Indexer zum Abrufen und Aktualisieren von Dokumenten für die Indizierung verwendet wird. Datenquellen verfügen über ein type. Sie können die von Microsoft bereitgestellten Verbindungen für Azure oder Partnerconnectors verwenden. Die vollständige Liste finden Sie im Datenquellenkatalog .
Urkunden Konzeptionell ist ein Dokument eine Entität in Ihrem Index. Zuordnen dieses Konzepts zu vertrauteren Datenbankäquivalenten: Ein Suchindex entspricht einer Tabelle, und Dokumente entsprechen ungefähr Zeilen in einer Tabelle. Dokumente sind nur in einem Index vorhanden und werden nur über Abfragen abgerufen, die auf die Dokumentensammlung (/docs) eines Indexes abzielen. Alle Vorgänge, die für die Auflistung ausgeführt werden, z. B. Hochladen, Zusammenführen, Löschen oder Abfragen von Dokumenten, werden im Kontext eines einzelnen Indexes ausgeführt, sodass die URL-Formatdokumentvorgänge immer für einen bestimmten Indexnamen enthalten /indexes/[index name]/docs sind.
Indexe Ein Index wird in Ihrem Suchdienst gespeichert und mit JSON-Dokumenten gefüllt, die für den Informationsabruf indiziert und tokenisiert sind. Die Feldauflistung eines Indexes definiert die Struktur des Suchdokuments. Felder weisen einen Namen, Datentypen und Attribute auf, die die Verwendung bestimmen. Beispielsweise searchable werden Felder in der Volltextsuche verwendet und somit während der Indizierung tokenisiert. Ein Index definiert auch andere Konstrukte, z. B. Bewertungsprofile für die Relevanzoptimierung, Suggester, semantische Konfigurationen und benutzerdefinierte Analysegeräte.
Indexer Indexer stellen die Indizierungsautomatisierung bereit. Ein Indexer stellt eine Verbindung mit einer Datenquelle, liest die Daten und übergibt sie an eine Suchmaschine für die Indizierung in einen Zielsuchindex. Indexer lesen aus einer externen Quelle mithilfe von Verbindungsinformationen in einer Datenquelle und serialisieren die eingehenden Daten in JSON-Suchdokumente. Zusätzlich zu einer Datenquelle benötigt ein Indexer auch einen Index. Der Index gibt die Felder und Attribute der Suchdokumente an.
Skillsets Ein Skillset fügt externe Verarbeitungsschritte zur Indizierungsausführung hinzu und wird zum Anwenden von KI- oder Deep Learning-Modellen verwendet, um Inhalte für eine verbesserte Suchbarkeit in einem Index zu analysieren oder zu transformieren. Die Inhalte eines Skillsets sind eine oder mehrere Fähigkeiten, die von Microsoft, benutzerdefinierten Fähigkeiten oder einer Kombination aus beiden erstellt werden können. Integrierte Fähigkeiten für die Bildanalyse, einschließlich OCR und natürlicher Sprachverarbeitung. Weitere Beispiele für integrierte Fähigkeiten sind die Entitätserkennung, die Tastenauszugsextraktion, das Aufteilen von Text in logische Seiten, u. a. Ein Skillset ist ein eigenständiges Objekt auf hoher Ebene, das auf einer Ebene vorhanden ist, die Indizes, Indexer und Datenquellen entspricht, aber nur innerhalb der Indexerverarbeitung funktionsfähig ist. Als übergeordnetes Objekt können Sie ein Skillset einmal entwerfen und dann in mehreren Indexern darauf verweisen.
Synonymzuordnungen Eine Synonymzuordnung ist ein Objekt auf Dienstebene, das benutzerdefinierte Synonyme enthält. Dieses Objekt wird unabhängig von Suchindizes verwaltet. Nach dem Hochladen können Sie jedes durchsuchbare Feld auf die Synonymzuordnung (eins pro Feld) verweisen.

Berechtigungen und Zugriffssteuerung

Sie können die schlüsselbasierte Authentifizierung oder rollenbasierte Authentifizierung über die Microsoft Entra-ID verwenden.

  • Die schlüsselbasierte Authentifizierung basiert auf API-Schlüsseln , die für den Suchdienst generiert werden. Ein gültiger Schlüssel stellt eine Vertrauensstellung auf Anforderungsbasis zwischen der Anwendung, die die Anforderung sendet, und dem Dienst, der ihn verarbeitet, her. Sie können einen Administrator-API-Schlüssel für Lese-/Schreibvorgänge oder einen Abfrage-API-Schlüssel für den Lesezugriff auf die Dokumentensammlung eines Suchindex verwenden.

  • Für die Microsoft Entra-ID-Authentifizierung und rollenbasierte Zugriffssteuerung ist es erforderlich, dass Sie über einen etablierten Mandanten in Microsoft Entra ID verfügen, mit Sicherheitsprinzipalen und Rollenzuweisungen. Mitglieder der folgenden Rollen haben Zugriff auf datenebenen. Sie können benutzerdefinierte Rollen erstellen, wenn die integrierten Rollen nicht ausreichen.

Wenn Sie Rollen für die Verbindung verwenden, zeigt Ihre Client-App ein Bearertoken im Autorisierungsheader an. Hilfe zum Einrichten finden Sie unter Autorisieren des Zugriffs auf eine Such-App mithilfe der Microsoft Entra-ID .

Sie können die schlüsselbasierte Authentifizierung oder die rollenbasierte Authentifizierung deaktivieren. Wenn Sie die rollenbasierte Authentifizierung deaktivieren, gilt sie nur für Datenebenenvorgänge. Steuern von Ebenenvorgängen, z. B. Dienstverwaltung, verwenden immer rollenbasierte Authentifizierung. Details finden Sie unter Microsoft Entra ID-Authentifizierung und rollenbasierte Zugriffssteuerung für Azure AI Search .

Aufrufen der APIs

Die in diesem Abschnitt dokumentierten APIs bieten Zugriff auf Vorgänge in Suchdaten, z. B. Indexerstellung und -population, Dokumentupload und Abfragen. Beachten Sie beim Aufrufen von APIs die folgenden Punkte:

  • Anforderungen müssen über HTTPS (im Standardport 443) ausgegeben werden.

  • Anforderungs-URIs müssen die API-Version enthalten. Der Wert muss auf eine unterstützte Version festgelegt werden, die wie in diesem Beispiel dargestellt formatiert ist: GET https://[search service name].search.windows.net/indexes?api-version=2024-07-01

  • Anforderungsheader müssen entweder einen API-Schlüssel oder ein Bearertoken für authentifizierte Verbindungen enthalten. Optional können Sie den Accept HTTP-Header festlegen. Wenn der Inhaltstypheader nicht festgelegt ist, wird als Standardwert angenommen application/json.

Siehe auch