Schnellstart: Herstellen einer Verbindung mit einem Foundry IQ -Dienst (Azure KI-Suche)

Hinweis

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

In dieser Schnellstartanleitung verwenden Sie die rollenbasierte Zugriffssteuerung (RBAC) und Microsoft Entra ID, um eine schlüssellose Verbindung mit Ihrem Foundry IQ (Azure KI-Suche)-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 "Connect to Foundry IQ" mithilfe von Schlüsseln.

Voraussetzungen

Konfigurieren des rollenbasierten Zugriffs

In diesem Abschnitt aktivieren Sie RBAC für Ihren Foundry IQ (Azure KI-Suche)-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 Foundry IQ mithilfe von Rollen.

So konfigurieren Sie den Zugriff:

  1. Wechseln Sie im Azure Portal zu Ihrem Foundry IQ Service.

  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 Optionen für die Zugriffssteuerung 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 Foundry IQ-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. Wechseln Sie im Azure Portal zu Ihrem Foundry IQ Service.

  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 Foundry IQ-Dienst herstellen, verwenden Sie die Azure CLI, um sich bei dem Abonnement anzumelden, 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 Foundry IQ-Dienst nicht gültig sind, führen Sie die folgenden Befehle aus, um ihre Werte zu aktualisieren. Die Abonnement-ID finden Sie auf der Seite "Foundry IQ Service Overview" 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>
    

Verbindung zu Foundry IQ

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: Agentic-Abruf.

Sie können Python Notizbücher in Visual Studio Code verwenden, um Anfragen an Ihren Foundry IQ-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 Foundry IQ-Dienst.

    import json
    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 Foundry IQ-Dienst auflisten, was auf eine erfolgreiche Verbindung hinweist.

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 Foundry IQ-Dienst muss Role-based access control 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 Foundry IQ-Dienst 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 die rollenbasierte Zugriffssteuerung (RBAC) und Microsoft Entra ID, um eine schlüssellose Verbindung mit Ihrem Foundry IQ (Azure KI-Suche)-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 Foundry IQ mithilfe von Schlüsseln.

Voraussetzungen

Konfigurieren des rollenbasierten Zugriffs

In diesem Abschnitt aktivieren Sie RBAC für Ihren Foundry IQ (Azure KI-Suche)-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 Foundry IQ mithilfe von Rollen.

So konfigurieren Sie den Zugriff:

  1. Wechseln Sie im Azure Portal zu Ihrem Foundry IQ Service.

  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 Optionen für die Zugriffssteuerung 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 Foundry IQ-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. Wechseln Sie im Azure Portal zu Ihrem Foundry IQ Service.

  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 Foundry IQ-Dienst herstellen, verwenden Sie die Azure CLI, um sich bei dem Abonnement anzumelden, 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 Foundry IQ-Dienst nicht gültig sind, führen Sie die folgenden Befehle aus, um ihre Werte zu aktualisieren. Die Abonnement-ID finden Sie auf der Seite "Foundry IQ Service Overview" 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.

Verbindung zu Foundry IQ

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: Agentic-Abruf.

Sie können die REST-Clienterweiterung in Visual Studio Code verwenden, um Anfragen an Ihren Foundry IQ-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=2026-10-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 Foundry IQ-Dienst 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 Foundry IQ-Dienst 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, in dem Ihr Foundry IQ-Dienst enthalten ist.

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