Schnellstart: Herstellen einer Verbindung ohne Schlüssel

Artikel
12/23/2024

Konfigurieren Sie Azure KI-Suche so, dass die Microsoft Entra ID-Authentifizierung und rollenbasierte Zugriffssteuerung (RBAC) verwendet werden, damit Sie über Jupyter-Notebooks oder einen REST-Client mit Ihrem Suchdienst eine Verbindung mit Ihrem lokalen System herstellen können, ohne API-Schlüssel zu verwenden.

Wenn Sie andere Schnellstarts ausgeführt haben, die eine Verbindung mithilfe von API-Schlüsseln herstellen, wird in dieser Schnellstartanleitung gezeigt, wie Sie zur identitätsbasierten Authentifizierung wechseln, damit Sie hartcodierte Schlüssel in Ihrem Beispielcode vermeiden können.

Voraussetzungen

Ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto.
Die Azure KI-Suche, beliebige Region oder Ebene, aber Sie benötigen den Tarif „Basic“ oder höher, um eine verwaltete Identität für die Azure KI-Suche zu konfigurieren.
Ein Befehlszeilen-Tool, wie PowerShell oder Bash, und die Azure CLI.

Schritt 1: Abrufen Ihres Azure-Abonnements und Ihrer Mandanten-IDs

Sie müssen diesen Schritt ausführen, wenn Sie über mehrere Abonnements oder Mandanten verfügen.

Rufen Sie das Azure-Abonnement und den Mandanten für Ihren Suchdienst ab:
1. Melden Sie sich beim Azure-Portal an, und navigieren Sie zu Ihrem Suchdienst.
2. Beachten Sie den Abonnementnamen und die ID in Übersicht>Zusammenfassung.
3. Wählen Sie jetzt den Abonnementnamen aus, um die übergeordnete Verwaltungsgruppe (Mandanten-ID) auf der nächsten Seite anzuzeigen.
Sie wissen jetzt, zu welchem Abonnement und Mandanten Azure KI-Suche gehört. Wechseln Sie zu Ihrem lokalen Gerät und einer Eingabeaufforderung, und identifizieren Sie das aktive Azure-Abonnement und den Mandanten auf Ihrem Gerät:
```
az account show
```
Wenn sich das aktive Abonnement und der Mandant von den im vorherigen Schritt abgerufenen Informationen unterscheiden, ändern Sie die Abonnement-ID. Melden Sie sich als Nächstes mit der Mandanten-ID an, die Sie im vorherigen Schritt gefunden haben:
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

Schritt 2: Konfigurieren von Azure KI-Suche für RBAC

Melden Sie sich beim Azure-Portal an, und navigieren Sie zum Azure KI-Suchdienst.
Aktivieren Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC):
1. Gehen Sie zu Einstellungen>Schlüssel.
2. Wählen Sie Rollenbasierte Steuerung oder Beides aus, wenn Sie Zeit benötigen, um Clients auf die rollenbasierten Zugriffssteuerung umzustellen.
  
  Wenn Sie rollenbasierte Steuerung auswählen, stellen Sie sicher, dass Sie sich selbst alle Rollen zuweisen, die in der nächsten Anweisung benannt sind, oder Sie können keine Aufgaben im Azure-Portal oder über einen lokalen Client ausführen.
Weisen Sie Rollen im Azure-Portal zu:
1. Navigieren Sie zu Ihrem Suchdienst.
2. Wählen Sie im linken Navigationsbereich Access Control (IAM) aus.
3. Wählen Sie +Hinzufügen>Rollenzuweisung hinzufügen aus.
4. Wählen Sie eine Rolle (Mitwirkender von Suchdienst, Mitwirkender an Suchindexdaten, Suchindexdatenleser) aus, und weisen Sie sie Ihrer Microsoft Entra-Benutzer- oder Gruppenidentität zu.
  
  Wiederholen Sie diesen Vorgang für jede Rolle.
  
  Sie benötigen die Rolle Mitwirkender von Suchdienst sowie Mitwirkender an Suchindexdaten, um Objekte in Azure KI-Suche zu erstellen, zu laden und abzufragen. Weitere Informationen finden Sie im Artikel zum Herstellen einer Verbindung mithilfe von Rollen.

Tipp

Wenn später Fehler bei der Authentifizierung angezeigt werden, überprüfen Sie die Einstellungen in diesem Abschnitt erneut. Es können Richtlinien auf Abonnement- oder Ressourcengruppenebene vorhanden sein, die alle von Ihnen angegebenen API-Einstellungen außer Kraft setzen.

Schritt 3: Herstellen einer Verbindung aus Ihrem lokalen System

Wenn Sie sich noch nicht bei Azure angemeldet haben:

az login

Mit Python und Jupyter-Notebooks

Installieren Sie die Azure Identity- und Azure Search-Bibliotheken:
```
pip install azure-identity azure-search-documents
```

Authentifizieren Sie sich, und stellen Sie eine Verbindung zur Azure KI-Suche her:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

Verwenden eines REST-Clients

Mehrere Schnellstarts und Lernprogramme verwenden einen REST-Client, z. B. Visual Studio Code mit der REST-Erweiterung. Hier erfahren Sie, wie Sie über Visual Studio Code eine Verbindung mit der Azure KI-Suche herstellen.

Sie sollten über eine .rest- oder .http-Datei verfügen, ähnlich wie die Datei, die in Schnellstart: Vektorsuche beschrieben ist.

Erstellen Sie ein Zugriffstoken.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Legen Sie oben in der Datei Variablen fest, die für die Verbindung verwendet werden, und fügen Sie den vollständigen Suchdienstendpunkt und das Zugriffstoken ein, das Sie im vorherigen Schritt erhalten haben. Ihre Variablen sollten in etwa dem folgenden Beispiel entsprechen. Beachten Sie, dass die Werte nicht in Anführungszeichen eingeschlossen sind.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

Geben Sie das Autorisierungsbearertoken in einem REST-Aufruf an:

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

Beheben von 401-Fehlern

Überprüfen Sie das aktive Abonnement und den Mandanten (az account show), und stellen Sie sicher, dass diese für Ihren Suchdienst gültig sind.
Überprüfen Sie die Optionen Einstellungen>Schlüssel für den Suchdienst im Azure-Portal, und bestätigen Sie, dass der Dienst für Beide oder Rollenbasierte Zugriffssteuerung konfiguriert ist.
Nur für den REST-Client: Überprüfen Sie das in Ihrer Datei angegebene Token und den Endpunkt, und stellen Sie sicher, dass keine umgebenden Anführungszeichen oder zusätzlichen Leerzeichen vorhanden sind.

Wenn keine andere Maßnahme funktioniert, starten Sie das Gerät neu, um zwischengespeicherte Token zu entfernen, und wiederholen Sie dann die Schritte in diesem Abschnitt, beginnend mit az login.

Zusätzliche Konfiguration

Konfigurieren Sie eine verwaltete Identität für ausgehende Verbindungen:

Konfigurieren Sie eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität für Ihren Suchdienst.
Verwenden Sie Rollenzuweisungen, um den Zugriff auf andere Azure-Ressourcen zu autorisieren.

Konfiguration des Netzwerkzugriffs:

Legen Sie eingehende Regeln fest, um Anforderungen für die Azure KI-Suche basierend auf der IP-Adresse zu akzeptieren oder abzulehnen.

Freigeben über