Partager via

Tutoriel : Indexer les métadonnées d’autorisation à partir d’ADLS Gen2 et interroger avec des résultats filtrés par autorisation

Ce tutoriel montre comment indexer des Listes de contrôle d’accès (ACL) Azure Data Lake Storage (ADLS) Gen2 et des Listes de contrôle d’accès en fonction du rôle (RBAC) dans un index de recherche à l’aide d’un indexeur.

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 l’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
  • Effectuer une recherche dans l’index que vous venez de créer

Utilisez un client REST pour suivre ce didacticiel et la dernière préversion de l’API REST. Actuellement, l’indexation ACL n’est pas prise en charge dans le portail Microsoft Azure.

Conditions préalables

  • Un compte Azure avec un abonnement actif. Créez un compte gratuitement.

  • Authentification et autorisation Microsoft Entra ID. 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. Il faudrait avoir des utilisateurs et des groupes pour travailler avec. La création de locataires et de principaux de sécurité est hors du cadre de ce didacticiel.

  • ADLS Gen2 avec un espace de noms hiérarchique.

  • Fichiers dans une structure de dossiers hiérarchique. Ce didacticiel part du principe que la 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 IA Azure, 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 un client REST ou un client Python et un package Jupyter.

Préparer les données d'échantillon

Chargez les exemples de données de parcs d’état dans un conteneur dans 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 le service de recherche pour l’authentification et l’autorisation 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.

Suivez 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

En guise de meilleure pratique, utilisez des jeux Group plutôt que d’affecter directement des jeux User.

  1. Accordez à l’identité du service de recherche l’accès en lecture au conteneur. L’indexeur se connecte au 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.

  2. Accordez des autorisations par groupe ou utilisateur dans la hiérarchie de fichiers. Dans la hiérarchie de fichiers, identifiez tous les ensembles Group et User qui sont affectés aux conteneurs, répertoires et fichiers.

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

  4. Ajoutez de nouveaux principaux de sécurité pour les utilisateurs et les groupes.

  5. Supprimez les principaux existants pour les groupes propriétaires, les utilisateurs propriétaires et d’autres. Ces principaux ne sont pas pris en charge pour l’indexation de liste de contrôle d’accès pendant la préversion publique.

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 la dernière API REST en préversion ou un package de sdk Azure en préversion 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 de 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 des documents sont chargés, vous pouvez émettre des requêtes sur ceux-ci en tirant parti de Documents – Rechercher des publications (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 de l’ACL et du RBAC au moment des requêtes.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-11-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"
}

Contenu connexe

  • Last updated on