Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Note
Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.
Important
Les fonctionnalités, capacités ou propriétés marquées (préversion) ne sont pas couvertes par un accord de niveau de service, ne sont pas recommandées pour les workloads de production et peuvent être modifiées ou faire l’objet de restrictions avant leur mise à disposition générale. Les Recherche Azure AI termes de la préversion s'appliquent à toutes les fonctionnalités d'aperçu, qu'il s'agisse d'une fonctionnalité autonome ou d'une partie d'une fonctionnalité généralement disponible.
Ce tutoriel présente l’ingestion de métadonnées d’autorisation (préversion) pour Azure Data Lake Storage (ADLS) Gen2, dans lequel un indexeur Recherche Azure AI ajoute des listes de contrôle d’accès (ACL) ainsi que l’étendue du contrôle d’accès en fonction du rôle (RBAC) à un index de recherche.
Il vous montre également comment structurer une requête qui respecte les autorisations d’accès utilisateur. Un résultat de requête réussi confirme le transfert d’autorisation qui s’est produit pendant le processus d'indexation.
Pour plus d’informations sur l’indexation des listes de contrôle d’accès, consultez Utiliser un indexeur ADLS Gen2 pour ingérer les métadonnées d’autorisation.
Dans ce tutoriel, vous allez apprendre à :
- Configurer l’étendue RBAC et les ACL sur une source de données
adlsgen2 - Créer un index Recherche Azure AI contenant des champs d’informations d’autorisation
- Créer et exécuter un indexeur pour ingérer des informations d’autorisation dans un index à partir d’une source de données
- Rechercher l’index que vous venez de créer
Utilisez un client REST pour suivre ce didacticiel et la dernière API REST en préversion. Actuellement, il n'existe aucun support pour l'indexation ACL dans le portail Azure.
Conditions préalables
Un compte Azure avec un abonnement actif. Créez gratuitement un compte.
Microsoft Entra ID pour l'authentification et l'autorisation. Les services et les applications doivent se trouver dans le même locataire. Les attributions de rôles sont utilisées pour chaque connexion authentifiée. Les utilisateurs et les groupes doivent se trouver dans le même locataire. Vous devez avoir des utilisateurs et des groupes à votre disposition. La création de locataires et de principaux de sécurité n'est pas couverte par ce didacticiel.
ADLS Gen2 avec un espace de noms hiérarchique.
Fichiers dans une structure de dossiers hiérarchique. Ce tutoriel présume une démonstration ADLS Gen2 de la structure de dossiers pour le fichier
/Oregon/Portland/Data.txt. Ce tutoriel vous guide tout au long de l’attribution de liste de contrôle d’accès sur les dossiers et les fichiers afin que vous puissiez effectuer l’exercice avec succès.Recherche Azure AI, n’importe quelle région. Le niveau de base ou supérieur est requis pour la prise en charge des identités managées.
Visual Studio Code avec l’extension client REST.
Préparer des exemples de données
Chargez les données des parcs d'État dans un conteneur de ADLS Gen2. Le nom du conteneur doit être « parcs » et il doit avoir deux dossiers : « Oregon » et « Washington ».
Vérifier la configuration du service de recherche
Vous devez configurer votre service de recherche pour l'authentification et l’autorisation de Microsoft Entra ID. Passez en revue cette liste de contrôle pour vous assurer que vous êtes prêt.
Obtenir un jeton d’identité personnel pour les tests locaux
Ce tutoriel suppose qu’un client REST sur un système local se connecte à Azure via une connexion Internet publique.
Follow ces étapes pour acquérir un jeton d’identité personnel et configurer Visual Studio Code pour les connexions locales à vos ressources Azure.
Définir des autorisations dans ADLS Gen2
Comme bonne pratique, utilisez des ensembles Group plutôt que d’attribuer directement des ensembles User.
Accordez à l’identité du service de recherche un accès en lecture au conteneur. L’indexeur se connecte à stockage Azure sous l’identité du service de recherche. Le service de recherche doit disposer des autorisations Lecteur de données blob de stockage pour récupérer des données.
Accordez des autorisations par groupe ou utilisateur dans la hiérarchie de fichiers. Dans la hiérarchie de fichiers, identifiez tous les ensembles
GroupetUserqui sont assignés aux conteneurs, répertoires et fichiers.Vous pouvez utiliser le portail Azure pour gérer les listes de contrôle d’accès. Dans Le navigateur de stockage, sélectionnez le répertoire Oregon, puis sélectionnez Gérer la liste de contrôle d’accès dans le menu contextuel.
Ajoutez de nouvelles entités de sécurité pour les utilisateurs et les groupes.
Supprimez les entités principales existantes pour les groupes propriétaires, les utilisateurs propriétaires et autres entités. Ces principaux ne sont pas pris en charge pour l’indexation ACL pendant la version préliminaire.
Créer un index de recherche pour les métadonnées d’autorisation
Créez un index qui contient des champs pour les métadonnées de contenu et d’autorisation.
Veillez à utiliser l’API REST version la plus récente ou un package de Kit de développement logiciel (SDK) Azure d’aperçu qui fournit des fonctionnalités équivalentes. Les propriétés du filtre d’autorisation sont disponibles uniquement dans les API d’aperçu.
À des fins de démonstration, le champ d’autorisation est retrievable activé pour vous permettre de vérifier les valeurs de l’index. Dans un environnement de production, vous devez désactiver retrievable pour éviter la fuite d’informations sensibles.
{
"name" : "my-adlsgen2-acl-index",
"fields": [
{
"name": "name", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "description", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "location", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "state", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "AzureSearch_DocumentKey", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true, "stored": true,
"key": true
},
{
"name": "UserIds", "type": "Collection(Edm.String)",
"permissionFilter": "userIds",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "GroupIds", "type": "Collection(Edm.String)",
"permissionFilter": "groupIds",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "RbacScope", "type": "Edm.String",
"permissionFilter": "rbacScope",
"searchable": true, "filterable": false, "retrievable": true
}
],
"permissionFilterOption": "enabled"
}
Créer une source de données
Modifiez la configuration de la source de données pour spécifier l’ingestion d’autorisation de l’indexeur et les types de métadonnées d’autorisation que vous souhaitez indexer.
Une source de données a besoin indexerPermissionOptions.
Dans ce tutoriel, utilisez une identité managée affectée par le système pour la connexion authentifiée.
{
"name" : "my-adlsgen2-acl-datasource",
"type": "adlsgen2",
"indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
"credentials": {
"connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
},
"container": {
"name": "parks",
"query": null
}
}
Créer et exécuter l’indexeur
La configuration de l’indexeur pour l’ingestion d’autorisations consiste principalement à définir fieldMappings à partir des métadonnées d’autorisation.
{
"name" : "my-adlsgen2-acl-indexer",
"dataSourceName" : "my-adlsgen2-acl-datasource",
"targetIndexName" : "my-adlsgen2-acl-index",
"parameters": {
"batchSize": null,
"maxFailedItems": 0,
"maxFailedItemsPerBatch": 0,
"configuration": {
"dataToExtract": "contentAndMetadata",
"parsingMode": "delimitedText",
"firstLineContainsHeaders": true,
"delimitedTextDelimiter": ",",
"delimitedTextHeaders": ""
},
"fieldMappings": [
{ "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
{ "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
{ "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
]
}
}
Après la création et l’exécution immédiate de l’indexeur, le contenu du fichier ainsi que les informations de métadonnées d’autorisation sont indexés dans l’index.
Exécuter une requête pour vérifier les résultats
Maintenant que les documents sont chargés, vous pouvez exécuter des requêtes dessus à l’aide de Documents - Exécution d’une recherche via POST (REST).
L’URI est étendu pour inclure une entrée de requête, qui est spécifiée à l’aide de l’opérateur /docs/search . Le jeton de requête est transmis dans l’en-tête de requête. Pour plus d’informations, consultez l'application des ACL au moment des requêtes et la mise en œuvre du RBAC.
POST {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json
{
"search": "*",
"select": "name,description,location,GroupIds",
"orderby": "name asc"
}