Referenz zur REST-API für Azure AI Search

  • Artikel

Azure AI Search (früher als Azure Cognitive Searchbezeichnet) ist ein vollständig verwalteter Cloudsuchdienst, der informationen über benutzereigene Inhalte abruft.

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 Verwaltungs-REST-APIbehandelt.

Versionsierte API-Dokumente

REST-API-Dokumente sind jetzt versionsiert. Wenn Sie eine API-Referenzseite öffnen, wird oberhalb des Inhaltsverzeichnisses eine Versionsauswahl angezeigt. Stellen Sie sicher, dass sich der API-Verweis aus dem Ordner Reference > Data Plane befindet.

Screenshot der Versionsauswahl.

Schlüsselkonzepte

Azure AI Search verfügt über die Konzepte Suchdienste, Indizes, Dokumente, Indexer, Datenquellen, Skillsetsund 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 KI-Anreicherung und integrierte Vektorisierung zur Indizierungspipeline 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 eine type. Sie können die von Microsoft bereitgestellten Verbindungen für Azure oder Partnerconnectors verwenden. Die vollständige Liste finden Sie im Katalog Datenquellen.
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 /indexes/[index name]/docs für einen bestimmten Indexnamen enthalten.
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 werden searchable 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 integrierten 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.

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

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

    Rolle Zugang
    Suchdienstmitwirkender Zugriff auf Objekte, aber keinen Zugriff auf Indexinhalte. Diese Rolle erstellt einen Suchindex und andere Objekte auf oberster Ebene, kann jedoch keinen Suchindex abfragen oder Dokumente in einem Suchindex hinzufügen, entfernen oder aktualisieren. Diese Rolle richtet sich an Entwickler, die Objektdefinitionen erstellen, aktualisieren und löschen. Es ist auch für Administratoren vorgesehen, die Objekte verwalten müssen, aber ohne die Möglichkeit zum Anzeigen oder Zugreifen auf Objektdaten.
    Suchdatenindexmitwirkender Lese-/Schreibzugriff auf Indexinhalte. Diese Rolle richtet sich an Entwickler oder Indexbesitzer, die die Dokumentensammlung eines Indexes importieren, aktualisieren oder abfragen müssen.
    Suchdatenindexleser Lesezugriff auf Indexinhalte. Diese Rolle richtet sich an Apps und Benutzer, die Abfragen ausführen.

Wenn Sie Rollen für die Verbindung verwenden, stellt Ihre Client-App ein Bearertoken im Autorisierungsheader dar. 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. 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 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-versionenthalten. Der Wert muss auf eine unterstützte Version festgelegt werden, die wie in diesem Beispiel dargestellt ist: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-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 die Standardeinstellung als application/jsonangenommen.

Siehe auch