Azure AI Search REST-API-Referenz

  • Artikel

Azure AI Search (früher bekannt als Azure Cognitive Search) ist ein vollständig verwalteter Cloudsuchdienst, der den Abruf von Informationen über benutzereigene Inhalte bereitstellt.

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

Auf Vorgänge auf Steuerungsebene wird über eine separate Verwaltungs-REST-API zugegriffen.

Versionierte API-Dokumentation

REST-API-Dokumentationen sind jetzt versioniert. Wenn Sie eine API-Referenzseite öffnen, wird über dem Inhaltsverzeichnis ein Versionsauswahlor angezeigt. Stellen Sie sicher, dass der API-Verweis aus dem Ordner Verweisdatenebene > stammt.

Screenshot der Versionsauswahl.

Wichtige Begriffe

Azure AI Search umfasst 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 ermöglicht die dauerhafte Speicherung von Suchdokumenten. Search Dokumente sind Ihre Daten, die als Sammlung von Feldern artikuliert, aus externen Quellen geladen und in einen Index gepusht werden, um sie durchsuchbar zu machen.
  • Ein Suchindexer fügt Automatisierung hinzu, liest Daten in nativen Formaten und serialisiert sie in JSON.
  • Ein Indexer verfügt über eine Datenquelle 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 hinzuzufügen, sodass er von einem Suchdienst indiziert werden kann.

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 Connectors von Drittanbietern über Partner verwenden. Die vollständige Liste finden Sie unter Datenquellenkatalog .
Dokumente 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 Index abzielen. Alle Vorgänge, die für die Sammlung ausgeführt werden, z. B. das Hochladen, Zusammenführen, Löschen oder Abfragen von Dokumenten, finden im Kontext eines einzelnen Indexes statt, sodass dokumentbezogene Vorgänge im URL-Format immer für einen bestimmten Indexnamen enthalten /indexes/[index name]/docs sind.
Indizes Ein Index wird in Ihrem Suchdienst gespeichert und mit JSON-Dokumenten aufgefüllt, die für den Informationsabruf indiziert und tokenisiert werden. Die Fields-Auflistung eines Indexes definiert die Struktur des Suchdokuments. Felder verfügen über einen Namen, Datentypen und Attribute, die bestimmen, wie sie verwendet werden. searchable Beispielsweise 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 Analysetools.
Indexer Indexer bieten Indizierungsautomatisierung. Ein Indexer stellt eine Verbindung mit einer Datenquelle her, liest die Daten ein und übergibt sie zur Indizierung in einen Zielsuchindex an eine Suchmaschine. 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 erfordert ein Indexer auch einen Index. Der Index gibt die Felder und Attribute der Suchdokumente an.
Qualifikationsgruppen Ein Skillset fügt externe Verarbeitungsschritte zur Indexerausführung hinzu und wird normalerweise verwendet, um KI- oder Deep Learning-Modelle hinzuzufügen, um Inhalte zu analysieren oder zu transformieren, um sie in einem Index durchsuchbar zu machen. Die Inhalte eines Skillsets sind eine oder mehrere Skills, die von Microsoft erstellt wurden , benutzerdefinierte Skills oder eine Kombination aus beidem sein können. Integrierte Fähigkeiten sind für die Bildanalyse, einschließlich OCR, und verarbeitung natürlicher Sprache vorhanden. Weitere Beispiele für integrierte Fähigkeiten sind unter anderem Entitätserkennung, Schlüsselbegriffsextraktion, Das Aufteilen von Text in logische Seiten. Ein Skillset ist ein eigenständiges Übergeordnetes Objekt, das auf einer Ebene vorhanden ist, die Indizes, Indexern und Datenquellen entspricht, aber nur innerhalb der Indexerverarbeitung betriebsbereit ist. Als allgemeines 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 die rollenbasierte Authentifizierung über 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 anforderungsbasiert eine Vertrauensstellung her zwischen der Anwendung, die die Anforderung versendet, und dem Dienst, der sie verarbeitet. Sie können einen Admin-API-Schlüssel für Lese-/Schreibvorgänge oder einen Abfrage-API-Schlüssel für den Lesezugriff auf die Dokumentensammlung eines Suchindexes verwenden.

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

    Rolle Access
    Mitwirkender von Suchdienst Zugriff auf Objekte, aber kein Zugriff auf Indexinhalte. Diese Rolle kann keinen Suchindex abfragen oder Dokumente in einem Suchindex hinzufügen, entfernen oder aktualisieren. Diese Rolle richtet sich an Administratoren, die Objekte verwalten müssen, aber ohne die Möglichkeit, Objektdaten anzuzeigen oder darauf zuzugreifen.
    Search Datenindexmitwirkender Lese-/Schreibzugriff auf Indexinhalte. Diese Rolle ist für Entwickler oder Indexbesitzer gedacht, die die Dokumentsammlung eines Index importieren, aktualisieren oder abfragen müssen.
    Search Datenindexleser Lesezugriff auf Indexinhalte. Diese Rolle ist für Apps und Benutzer gedacht, die Abfragen ausführen.

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

Sie können die schlüsselbasierte Authentifizierung oder die rollenbasierte Authentifizierung deaktivieren. Wenn Sie die rollenbasierte Authentifizierung deaktivieren, haben einige integrierte Rollen weiterhin Zugriff. Weitere Informationen 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 für Suchdaten, beispielsweise das Erstellen und Auffüllen des Indexes, das Hochladen von Dokumenten und das Ausführen von Abfragen. Beachten Sie beim Aufrufen von APIs die folgenden Punkte:

  • Anforderungen müssen über HTTPS (am Standardport 443) ausgestellt 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=2020-06-30

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

Weitere Informationen