Rest-API-Referenz zur Verwaltung (Azure AI Search)

  • Artikel

Die Verwaltungs-REST-APIs von Azure AI Search (früher als Azure Cognitive Search bezeichnet) bieten programmgesteuerten Zugriff auf Verwaltungsvorgänge:

  • Erstellen, Aktualisieren und Löschen eines Suchdiensts
  • Abrufen von Suchdienstinformationen
  • Erstellen, Generieren oder Abrufen api-keys (Abfrage- oder Administratorschlüssel)
  • Hinzufügen oder Entfernen von Replikaten und Partitionen (Kapazität anpassen)
  • Konfigurieren eines Suchdiensts für die Verwendung eines privaten Endpunkts
  • Aktivieren oder Deaktivieren der rollenbasierten Zugriffssteuerung in Azure

Verwenden Sie für Aufgaben auf Datenebene, z. B. das Erstellen und Abfragen eines Indexes, stattdessen die Search-Dienst-REST-APIs.

Arbeiten mit den VERWALTUNGS-REST-APIs

Um Ihren Dienst programmgesteuert vollständig zu verwalten, arbeiten Sie mit zwei APIs: die Verwaltungs-REST-API von Azure AI Search hier dokumentiert, sowie die allgemeine Azure Resource Manager REST-API.

Die Resource Manager-API wird für allgemeine Vorgänge verwendet, die nicht dienstspezifisch sind, z. B. das Abfragen von Abonnementdaten, das Auflisten von Geostandorten usw. Alle Resource Manager-API-Aufrufe werden mit Microsoft Entra ID authentifiziert. Sie benötigen eine Mitgliedschaft und eine Rollenzuweisung in einem Microsoft Entra Mandanten, um Resource Manager API-Aufrufe ausführen zu können.

Versionierte API-Dokumentation

REST-API-Dokumentationen sind jetzt versioniert. Wenn Sie eine API-Referenzseite öffnen, wählen Sie im Dropdownfilter die API-Version aus.

Screenshot der Versionsauswahl.

Berechtigungen und Zugriffssteuerung

Verwaltungsrechte werden über integrierte Rollen in Microsoft Entra ID übertragen:

  • Besitzer - oder Mitwirkendezuweisungen sind für die meisten Aufgaben erforderlich.
  • Die Leserrolle verfügt über eingeschränkten Zugriff auf Dienstinformationen (GET-Vorgänge, mit Ausnahme von API-Schlüsseln, für die Besitzer- oder Mitwirkenderberechtigungen erforderlich sind).

Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung in Azure AI Search.

Eine bewährte Methode ist das Zuweisen von Rollen zu Gruppen und nicht zu einzelnen Benutzern. Diese Zuweisungen werden von einem Azure-Abonnementbesitzer oder einem globalen Administrator verwaltet. Weitere Informationen finden Sie unter Zuweisen von Microsoft Entra-Rollen an Gruppen.

Herstellen einer Verbindung mit dem Verwaltungsendpunkt

Beginnen Sie beim Einrichten der Verbindung mit dem Resource Manager Endpunkthttps://management.azure.com, und fügen Sie dann die Abonnement-ID, den Anbieter (Microsoft.Search) und die API-Version hinzu. Vorgänge werden im Textkörper der Anforderung angegeben.

Ein vollständig angegebener Endpunkt verfügt über die folgenden Komponenten:

https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2020-08-01

Die folgenden Clients werden häufig verwendet, um die VERWALTUNGS-REST-APIs aufzurufen:

Client Anleitungen und Beispiele
Azure PowerShell mit dem Modul Az.Search Verwalten von Azure AI-Search mithilfe von Azure PowerShell
Azure-Befehlszeilenschnittstelle (CLI) Verwalten von Azure KI-Search mithilfe der Azure CLI
Visual Studio Code mit dem REST-Client Verwalten von Azure AI-Search mithilfe von REST

Sie können einen Suchdienst auch mithilfe des Azure-Portal verwalten.

Verwaltungs-APIs in anderen SDKs

Die REST-APIs sind grundlegend für Azure AI Search, und alle Änderungen am Programmiermodell werden zuerst in den REST-APIs reflektiert.

Alternativen sind die folgenden Azure SDKs, die unabhängig nach separaten Releasezeitplänen aktualisiert werden:

Weitere Informationen