Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zu Ihrem Suchdienst.

3. Wählen Sie im linken Navigationsbereich Access Control (IAM) aus.

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

5. Wählen Sie eine entsprechende Rolle aus:

   • Besitzer (Vollzugriff auf alle Vorgänge der Datenebene und der Steuerungsebene mit Ausnahme von Abfrageberechtigungen)
   • Mitwirkender (wie der Besitzer mit Ausnahme von Berechtigungen für das Zuweisen von Rollen)
   • Leser (für Überwachung und Anzeigemetriken)

6. Wählen Sie auf der Registerkarte „Mitglieder“ die Microsoft Entra-Benutzer- oder Gruppenidentität aus.

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

Wenn Sie PowerShell zum Zuweisen von Rollen verwenden, rufen Sie New-AzRoleAssignment auf, und geben Sie den Namen des Azure-Benutzers oder der Azure-Gruppe 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>"

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zu Ihrem Suchdienst.

3. Wählen Sie im linken Navigationsbereich Access Control (IAM) aus.

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

   

5. Wählen Sie eine Rolle aus:

   • Suchdienstmitwirkender (Vorgänge bei Indizes, Indexern, Skillsets und anderen Objekten auf höchster Ebene: Erstellen, Lesen, Updaten, Löschen)
   • Suchindexdatenmitwirkender (Laden von Dokumenten und Ausführen von Indizierungsaufträgen)
   • Suchindexdatenleser (Abfragen eines Index)

   Eine weitere Kombination aus Rollen, die Vollzugriff bieten, ist Mitwirkender oder Besitzer mit Suchindexdatenleser.

6. Wählen Sie auf der Registerkarte „Mitglieder“ die Microsoft Entra-Benutzer- oder Gruppenidentität aus.

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

8. Wiederholen Sie diesen Vorgang für die anderen Rollen. Die meisten Entwickler benötigen alle drei.

Wenn Sie PowerShell zum Zuweisen von Rollen verwenden, rufen Sie New-AzRoleAssignment auf, und geben Sie den Namen des Azure-Benutzers oder der Azure-Gruppe sowie den Umfang der Zuweisung an.

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>"

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zu Ihrem Suchdienst.

3. Wählen Sie im linken Navigationsbereich Access Control (IAM) aus.

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

5. Wählen Sie die Rolle Suchindexdatenleser aus.

6. Wählen Sie auf der Registerkarte „Mitglieder“ die Microsoft Entra-Benutzer- oder Gruppenidentität aus. Wenn Sie Berechtigungen für einen anderen Dienst einrichten, verwenden Sie möglicherweise eine system- oder benutzerseitig verwaltete Identität. Wählen Sie diese Option aus, wenn es sich um eine Rollenzuweisung für eine Dienstidentität handelt.

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

Wenn Sie PowerShell zum Zuweisen von Rollen verwenden, rufen Sie New-AzRoleAssignment auf, und geben Sie den Namen des Azure-Benutzers oder der Azure-Gruppe sowie den Geltungsbereich der Zuweisung an.

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>
   

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
   

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
   

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zu Ihrem Suchdienst.

3. Wählen Sie auf der Seite „Übersicht“ die Registerkarte Indizes aus:

   • Suchdienstmitwirkende können jedes Objekt anzeigen und erstellen, aber keine Dokumente laden und keinen Index abfragen. Um Berechtigungen zu überprüfen, erstellen Sie einen Suchindex.

   • Suchindexdatenmitwirkende können Dokumente laden. Es gibt keine Option zum Laden von Dokumenten im Portal außerhalb des Assistenten zum Importieren von Daten, aber Sie können einen Indexer zurücksetzen und ausführen, um die Dokumentladeberechtigungen zu bestätigen.

   • Suchindexdatenleser können den Index abfragen. Verwenden Sie zum Überprüfen von Berechtigungen den Suchexplorer. Sie sollten Abfragen senden und Ergebnisse anzeigen, aber Indexdefinition nicht anzeigen oder erstellen können.

Für diesen Ansatz wird Visual Studio Code mit einer REST-Clienterweiterung vorausgesetzt.

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

   az login
   

2. Rufen Sie Ihre Mandanten-ID und Abonnement-ID ab. Die ID wird in einem zukünftigen Schritt als Variable verwendet.

   az account show
   

3. Rufe ein Zugriffstoken ab.

   az account get-access-token --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 nach dem Einfügen eine Anforderung, welche die angegebenen Variablen verwendet. Für die Rolle „Suchindexdatenleser“ können Sie eine Abfrage senden. Sie können jede unterstützte API-Versionverwenden.

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

Weitere Informationen zum Abrufen eines Tokens für eine bestimmte Umgebung finden Sie unter Verwalten eines Azure KI-Suche-Diensts mit REST-APIs und Microsoft Identity Platform-Authentifizierungsbibliotheken.

1. Verwenden Sie das Paket Azure.Search.Documents.

2. Verwenden Sie Azure.Identity 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
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new 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);
   

1. Verwenden Sie azure.search.documents (Azure SDK für Python).

2. Verwenden Sie Azure.Identity 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)
   

1. Verwenden Sie @azure/search-documents (Azure SDK für JavaScript), Version 11.3.

2. Verwenden Sie Azure.Identity für JavaScript für die Tokenauthentifizierung.

3. Wenn Sie React verwenden, verwenden InteractiveBrowserCredential Sie die Microsoft Entra-Authentifizierung für die Suche. Besuchen Sie Wann @azure/identity benutzen für Einzelheiten.

1. Verwenden Sie azure-search-documents (Azure SDK für Java).

2. Verwenden Sie Azure.Identity für Java für die Tokenauthentifizierung.

3. Microsoft empfiehlt DefaultAzureCredential für Apps, die in Azure ausgeführt werden.

Diese Schritte werden von Erstellen oder Aktualisieren benutzerdefinierter Azure-Rollen mithilfe des Azure-Portals. Das Klonen von einer vorhandenen Rolle wird auf einer Suchdienstseite unterstützt.

Diese Schritte erstellen eine benutzerdefinierte Rolle, die Suchabfragerechte ergänzt, um das Auflisten von Indizes nach Namen einzuschließen. In der Regel wird das Auflisten von Indizes als Administratorfunktion angesehen.

1. Navigieren Sie im Azure-Portal zu Ihrem Suchdienst.

2. Wählen Sie im linken Navigationsbereich Zugriffssteuerung (IAM) aus.

3. Wählen Sie auf der Aktionsleiste Rollen aus.

4. Klicken Sie mit der rechten Maustaste auf Suchindexdatenleser (oder eine andere Rolle), und wählen Sie Klonen aus, um den Assistenten zum Erstellen einer benutzerdefinierten Rolle zu öffnen.

5. Geben Sie auf der Registerkarte „Grundlagen“ einen Namen für die benutzerdefinierte Rolle an, z. B. „Suchindexdaten-Explorer“, und wählen Sie dann Weiter aus.

6. Wählen Sie auf der Registerkarte „Berechtigungen“ die Option Berechtigung hinzufügen aus.

7. Suchen Sie auf der Registerkarte „Berechtigungen hinzufügen“ nach der Kachel Microsoft Search, und wählen Sie sie aus.

8. Legen Sie die Berechtigungen für Ihre benutzerdefinierte Rolle fest. Oben auf der Seite unter Verwendung der Standardauswahl Aktionen:

   • Wählen Sie unter „Microsoft.Search/operations“ Lesen: Alle verfügbaren Vorgänge auflisten aus.
   • Wählen Sie unter „Microsoft.Search/searchServices/indexes“ Lesen: Index lesen aus.

9. Wechseln Sie auf derselben Seite zu Datenaktionen, und wählen Sie unter „Microsoft.Search/searchServices/indexes/documents“ Lesen: Dokumente lesen 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": []
            }
        ]
      }
    }
   

10. Wählen Sie Überprüfen + erstellen aus, um die Rolle zu erstellen. Sie können der Rolle jetzt Benutzer und Gruppen zuweisen.

Das PowerShell-Beispiel zeigt die JSON-Syntax zum Erstellen einer benutzerdefinierten Rolle, die ein Klon von Suchindexdatenleser 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. In diesem Beispiel benötigen Sie Folgendes:

   "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}"
  ]
}

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

2. Wie Sie dabei vorgehen, erfahren Sie unter Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure über die 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. Wie Sie dabei vorgehen, erfahren Sie unter Erstellen oder Aktualisieren von benutzerdefinierten Rollen in Azure mithilfe der Azure-Befehlszeilenschnittstelle.

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