Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen

1. Wechseln Sie zum Suchdienst im Azure-Portal.

2. Wählen Sie im linken Bereich Access control (IAM) aus.

3. Wählen Sie +Hinzufügen>Rollenzuweisung hinzufügen aus.

   

4. Wählen Sie eine Rolle aus: Besitzer, Mitwirkender oder Leser.

5. Wählen Sie auf der Registerkarte Members die Microsoft Entra Benutzer- oder Gruppenidentität aus. Wenn Sie Berechtigungen für einen anderen Azure Dienst einrichten, wählen Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität aus.

6. Wählen Sie auf der Registerkarte Überprüfen und zuweisen die Option Überprüfen und zuweisen aus, um die Rolle zuzuweisen.

Wenn Sie Rollen mithilfe von PowerShell zuweisen, rufen Sie New-AzRoleAssignment auf und geben Sie den Azure-Benutzer- oder -Gruppennamen sowie den Umfang der Zuweisung an.

In diesem Beispiel wird eine Rollenzuweisung für einen Suchdienst erstellt:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Referenz:New-AzRoleAssignment

1. Wechseln Sie zum Suchdienst im Azure-Portal.

2. Wählen Sie im linken Bereich Access control (IAM) aus.

3. Wählen Sie +Hinzufügen>Rollenzuweisung hinzufügen aus.

   

4. Wählen Sie "Suchdienstmitwirkender" aus.

5. Wählen Sie auf der Registerkarte Members die Microsoft Entra Benutzer- oder Gruppenidentität aus. Wenn Sie Berechtigungen für einen anderen Azure Dienst einrichten, wählen Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität aus.

6. Wählen Sie auf der Registerkarte Überprüfen und zuweisen die Option Überprüfen und zuweisen aus, um die Rolle zuzuweisen.

7. Wiederholen Sie diese Schritte, um den Suchindexdatenmitwirkenden und den Suchindexdatenleser zuzuweisen.

Weisen Sie Rollen mithilfe von PowerShell zu, indem Sie New-AzRoleAssignment aufrufen und den Azure-Benutzer- oder Gruppennamen sowie den Gültigkeitsbereich der Zuweisung angeben.

In diesem Beispiel wird eine Rollenzuweisung für einen Suchdienst erstellt:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

In diesem Beispiel wird eine Rollenzuweisung erstellt, die auf einen bestimmten Index festgelegt ist:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Referenz:New-AzRoleAssignment

1. Wechseln Sie zum Suchdienst im Azure-Portal.

2. Wählen Sie im linken Bereich Access control (IAM) aus.

3. Wählen Sie +Hinzufügen>Rollenzuweisung hinzufügen aus.

   

4. Wählen Sie die Rolle "Suchindexdatenleser" aus .

5. Wählen Sie auf der Registerkarte Members die Microsoft Entra Benutzer- oder Gruppenidentität aus. Wenn Sie Berechtigungen für einen anderen Azure Dienst einrichten, wählen Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität aus.

6. Wählen Sie auf der Registerkarte Überprüfen und zuweisen die Option Überprüfen und zuweisen aus, um die Rolle zuzuweisen.

Wenn Sie Rollen mithilfe von PowerShell zuweisen, geben Sie den Namen des Azure-Benutzers oder der Azure-Gruppe sowie den Zuweisungsbereich an, während Sie New-AzRoleAssignment aufrufen.

1. Rufen Sie Ihre Abonnement-ID, die Suchdienstressourcengruppe und den Namen des Suchdiensts ab.

2. Rufen Sie den Objektbezeichner Ihres Azure-Diensts ab, z. B. Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <your-azure-openai-resource-name>
   

   Die Ausgabe enthält eine Id Eigenschaft, die die Objekt-ID enthält, die Sie für die Rollenzuweisung benötigen.

3. Rufen Sie die Rollendefinition ab, und überprüfen Sie die Berechtigungen, um sicherzustellen, dass dies die gewünschte Rolle ist.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Erstellen Sie die Rollenzuweisung, und ersetzen Sie die Platzhalter durch gültige Werte.

   New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>
   

   Eine erfolgreiche Zuweisung liefert die Details der Rollenzuweisung einschließlich RoleAssignmentId.

5. Hier sehen Sie ein Beispiel für eine Rollenzuweisung, die auf einen bestimmten Index festgelegt ist:

   New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>/indexes/<your-index-name>
   

   Referenz:New-AzRoleAssignment

1. Wechseln Sie zum Suchdienst im Azure-Portal.

2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus, um indexbezogene Berechtigungen zu testen:

   • Suchdienstmitwirkende können Suchobjekte erstellen, ändern und löschen, aber keine Dokumente laden oder Abfragen ausführen. Um Berechtigungen zu überprüfen, erstellen Sie einen Suchindex.

   • Suchindexdatenmitwirkende können Dokumente laden. Es gibt keine Option zum Laden von Dokumenten im Azure-Portal außerhalb des Import-Daten-Assistenten, sie können jedoch reset ausführen und einen Indexer ausführen, um die Berechtigungen zum Laden von Dokumenten zu bestätigen.

   • Suchindexdatenleser können Indizes abfragen. Verwenden Sie zum Überprüfen von Berechtigungen den Suchexplorer. Sie sollten Abfragen senden und Ergebnisse anzeigen können, aber Sie sollten nicht in der Lage sein, Indexdefinitionen anzuzeigen oder Indizes zu erstellen.

Bei diesem Ansatz wird davon ausgegangen, dass Visual Studio Code mit der REST Client-Erweiterung genutzt wird.

1. Öffnen Sie eine Befehlsshell für Azure CLI, und melden Sie sich bei Ihrem Azure-Abonnement an.

   az login
   

2. Rufen Sie Ihre Mandanten-ID und Abonnement-ID ab. Verwenden Sie die ID als Variable in einem zukünftigen Schritt.

   az account show
   

3. Abrufen eines Zugriffstokens für die Azure KI-Suche-Datenebene.

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

4. Fügen Sie diese Variablen in eine neue Textdatei in Visual Studio Code ein.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Senden Sie eine Anforderung, die die von Ihnen angegebenen Variablen verwendet. Für die Rolle "Indexdatenleser suchen" können Sie eine Abfrage mit jeder unterstützten API-Version senden.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2025-09-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

   Reference:Search Documents

   Eine erfolgreiche Abfrage gibt Suchergebnisse mit übereinstimmenden Dokumenten zurück. Wenn der Index leer ist oder keine Übereinstimmungen aufweist, value enthält es ein leeres Array.

   Tipp

   Weitere Informationen zum Abrufen eines Tokens für eine bestimmte Umgebung finden Sie unter Manage an Azure KI-Suche Service with REST APIs and Microsoft Identity Platform authentication libraries.

1. Installieren Sie die erforderlichen Pakete:

   dotnet add package Azure.Search.Documents
   dotnet add package Azure.Identity
   

2. Verwenden Sie Azure. Identität für .NET für die Tokenauthentifizierung. Microsoft empfiehlt DefaultAzureCredential() für die meisten Szenarien.

3. Hier ist ein Beispiel für eine Clientverbindung mit DefaultAzureCredential():

   // Create a SearchIndexClient to send create/delete index commands
   // Requires Search Service Contributor role
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   // Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

   Reference:SearchClient, SearchIndexClient, DefaultAzureCredential

4. Hier ist ein weiteres Beispiel der Verwendung von Anmeldeinformationen für geheimen Clientschlüssel:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

5. Hier ist ein Beispiel für die Ausführung einer Abfrage:

   SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
   foreach (SearchResult<SearchDocument> result in response.GetResults())
   {
       Console.WriteLine(result.Document["HotelName"]);
   }
   

   Eine erfolgreiche Abfrage gibt Suchergebnisse zurück. Wenn keine Dokumente übereinstimmen, ist die Ergebnisauflistung leer.

1. Installieren Sie die erforderlichen Pakete:

   pip install azure-search-documents azure-identity
   

2. Verwenden Sie Azure. Identität für Python für die Tokenauthentifizierung.

3. Verwenden Sie DefaultAzureCredential wenn der Python-Client eine Anwendung ist, die serverseitig ausgeführt wird. Aktivieren Sie die interaktive Authentifizierung, wenn die App in einem Browser ausgeführt wird.

4. Hier sehen Sie ein Beispiel:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

   Reference:SearchClient, DefaultAzureCredential

1. Installieren Sie die erforderlichen Pakete:

   npm install @azure/search-documents @azure/identity
   

2. Verwenden Sie Azure. Identität für JavaScript für die Tokenauthentifizierung.

3. Wenn Sie React verwenden, verwenden Sie InteractiveBrowserCredential für die Microsoft Entra-Authentifizierung für Azure KI-Suche. Weitere Informationen finden Sie unter "Wann zu verwenden @azure/identity" .

   Reference:SearchClient, DefaultAzureCredential

1. Fügen Sie die erforderlichen Abhängigkeiten zu Ihrem pom.xml hinzu:

   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
     <version>11.7.4</version>
   </dependency>
   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
     <version>1.15.0</version>
   </dependency>
   

2. Verwenden Sie Azure. Identität für Java für die Tokenauthentifizierung.

3. Verwenden Sie DefaultAzureCredential für Apps, die auf Azure ausgeführt werden.

1. Melden Sie sich beim portal Azure an, und navigieren Sie zu Ihrem Suchdienst.

2. Wählen Sie im linken Bereich Access control (IAM) aus.

3. Suchen Sie auf der Registerkarte Rollen den Suchindexdatenleser oder eine andere Rolle, wählen Sie die Auslassungspunkte (...), und wählen Sie dann Klonen aus.

4. Geben Sie auf der Registerkarte Basics einen Namen für die benutzerdefinierte Rolle ein, z. B. "Suchindex Data Explorer", und wählen Sie dann Next aus.

5. Wählen Sie auf der Registerkarte "Berechtigungen " die Option "Berechtigungen hinzufügen" aus.

6. Wählen Sie im Bereich Berechtigungen die Kachel Microsoft Search aus.

7. Legen Sie bei oben ausgewählten Aktionen die folgenden Berechtigungen fest:

   • Wählen Sie unter Microsoft.Search/operationsRead : Alle verfügbaren Vorgänge auflisten aus.
   • Wählen Sie unter Microsoft.Search/searchServices/indexes die Option Read : Read Index aus.

8. Wechseln Sie oben zu Datenaktionen und wählen Sie unter Microsoft.Search/searchServices/indexes/documentsRead : Read Documents aus.

   Die JSON-Definition sieht wie im folgenden Beispiel aus:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

9. Wählen Sie "Hinzufügen" aus, um den Bereich zu schließen.

10. Wählen Sie Überprüfen + erstellen aus, um die Rolle zu erstellen.

    Sie können der Rolle jetzt Benutzer und Gruppen zuweisen. Weitere Informationen zu diesen Schritten finden Sie unter Create or update Azure custom roles using the Azure portal.

Das PowerShell-Beispiel zeigt die JSON-Syntax zum Erstellen einer benutzerdefinierten Rolle, die ein Klon des Suchindexdatenlesers ist, aber mit der Möglichkeit, alle Indizes nach Namen auflisten zu können.

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen. Für dieses Beispiel benötigen Sie die folgenden Berechtigungen:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Richten Sie eine PowerShell-Sitzung ein, um die benutzerdefinierte Rolle zu erstellen. Ausführliche Anweisungen finden Sie unter Azure PowerShell.

3. Geben Sie die Rollendefinition als JSON-Dokument an. Das folgende Beispiel zeigt die Syntax zum Erstellen einer benutzerdefinierten Rolle mit PowerShell.

   {
     "Name": "Search Index Data Explorer",
     "Id": "88888888-8888-8888-8888-888888888888",
     "IsCustom": true,
     "Description": "List all indexes on the service and query them.",
     "Actions": [
         "Microsoft.Search/operations/read",
         "Microsoft.Search/searchServices/read"
     ],
     "NotActions": [],
     "DataActions": [
         "Microsoft.Search/searchServices/indexes/read"
     ],
     "NotDataActions": [],
     "AssignableScopes": [
       "/subscriptions/{subscriptionId1}"
     ]
   }
   

   Hinweis

   Wenn Sie den Bereich auf Indexebene zuweisen, verwenden Sie die Datenaktion "Microsoft.Search/searchServices/indexes/documents/read".

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen.

2. Schritte finden Sie unter Create or update Azure custom roles using the REST API.

3. Kopieren oder erstellen Sie eine Rolle, oder verwenden Sie JSON, um die benutzerdefinierte Rolle anzugeben (JSON-Syntax finden Sie auf der Registerkarte PowerShell).

1. Überprüfen Sie die Liste der atomischen Berechtigungen, um zu bestimmen, welche Berechtigungen Sie benötigen.

2. Schritte finden Sie unter Create or update Azure custom roles using Azure CLI.

3. Informationen zur JSON-Syntax finden Sie auf der Registerkarte „PowerShell“.