Se connecter à la Recherche Azure AI en utilisant des rôles

Azure fournit une authentification globale et un contrôle d’accès en fonction du rôle via l’ID Microsoft Entra pour tous les services exécutés sur la plateforme. Dans cet article, découvrez quels rôles fournissent l’accès au contenu et à l’administration de la recherche dans Azure AI Search.

Dans la recherche Azure AI, vous pouvez attribuer des rôles Azure pour :

• Administration du service
• le développement ou l’accès en écriture à un service de recherche
• l’accès en lecture seule aux demandes
• l’accès délimité à un index unique

L’accès par utilisateur aux résultats de la recherche (parfois appelé sécurité au niveau des lignes ou sécurité au niveau du document) n’est pas pris en charge avec l’attribution de rôle. En guise de solution de contournement, créez des filtres de sécurité qui ajustent les résultats par identité utilisateur, en supprimant les documents auxquels le demandeur ne doit pas avoir accès. Consultez cet exemple de conversation d’entreprise avec RAG pour une démonstration.

Les attributions de rôles sont cumulatives et généralisées pour tous les outils et bibliothèques de client. Vous pouvez attribuer des rôles à l’aide de l’une des approches prises en charge décrites dans la documentation sur le contrôle d’accès basé sur les rôles d’Azure.

L’accès en fonction du rôle est facultatif, mais recommandé. L’alternative est l’authentification par clé, qui est la valeur par défaut.

Prérequis

• Un service de recherche dans n’importe quelle région, sur n’importe quel niveau, activé pour l’accès en fonction du rôle.

• Propriétaire, Administrateur d’accès utilisateur, Administrateur de contrôle d’accès en fonction du rôle, ou rôle personnalisé avec des autorisations Microsoft.Authorization/roleAssignments/write.

Guide pratique pour attribuer des rôles dans le portail

Les étapes suivantes fonctionnent pour toutes les attributions de rôles.

1. Connectez-vous au portail Azure.

2. Accéder à votre service de recherche.

3. Activer l’accès en fonction du rôle.

4. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

5. Sélectionnez +Ajouter>Ajouter une attribution de rôle pour démarrer l’Assistant Ajouter une attribution de rôle.

   

6. Sélectionner un rôle. Vous pouvez affecter plusieurs principaux de sécurité, qu’il s’agisse d’utilisateurs ou d’identités managées, à un rôle dans un seul passage via l’Assistant, mais vous devez répéter ces étapes pour chaque rôle que vous définissez.

7. Sous l’onglet Membres, sélectionnez l’identité de l’utilisateur ou du groupe Microsoft Entra. Si vous configurez des autorisations pour un autre service Azure, sélectionnez une identité managée par l’utilisateur ou un système.

8. Dans l’onglet Passer en revue + affecter, sélectionnez Passer en revue + affecter pour affecter le rôle.

Rôles intégrés utilisés dans la recherche

Le plan de données fait référence aux opérations sur le point de terminaison du service de recherche, comme l’indexation ou les requêtes, ou toute autre opération spécifiée dans les API REST Service de recherche ou les bibliothèques clientes du kit de développement logiciel (SDK) équivalentes.

Plan de contrôle fait référence à la gestion des ressources Azure, telle que la création ou la configuration d’un service de recherche.

Les rôles suivants sont intégrés. Si ces rôles sont insuffisants, créez un rôle personnalisé.

Rôle	Plane	Description
Propriétaire	Contrôle et données	Accès complet au plan de contrôle de la ressource de recherche, y compris la possibilité d’affecter des rôles Azure. Seul le rôle Propriétaire peut activer ou désactiver les options d’authentification ou gérer des rôles pour d’autres utilisateurs. Les administrateurs d’abonnements sont membres par défaut. Sur le plan de données, ce rôle a le même accès que le rôle Contributeur de service de recherche. Il inclut l’accès à toutes les actions de plan de données, à l’exception de la possibilité d’interroger les documents d’index.
Contributeur	Contrôle et données	Même niveau d’accès au plan de contrôle que le Propriétaire, moins la possibilité d’affecter des rôles ou de modifier les options d’authentification. Sur le plan de données, ce rôle a le même accès que le rôle Contributeur de service de recherche. Il inclut l’accès à toutes les actions de plan de données, à l’exception de la possibilité d’interroger les documents d’index.
Lecteur	Contrôle et données	L’accès en lecture dans le service entier, ce qui inclut les métriques de recherche, les métriques de contenu (stockage consommé, nombre d’objets) et les définitions d’objet des ressources de plan de données (index, indexeurs, etc.). Toutefois, il ne peut pas lire les clés API ni le contenu dans les index.
Contributeur du service de recherche	Contrôle et données	Accès en lecture-écriture aux définitions d’objets (index, alias, mappages de synonymes, indexeurs, sources de données et ensembles de compétences). Ce rôle est destiné aux développeurs qui créent des objets et aux administrateurs qui gèrent un service de recherche et ses objets, mais sans accès au contenu de l’index. Utilisez ce rôle pour créer, supprimer et répertorier des index, obtenir des définitions d’index et des informations sur le service (statistiques et quotas), tester des analyseurs, créer et gérer des mappages de synonymes, des indexeurs, des sources de données et des ensembles de compétences. Consultez Microsoft.Search/searchServices/* pour obtenir la liste des autorisations.
Contributeur de données d’index de la Recherche	Données	Accès en lecture-écriture au contenu dans des index. Ce rôle est destiné aux développeurs ou aux propriétaires d’index qui ont besoin d’importer, d’actualiser ou d’interroger la collection de documents d’un index. Ce rôle ne prend pas en charge la création ou la gestion d’index. Par défaut, ce rôle est destiné à tous les index d’un service de recherche. Pour réduire l’étendue, consultez Accorder l’accès à un seul index.
Lecteur de données d’index de la Recherche	Données	Accès en lecture seule pour interroger des index de recherche. Ce rôle est destiné aux applications et utilisateurs qui exécutent des requêtes. Ce rôle ne prend pas en charge l’accès en lecture aux définitions d’objets. Par exemple, vous ne pouvez pas lire une définition d’index de recherche ou obtenir des statistiques du service de recherche. Par défaut, ce rôle est destiné à tous les index d’un service de recherche. Pour réduire l’étendue, consultez Accorder l’accès à un seul index.

Combinez ces rôles pour obtenir des autorisations suffisantes pour votre cas d’usage.

Remarque

Si vous désactivez l’accès en fonction du rôle Azure, les rôles intégrés pour le plan de contrôle (Propriétaire, Contributeur, Lecteur) continuent d’être disponibles. La désactivation de l’accès en fonction du rôle supprime uniquement les autorisations liées aux données associées à ces rôles. Si les rôles du plan de données sont désactivés, le contributeur du service de recherche équivaut au contributeur du plan de contrôle.

Résumé

autorisations	Lecteur de données d’index de la Recherche	Contributeur de données d’index de la Recherche	Contributeur du service de recherche	Propriétaire/Contributeur	Lecteur
Afficher la ressource dans le Portail Azure	❌	❌	✅	✅	✅
Afficher les propriétés des ressources, de métriques ou d’un point de terminaison	❌	❌	✅	✅	✅
Répertorier tous les objets sur la ressource	❌	❌	✅	✅	✅
Quotas d’accès et statistiques de service	❌	❌	✅	✅	❌
Lire/Interroger un index	✅	❌	❌	❌	❌
Charger l’indexation des données	❌	✅	❌	❌	❌
Créer ou modifier des index/alias	❌	❌	✅	✅	❌
Créer, modifier et exécuter des indexeurs/sources de données/ensembles de compétences	❌	❌	✅	✅	❌
Créer ou modifier des mappages de synonymes	❌	❌	✅	✅	❌
Créer ou modifier des sessions de débogage	❌	❌	✅	✅	❌
Créer ou gérer des déploiements	❌	❌	✅	✅	❌
Créer ou configurer des ressources Recherche Azure IA	❌	❌	✅	✅	❌
Voir/copier/regénérer des clés sous Clés	❌	❌	✅	✅	❌
Afficher des rôles/stratégies/définitions	❌	❌	✅	✅	❌
Définir des options d’authentification	❌	❌	✅	✅	❌
Configurer des connexions privées	❌	❌	✅	✅	❌
Configurer la sécurité réseau	❌	❌	✅	✅	❌

Les propriétaires et les contributeurs accordent les mêmes autorisations, sauf que seuls les propriétaires peuvent attribuer des rôles.

Les propriétaires et les contributeurs peuvent créer, lire, mettre à jour et supprimer des objets dans le portail Azure si les clés API sont activées. Le portail utilise des clés sur les appels internes aux API de plan de données. Lorsque vous configurez par la suite Recherche Azure AI pour qu’il utilise uniquement les « rôles », le propriétaire et le contributeur ne pourront pas gérer les objets dans le portail en utilisant uniquement ces attributions de rôles. La solution consiste à attribuer davantage de rôles, tels que Lecteur de données d’index de recherche, Contributeur de données d’index de recherche et Contributeur du service de recherche.

Attribuer des rôles

Dans cette section, attribuez des rôles pour :

• Administration du service
• le développement ou l’accès en écriture à un service de recherche
• l’accès en lecture seule aux demandes

Attribuer des rôles pour l’administration de services

En tant qu’administrateur de services, vous pouvez créer et configurer un service de recherche et effectuer toutes les opérations de plan de contrôle décrites dans l’API REST de gestion ou les bibliothèques clientes équivalentes. Si vous êtes propriétaire ou contributeur, vous pouvez également effectuer la plupart des tâches API REST de recherche de plan de données dans le portail Azure.

Rôle	id
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure portal

1. Connectez-vous au portail Azure.

2. Attribuez ces rôles :

   • Propriétaire (accès complet à toutes les opérations de plan de données et de plan de contrôle, à l’exception des autorisations de demande)
   • Contributeur (identique à Propriétaire, à l’exception des autorisations d’attribution de rôle)
   • Lecteur (acceptable pour la surveillance et la consultation des métriques)

PowerShell

Lorsque vous utilisez PowerShell pour attribuer des rôles, appelez New-AzRoleAssignment en indiquant le nom de l’utilisateur ou du groupe Azure et la portée de l’attribution.

Cet exemple crée une attribution de rôle délimitée à un service de recherche :

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

Attribuer des rôles pour le développement

Les attributions de rôle sont globales dans le service de recherche. Pour limiter les autorisations à un seul index, utilisez plutôt PowerShell ou Azure CLI pour créer un rôle personnalisé.

Tâche	Role	id
Opérations CRUD	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Charger des documents, exécuter des travaux d’indexation	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Interroger un index	Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

L’association des rôles Contributeur/Propriétaire et Lecteur de données d’index de recherche fournit elle aussi un accès complet.

Important

Si vous configurez l’accès en fonction du rôle pour un service ou un index, et que vous fournissez également une clé API sur la demande, le service de recherche utilise la clé API pour l’authentification.

Azure portal

1. Connectez-vous au portail Azure.

2. Attribuez ces rôles :

   • Contributeur de services de recherche (opérations create-read-update-delete sur les index, les indexeurs, les ensembles de compétences et les autres objets de niveau supérieur)
   • Contributeur de données d’index de recherche (charge des documents et exécute des travaux d’indexation)
   • Lecteur de données d’index de recherche (demande un index)

PowerShell

Lorsque vous utilisez PowerShell pour attribuer des rôles, appelez New-AzRoleAssignment en indiquant le nom de l’utilisateur ou du groupe Azure et la portée de l’attribution.

Cet exemple crée une attribution de rôle délimitée à un service de recherche :

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

Cet exemple crée une attribution de rôle délimitée à un index spécifique :

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

Attribuer des rôles pour les demandes en lecture seule

Utilisez le rôle Lecteur de données d’index de recherche pour les applications et les processus qui ont uniquement besoin d’un accès en lecture à un index.

Rôle	id
Search Index Data Reader avec PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

Il s’agit d’un rôle très spécifique. Il octroie un accès GET ou POST à la collection de documents d’un index de recherche pour la recherche, l’autocomplétion et les suggestions. Il ne prend pas en charge les opérations GET ou LIST sur un index ou d’autres objets de niveau supérieur, ni les statistiques de service GET.

Cette section fournit les étapes de base pour configurer l’attribution de rôle et est présentée pour des raisons d’exhaustivité. Toutefois, nous vous recommandons de consulter Utiliser la Recherche Azure AI sans clés pour obtenir des instructions complètes sur la configuration de votre application pour l’accès en fonction du rôle.

Azure portal

1. Connectez-vous au portail Azure.

2. Attribuez le rôle Lecteur de données d’index de recherche.

PowerShell

Lorsque vous utilisez PowerShell pour attribuer des rôles, appelez New-AzRoleAssignment en indiquant le nom de l'utilisateur ou du groupe Azure et la portée de l'attribution.

1. Récupérez votre ID d’abonnement, votre groupe de ressources de service de recherche et le nom du service de recherche.

2. Récupérez l’identificateur d’objet de votre service Azure, comme Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Récupérez la définition de rôle et passez en revue les autorisations pour vous assurer qu’il s’agit du rôle souhaité.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Créez l’attribution de rôle, en remplaçant les valeurs valides pour les espaces réservés.

   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. Cet exemple crée une attribution de rôle limitée à un index spécifique :

   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
   

Tester les attributions de rôles

Utilisez un client pour tester les attributions de rôles. N’oubliez pas que les rôles sont des rôles cumulatifs et hérités qui sont délimités au niveau de l’abonnement ou du groupe de ressources et ne peuvent donc pas être supprimés ni refusés au niveau de la ressource (service de recherche).

Configurez votre application pour les connexions sans clé et obtenez les attributions de rôle en place avant le test.

Azure portal

1. Connectez-vous au portail Azure.

2. Accéder à votre service de recherche.

3. Dans la page de la vue d’ensemble, sélectionnez l’onglet Index :

   • Les contributeurs du service de recherche peuvent afficher et créer n’importe quel objet, mais ils ne peuvent pas charger de documents ni interroger un index. Pour vérifier les autorisations, créez un index de recherche.

   • Les Contributeurs de données d’index de recherche peuvent charger des documents. Le portail ne propose aucune option de chargement de documents en dehors de l’assistant Importation de données. Cependant, vous pouvez réinitialiser et exécuter un indexeur pour confirmer les autorisations de chargement de documents.

   • Les personnes avec le rôle Lecteur de données de l’index de recherche peuvent interroger l’index. Pour vérifier les autorisations, utilisez l’Explorateur de recherche. Vous devez pouvoir envoyer des requêtes et afficher les résultats, mais pas consulter la définition d’index.

REST API

Cette approche suppose Visual Studio Code avec une extension de client REST.

1. Ouvrez un interpréteur de commandes pour Azure CLI et connectez-vous à votre abonnement Azure.

   az login
   

2. Obtenez votre ID de locataire et votre ID d’abonnement. L’ID est utilisé comme variable dans une étape ultérieure.

   az account show
   

3. Obtenez un jeton d’accès.

   az account get-access-token --query accessToken --output tsv
   

4. Collez ces variables dans un nouveau fichier texte dans Visual Studio Code.

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

5. Collez-les, puis envoyez une demande qui utilise les variables que vous avez spécifiées. Pour le rôle « Lecteur de données d’index de recherche », vous pouvez envoyer une requête. Vous pouvez utiliser n’importe quelle version d’API prise en charge.

   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
        }
   

Pour plus d’informations sur l’acquisition d’un jeton pour un environnement spécifique, consultez Gérer un service Recherche Azure AI avec des API REST et Bibliothèques d’authentification de la plateforme d’identité Microsoft.

.NET

1. Utilisez le package Azure.Search.Documents.

2. Utilisez Azure.Identity pour .NET pour l’authentification par jeton. Microsoft recommande DefaultAzureCredential() pour la plupart des scénarios.

3. Voici un exemple de connexion client utilisant 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. Voici un autre exemple d’utilisation des informations d’identification de la clé secrète client :

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

Python

1. Utilisez azure.search.documents (SDK Azure pour Python).

2. Utilisez Azure.Identity pour Python pour l’authentification par jeton.

3. Utilisez DefaultAzureCredential si le client Python est une application qui exécute côté serveur. Activez l’authentification interactive si l’application s’exécute dans un navigateur.

4. Voici un exemple :

   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)
   

JavaScript

1. Utilisez @azure/search-documents (kit de développement logiciel Azure pour JavaScript) version 11.3.

2. Utilisez Azure.Identity pour JavaScript pour l’authentification par jeton.

3. Si vous utilisez React, utilisez InteractiveBrowserCredential pour l’authentification Microsoft Entra à rechercher. Consultez Quand utiliser @azure/identity pour plus d’informations.

Java

1. Utilisez azure.search.documents (SDK Azure pour Java).

2. Utilisez Azure.Identity pour Java pour l’authentification par jeton.

3. Microsoft recommande DefaultAzureCredential pour les applications qui s’exécutent sur Azure.

Tester en tant qu’utilisateur actuel

Si vous êtes déjà contributeur ou propriétaire de votre service de recherche, vous pouvez présenter un jeton de porteur pour votre identité utilisateur pour l’authentification auprès de la recherche Azure AI.

1. Obtenez un jeton du porteur pour l’utilisateur actuel à l’aide d’Azure CLI :

   az account get-access-token --scope https://search.azure.com/.default
   

   Ou à l’aide de PowerShell :

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. Collez ces variables dans un nouveau fichier texte dans Visual Studio Code.

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

3. Collez puis envoyez une requête pour vérifier l’accès. En voici une qui interroge l’index hotels-quickstart :

   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
        }
   

Accorder l’accès à un index unique

Dans certains scénarios, il est possible que vous souhaitiez limiter l’accès d’une application à une seule ressource, comme un index.

Le portail ne prend actuellement pas en charge les attributions de rôles à ce niveau de précision, mais vous pouvez le faire avec PowerShell ou Azure CLI.

Dans PowerShell, utilisez New-AzRoleAssignment, en indiquant le nom de l’utilisateur ou du groupe Azure et l’étendue de l’attribution.

1. Chargez les modules Azure et AzureAD, puis connectez-vous à votre compte Azure :

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Ajoutez une attribution de rôle étendue à un index individuel :

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

Créer un rôle personnalisé

Si les rôles intégrés ne fournissent pas la bonne combinaison d’autorisations, vous pouvez créer un rôle personnalisé pour prendre en charge les opérations requises.

Cet exemple clone le lecteur de données d’index de recherche, puis ajoute la possibilité de répertorier les index par nom. Normalement, la liste des index sur un service de recherche est considérée comme un droit administratif.

Azure portal

Ces étapes sont dérivées de Créer ou de mettre à jour des rôles personnalisés Azure à l’aide du Portail Azure. Le clonage à partir d’un rôle existant est pris en charge dans une page de service de recherche.

Ces étapes créent un rôle personnalisé qui augmente les droits de requête de recherche pour inclure des index de liste par nom. En règle générale, la liste des index est considérée comme une fonction d’administrateur.

1. Dans le portail Azure, accédez à votre service de recherche.

2. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

3. Dans la barre d’action, sélectionnez Rôles.

4. Cliquez avec le bouton droit sur Lecteur de données d’index de recherche (ou un autre rôle) et sélectionnez Cloner pour ouvrir l’Assistant Créer un rôle personnalisé.

5. Sous l’onglet Informations de base, indiquez un nom pour le rôle personnalisé, comme "Explorateur de données d’index de recherche", puis sélectionnez Suivant.

6. Sous l’onglet Autorisations, cliquez sur Ajouter des autorisations.

7. Sous l’onglet Ajouter des autorisations, recherchez, puis sélectionnez la vignette Recherche Microsoft.

8. Définissez les autorisations pour votre rôle personnalisé. En haut de la page, à l’aide de la sélection Actions par défaut :

   • Sous Microsoft.Search/operations, sélectionnez Lecture : Répertorier toutes les opérations disponibles.
   • Sous Microsoft.Search/searchServices/index, sélectionnez Lecture : Index de lecture.

9. Dans la même page, basculez vers Actions de données et sous Microsoft.Search/searchServices/index/documents, sélectionnez Lecture : Lire des documents.

   La définition JSON ressemble à l’exemple qui suit :

   {
    "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. Sélectionnez Vérifier + créer pour créer le rôle. Vous pouvez maintenant affecter des utilisateurs et des groupes au rôle.

Azure PowerShell

L’exemple PowerShell montre la syntaxe JSON pour créer un rôle personnalisé qui est un clone du lecteur de données d’index de recherche, mais avec la possibilité de répertorier tous les index par nom.

1. Examinez la liste des autorisations atomiques pour déterminer celles dont vous avez besoin. Pour cet exemple, vous aurez besoin des éléments suivants :

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

2. Configurez une session PowerShell pour créer le rôle personnalisé. Pour obtenir des instructions détaillées, consultez Azure PowerShell.

3. Fournissez la définition de rôle sous la forme d’un document JSON. L’exemple suivant montre la syntaxe permettant de créer un rôle personnalisé avec 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}"
  ]
}

Remarque

Si l’étendue assignable se trouve au niveau de l’index, l’action de données doit être "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Examinez la liste des autorisations atomiques pour déterminer celles dont vous avez besoin.

2. Pour savoir comment procéder, consultez Créer ou mettre à jour des rôles personnalisés Azure à l’aide de l’API REST.

3. Copiez ou créez un rôle, ou utilisez JSON pour spécifier le rôle personnalisé (voir l’onglet PowerShell pour la syntaxe JSON).

Azure CLI

1. Examinez la liste des autorisations atomiques pour déterminer celles dont vous avez besoin.

2. Pour savoir comment procéder, consultez Créer ou mettre à jour des rôles personnalisés Azure à l’aide d’Azure CLI.

3. Consultez l’onglet PowerShell pour la syntaxe JSON.

Accès conditionnel

Nous recommandons l’accès conditionnel Microsoft Entra si vous devez appliquer des stratégies organisationnelles, notamment l’authentification multifacteur.

Pour activer une stratégie d’accès conditionnel pour Recherche Azure AI, effectuez les étapes suivantes :

1. Connectez-vous au portail Azure.

2. Recherchez l’accès conditionnel Microsoft Entra.

3. Sélectionnez Stratégies.

4. Sélectionnez Nouvelle stratégie.

5. Dans la section Applications cloud ou actions de la stratégie, ajoutez Recherche Azure AI en tant qu’application cloud selon la manière dont vous souhaitez configurer votre stratégie.

6. Mettez à jour les paramètres restants de la stratégie. Par exemple, spécifiez les utilisateurs et les groupes auxquels cette stratégie s’applique.

7. Enregistrez la stratégie.

Important

Si une identité managée est attribuée à votre service de recherche, celui-ci apparaîtra comme une application cloud qui peut être incluse ou exclue dans le cadre de la stratégie d’accès conditionnel. Les stratégies d’accès conditionnel ne peuvent pas être appliquées à un service de recherche spécifique. Veillez plutôt à sélectionner l’application cloud générale Recherche Azure AI.

Limites

• Le contrôle d’accès en fonction du rôle peut augmenter la latence de certaines demandes. Chaque combinaison unique de ressource de service (index, indexeur, etc.) et de principal de service déclenche une vérification d’autorisation. Ces vérifications d’autorisation peuvent ajouter jusqu’à 200 millisecondes de latence par demande.

• Dans de rares cas où les demandes proviennent d’un grand nombre de principaux de service différents, ciblant différentes ressources de service (index, indexeurs, etc.), il est possible que les vérifications d’autorisation entraînent une limitation. La limitation se produit uniquement si des centaines de combinaisons uniques de chaque ressource du service de recherche et du principal de service ont été utilisées en une seconde.

Résolution des problèmes de contrôle d’accès en fonction du rôle

Lorsque vous développez des applications qui utilisent le contrôle d’accès en fonction du rôle pour l’authentification, il est possible que certains problèmes courants se produisent :

• Si le jeton d’autorisation provient d’une identité managée et que les autorisations appropriées ont été récemment attribuées, il est possible que la prise d’effet de celles-ci prenne plusieurs heures.

• La configuration par défaut d’un service de recherche est une authentification par clé. Si vous n’avez pas modifié le paramètre de clé par défaut sur Les deux ou Contrôle d’accès en fonction du rôle, toutes les requêtes utilisant l’authentification en fonction du rôle sont automatiquement refusées, quelles que soient les autorisations sous-jacentes.