Freigeben über

Schnellstart: Herstellen einer Verbindung mit einem Suchdienst

In dieser Schnellstartanleitung verwenden Sie rollenbasierte Zugriffssteuerung (RBAC) und Microsoft Entra ID, um eine schlüssellose Verbindung mit Ihrem Azure AI Search-Dienst herzustellen. Anschließend verwenden Sie Python in Visual Studio Code, um mit Ihrem Dienst zu interagieren.

Schlüssellose Verbindungen bieten erweiterte Sicherheit durch präzise Berechtigungen und identitätsbasierte Authentifizierung. Wir empfehlen keine hartcodierten API-Schlüssel, aber wenn Sie sie bevorzugen, lesen Sie "Herstellen einer Verbindung mit Azure AI Search mithilfe von Schlüsseln".

Voraussetzungen

Konfigurieren des rollenbasierten Zugriffs

In diesem Abschnitt aktivieren Sie RBAC für Ihren Azure AI Search-Dienst und weisen die erforderlichen Rollen zum Erstellen, Laden und Abfragen von Suchobjekten zu. Weitere Informationen zu diesen Schritten finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe von Rollen.

So konfigurieren Sie den Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich "Einstellungsschlüssel" >aus.

  3. Wählen Sie die rollenbasierte Zugriffssteuerung oder beides aus, wenn Sie Zeit benötigen, um Clients auf RBAC umzusteigen.

    Screenshot der Zugriffssteuerungsoptionen im Azure-Portal.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

    Screenshot des Dropdownmenüs zum Hinzufügen einer Rollenzuweisung im Azure-Portal.

  6. Weisen Sie Ihrer Benutzerkonten- oder verwalteten Identität die Rolle "Mitwirkender des Suchdiensts " zu.

  7. Wiederholen Sie die Rollenzuweisung für den Suchindexdatenmitwirkenden.

Abrufen von Dienstinformationen

In diesem Abschnitt rufen Sie die Abonnement-ID und den Endpunkt Ihres Azure AI Search-Diensts ab. Wenn Sie nur über ein Abonnement verfügen, überspringen Sie die Abonnement-ID, und rufen Sie nur den Endpunkt ab. Sie verwenden diese Werte in den verbleibenden Abschnitten dieser Schnellstartanleitung.

So rufen Sie Ihre Dienstinformationen ab

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

  3. Notieren Sie sich die Abonnement-ID und den Endpunkt.

    Screenshot der Abonnement-ID und des Endpunkts im Azure-Portal.

Anmelden bei Azure

Bevor Sie eine Verbindung mit Ihrem Azure AI Search-Dienst herstellen, melden Sie sich mit der Azure CLI beim Abonnement an, das Ihren Dienst enthält. In diesem Schritt wird Ihre Microsoft Entra-Identität eingerichtet, die DefaultAzureCredential zum Authentifizieren von Anforderungen im nächsten Abschnitt verwendet.

So melden Sie sich an

  1. Öffnen Sie auf Ihrem lokalen System ein Befehlszeilentool.

  2. Überprüfen Sie das aktive Abonnement und den Mandanten in Ihrer lokalen Umgebung.

    az account show

  3. Wenn das aktive Abonnement und der Mandant für Ihren Suchdienst nicht gültig sind, führen Sie die folgenden Befehle aus, um ihre Werte zu aktualisieren. Die Abonnement-ID finden Sie auf der Seite "Übersicht" des Suchdiensts im Azure-Portal. Um die Mandanten-ID zu finden, wählen Sie den Namen Ihres Abonnements auf der Seite Übersicht aus, und suchen Sie dann den Wert der übergeordneten Managementgruppe.

     az account set --subscription <your-subscription-id>

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

Hinweis

In diesem Abschnitt wird das grundlegende Python-Muster für schlüssellose Verbindungen veranschaulicht. Umfassende Anleitungen finden Sie in einem bestimmten Schnellstart oder Tutorial, z. B. Schnellstart: Verwenden des agentischen Abrufs in Azure AI Search.

Sie können Python-Notizbücher in Visual Studio Code verwenden, um Anforderungen an Ihren Azure AI Search-Dienst zu senden. Verwenden Sie für die Anforderungsauthentifizierung die DefaultAzureCredential Klasse aus der Azure Identity-Bibliothek.

So stellen Sie eine Verbindung mit Python her:

  1. Öffnen Sie visual Studio Code auf Ihrem lokalen System.

  2. Erstellen Sie die Datei .ipynb.

  3. Erstellen Sie eine Codezelle, um die azure-identity Und azure-search-documents Bibliotheken zu installieren.

    pip install azure-identity azure-search-documents

  4. Erstellen Sie eine weitere Codezelle zum Authentifizieren und Herstellen einer Verbindung mit Ihrem Suchdienst.

    from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
credential = DefaultAzureCredential()
client = SearchIndexClient(endpoint = service_endpoint, credential = credential)

# List existing indexes
indexes = client.list_indexes()

for index in indexes:
   index_dict = index.as_dict()
   print(json.dumps(index_dict, indent = 2))

  5. Legen Sie service_endpoint diesen Wert fest, den Sie in "Dienstinformationen abrufen" erhalten haben.

  6. Wählen Sie "Alle ausführen" aus, um beide Codezellen auszuführen.

    Die Ausgabe sollte die vorhandenen Indizes (falls vorhanden) in Ihrem Suchdienst auflisten, die eine erfolgreiche Verbindung angeben.

Beheben von 401-Fehlern

Wenn ein 401-Fehler auftritt, führen Sie die folgenden Schritte zur Problembehandlung aus:

  • Überprüfen Sie den rollenbasierten Zugriff. Ihr Suchdienst muss über eine rollenbasierte Zugriffssteuerung oder beides verfügen. Richtlinien auf Abonnement- oder Ressourcengruppenebene können Ihre Rollenzuweisungen außer Kraft setzen.

  • Besuchen Sie die Azure-Anmeldeseite erneut. Sie müssen sich bei dem Abonnement anmelden, das Ihren Suchdienst enthält.

  • Stellen Sie sicher, dass Ihre Endpunktvariable von Anführungszeichen umgeben ist.

  • Wenn alles andere fehlschlägt, starten Sie Ihr Gerät neu, um zwischengespeicherte Token zu entfernen, und wiederholen Sie dann die Schritte in dieser Schnellstartanleitung, beginnend mit der Anmeldung bei Azure.

In dieser Schnellstartanleitung verwenden Sie rollenbasierte Zugriffssteuerung (RBAC) und Microsoft Entra ID, um eine schlüssellose Verbindung mit Ihrem Azure AI Search-Dienst herzustellen. Anschließend verwenden Sie REST in Visual Studio Code, um mit Ihrem Dienst zu interagieren.

Schlüssellose Verbindungen bieten erweiterte Sicherheit durch präzise Berechtigungen und identitätsbasierte Authentifizierung. Wir empfehlen keine hartcodierten API-Schlüssel, aber wenn Sie sie bevorzugen, lesen Sie "Herstellen einer Verbindung mit Azure AI Search mithilfe von Schlüsseln".

Voraussetzungen

Konfigurieren des rollenbasierten Zugriffs

In diesem Abschnitt aktivieren Sie RBAC für Ihren Azure AI Search-Dienst und weisen die erforderlichen Rollen zum Erstellen, Laden und Abfragen von Suchobjekten zu. Weitere Informationen zu diesen Schritten finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe von Rollen.

So konfigurieren Sie den Zugriff:

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich "Einstellungsschlüssel" >aus.

  3. Wählen Sie die rollenbasierte Zugriffssteuerung oder beides aus, wenn Sie Zeit benötigen, um Clients auf RBAC umzusteigen.

    Screenshot der Zugriffssteuerungsoptionen im Azure-Portal.

  4. Wählen Sie im linken Bereich access control (IAM) aus.

  5. Wählen Sie Hinzufügen>Rollenzuweisung hinzufügen.

    Screenshot des Dropdownmenüs zum Hinzufügen einer Rollenzuweisung im Azure-Portal.

  6. Weisen Sie Ihrer Benutzerkonten- oder verwalteten Identität die Rolle "Mitwirkender des Suchdiensts " zu.

  7. Wiederholen Sie die Rollenzuweisung für den Suchindexdatenmitwirkenden.

Abrufen von Dienstinformationen

In diesem Abschnitt rufen Sie die Abonnement-ID und den Endpunkt Ihres Azure AI Search-Diensts ab. Wenn Sie nur über ein Abonnement verfügen, überspringen Sie die Abonnement-ID, und rufen Sie nur den Endpunkt ab. Sie verwenden diese Werte in den verbleibenden Abschnitten dieser Schnellstartanleitung.

So rufen Sie Ihre Dienstinformationen ab

  1. Melden Sie sich beim Azure-Portal an, und wählen Sie Ihren Suchdienst aus.

  2. Wählen Sie im linken Bereich die Option "Übersicht" aus.

  3. Notieren Sie sich die Abonnement-ID und den Endpunkt.

    Screenshot der Abonnement-ID und des Endpunkts im Azure-Portal.

Anmelden bei Azure

Bevor Sie eine Verbindung mit Ihrem Azure AI Search-Dienst herstellen, melden Sie sich mit der Azure CLI beim Abonnement an, das Ihren Dienst enthält.

So melden Sie sich an

  1. Öffnen Sie auf Ihrem lokalen System ein Befehlszeilentool.

  2. Überprüfen Sie das aktive Abonnement und den Mandanten in Ihrer lokalen Umgebung.

    az account show

  3. Wenn das aktive Abonnement und der Mandant für Ihren Suchdienst nicht gültig sind, führen Sie die folgenden Befehle aus, um ihre Werte zu aktualisieren. Die Abonnement-ID finden Sie auf der Seite "Übersicht" des Suchdiensts im Azure-Portal. Um die Mandanten-ID zu finden, wählen Sie den Namen Ihres Abonnements auf der Seite Übersicht aus, und suchen Sie dann den Wert der übergeordneten Managementgruppe.

     az account set --subscription <your-subscription-id>

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

Abrufen von Token

REST-API-Aufrufe erfordern die Einbindung eines Microsoft Entra-ID-Tokens. Sie verwenden dieses Token zum Authentifizieren von Anforderungen im nächsten Abschnitt.

So rufen Sie Ihr Token ab

  1. Generieren Sie mit demselben Befehlszeilentool ein Zugriffstoken.

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

  2. Notieren Sie sich die Tokenausgabe.

Hinweis

In diesem Abschnitt wird das grundlegende REST-Muster für schlüssellose Verbindungen veranschaulicht. Umfassende Anleitungen finden Sie in einem bestimmten Schnellstart oder Tutorial, z. B. Schnellstart: Verwenden des agentischen Abrufs in Azure AI Search.

Sie können die REST-Clienterweiterung in Visual Studio Code verwenden, um Anforderungen an Ihren Azure AI Search-Dienst zu senden. Fügen Sie für die Anforderungsauthentifizierung einen Authorization Header mit dem Microsoft Entra ID-Token ein, das Sie zuvor generiert haben.

So stellen Sie eine Verbindung mit REST her:

  1. Öffnen Sie visual Studio Code auf Ihrem lokalen System.

  2. Erstellen Sie eine .rest-Datei oder eine .http-Datei.

  3. Fügen Sie die folgenden Variablen und die Anforderung in die Datei ein.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

### List existing indexes
GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Legen Sie @baseUrl diesen Wert fest, den Sie in "Dienstinformationen abrufen" erhalten haben.

  5. Setzen Sie @token auf den im Token abrufen erhaltenen Wert.

  6. Wählen Sie unter ### List existing indexes" "Anfrage senden" aus.

    Sie sollten eine HTTP/1.1 200 OK Antwort erhalten, die eine erfolgreiche Verbindung mit Ihrem Suchdienst angibt.

Beheben von 401-Fehlern

Wenn ein 401-Fehler auftritt, führen Sie die folgenden Schritte zur Problembehandlung aus:

  • Überprüfen Sie den rollenbasierten Zugriff. Ihr Suchdienst muss über eine rollenbasierte Zugriffssteuerung oder beides verfügen. Richtlinien auf Abonnement- oder Ressourcengruppenebene können Ihre Rollenzuweisungen außer Kraft setzen.

  • Besuchen Sie die Azure-Anmeldeseite erneut. Sie müssen sich bei dem Abonnement anmelden, das Ihren Suchdienst enthält.

  • Stellen Sie sicher, dass Ihre Endpunkt- und Tokenvariablen keine umgebenden Anführungszeichen oder zusätzliche Leerzeichen aufweisen.

  • Stellen Sie sicher, dass Ihr Token nicht über das @ Symbol im Anforderungsheader verfügt. Wenn die Variable beispielsweise lautet @token, sollte {{token}}der Verweis in der Anforderung sein.

  • Wenn alles andere fehlschlägt, starten Sie Ihr Gerät neu, um zwischengespeicherte Token zu entfernen, und wiederholen Sie dann die Schritte in dieser Schnellstartanleitung, beginnend mit der Anmeldung bei Azure.

Verwandte Inhalte

  • Last updated on