Utiliser un indexeur d’objets blob ou une source de connaissance pour ingérer les métadonnées des étendues RBAC (préversion)

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.

stockage Azure permet l’accès en fonction du rôle sur les conteneurs dans le stockage d’objets blob, où les rôles tels que Lecteur de données BlobStorage ou Contributeur aux données blobStorage déterminent si quelqu’un a accès au contenu. Recherche Azure AI prend en charge l’ingestion des autorisations utilisateur (préversion) parallèlement à l’ingestion de documents afin d’utiliser ces autorisations pour contrôler l’accès aux résultats de recherche. Si un utilisateur n'a pas d'autorisations sur un répertoire ou un fichier spécifique dans stockage Azure, celui-ci n'a pas accès aux documents correspondants dans les résultats de Recherche Azure AI, même si vous disposez personnellement d'une affectation Search Index Data Reader sur l'index.

  • À partir de 2025-05-01-preview et pour les versions ultérieures, les métadonnées des étendues RBAC peuvent être ingérées à l’aide de l’indexeur Blob.
  • 2025-11-01-preview et les versions ultérieures fournissent une prise en charge équivalente des sources de connaissances Blob dans stockage Azure.

Le périmètre RBAC est défini au niveau du conteneur et s’applique à tous les blobs (documents) via l’héritage des autorisations. L’étendue RBAC est capturée lors de l’indexation en tant que métadonnées d’autorisation. Vous pouvez utiliser les API Push pour charger et indexer le contenu et les métadonnées d’autorisation manuellement (voir Autorisations d’indexation à l’aide de l’API REST Push), ou vous pouvez utiliser un indexeur ou une source de connaissances pour automatiser l’ingestion des données. Cet article se concentre sur l'automatisation de l'indexation.

Au moment de la requête, l’identité de l’appelant est incluse dans l’en-tête de requête via le x-ms-query-source-authorization paramètre. L’identité doit correspondre aux métadonnées d’autorisation sur les documents si l’utilisateur doit afficher les résultats de la recherche.

Cet article se concentre sur les approches d’automatisation de l’indexation, basées sur cette base :

Conditions préalables

  • Microsoft Entra ID authentification et autorisation. Les services et les applications doivent se trouver dans le même locataire. Les utilisateurs peuvent se trouver dans différents locataires, à condition que tous les locataires utilisent Microsoft Entra ID. Les attributions de rôles sont utilisées pour chaque connexion authentifiée.

  • Recherche Azure AI, n’importe quelle région, mais vous devez disposer d’un niveau facturable (de base et supérieur) pour la prise en charge des identités managées. Le service de recherche doit être configuré pour l’accès en fonction du rôle et doit avoir une identité managée (système ou utilisateur).

  • Stockage Azure, performances standard (v2 à usage général), sur les niveaux d’accès chaud, sporadique et froid, avec des conteneurs ou des objets blob sécurisés par RBAC.

  • Vous devez comprendre comment les indexeurs et les sources de connaissances fonctionnent et comment créer un index. Cet article explique les paramètres de configuration de la source de données et de l’indexeur, mais ne fournit pas les étapes de création de l’index. Pour plus d’informations sur les index conçus pour les filtres d’autorisations, consultez Créer un index avec des champs de filtre d’autorisation.

Limitations

Configurer le Stockage Blob

Vérifiez que votre conteneur d’objets blob utilise un accès basé sur les rôles.

  1. Connectez-vous au portail Azure et recherchez votre compte de stockage.

  2. Étendez les conteneurs et sélectionnez le conteneur qui contient les objets blob que vous souhaitez indexer.

  3. Sélectionnez Access Control (IAM) pour vérifier les attributions de rôles. Les utilisateurs et les groupes disposant d’un lecteur de données Blob de stockage ou d’un contributeur aux données blob de stockage ont accès aux documents de recherche dans l’index une fois le conteneur indexé.

Autorisation

Pour l’exécution de l’indexeur, l’identité de votre service de recherche doit disposer de l’autorisation Lecteur de données Blob de stockage. Pour plus d’informations, consultez Connect to stockage Azure using a managed identity.

Rappelez-vous que le service de recherche doit avoir :

Autorisation

Pour l’exécution de l’indexeur, le client qui émet l’appel d’API doit avoir Contributeur du serviceSearch l’autorisation de créer des objets, Search Index Data Contributor autorisation d’effectuer l’importation de données et Search Index Data Reader pour interroger un index, voir Connect to Recherche Azure AI using roles.

Configurer une source de connaissances

Si vous utilisez une source de connaissances, les définitions de la source de connaissances sont utilisées pour générer un pipeline d’indexation complet (indexeur, source de données et index). L’étendue RBAC est détectée et automatiquement incluse dans l’index généré. Il n’est pas nécessaire de modifier l’un des objets générés si vous souhaitez l’héritage d’autorisation dans votre contenu indexé.

Points clés sur la configuration qui le rendent adapté à ce scénario :

  • isADLSGen2 a la valeur false, ce qui signifie que la source de données est Stockage Blob Azure.
  • ingestionPermissionOptions spécifie rbacScope.
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": false,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

Référence :Créer ou mettre à jour une source de connaissances (API REST)

Configurer l’indexation basée sur l’indexeur

Si vous utilisez un indexeur, configurez-le, la source de données et l’index pour extraire les métadonnées d’autorisation à partir d’objets blob.

Créer la source de données

  • Le type de source de données doit être azureblob.

  • Le mode d’analyse de source de données doit être la valeur par défaut.

  • La source de données doit avoir indexerPermissionOptions avec rbacScope.

Exemple JSON avec une identité managée système et indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    }
}

Exemple de schéma JSON avec une identité managée par l’utilisateur dans le chaîne de connexion :

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
        "name": "<your-container-name>",
        "query": "<optional-query-used-for-selecting-specific-blobs>"
    },
    "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Créer des champs d’autorisation dans l’index

Dans Recherche Azure AI, vérifiez que votre index contient des définitions de champs pour les métadonnées d’autorisation. Les métadonnées d’autorisation peuvent être indexées quand indexerPermissionOptions elles sont spécifiées dans la définition de la source de données.

Attributs de schéma recommandés pour la portée RBAC :

  • Champ d’étendue RBAC avec la valeur de permissionFilter rbacScope.
  • Propriété permissionFilterOption permettant d’activer le filtrage au moment de l’interrogation.
  • Utiliser des champs de chaîne pour les métadonnées d’autorisation
  • Définissez la filterable valeur true sur tous les champs.

Notez que retrievable est faux. Vous pouvez définir la valeur true pendant le développement pour vérifier que les autorisations sont présentes, mais n’oubliez pas de revenir à false avant de le déployer dans un environnement de production afin que les identités de principal de sécurité ne soient pas visibles dans les résultats.

Exemple de schéma JSON :

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

Configurer l’indexeur

Les mappages de champs au sein d’un indexeur définissent le chemin des données sur les champs d’un index. Les champs cibles et de destination qui varient selon le nom ou le type de données nécessitent un mappage de champ explicite. Les champs de métadonnées suivants dans Stockage Blob Azure peuvent avoir besoin de mappages de champs si vous modifiez le nom du champ :

  • metadata_rbac_scope (Edm.String) : étendue RBAC du conteneur.

Spécifiez fieldMappings dans l’indexeur pour router les métadonnées d’autorisation vers les champs cibles pendant l’indexation.

Exemple de schéma JSON :

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Exécuter l’indexeur

Une fois que votre indexeur, votre source de données et votre index sont configurés, exécutez l’indexeur pour définir le processus en mouvement. S’il existe un problème avec la configuration ou les autorisations, ces problèmes s’affichent à cette étape.

Par défaut, un indexeur s’exécute dès que vous le publiez dans un service de recherche, mais si la configuration de l’indexeur inclut disabled la valeur true, l’indexeur est publié dans un état désactivé afin que vous puissiez exécuter l’indexeur manuellement.

Nous vous recommandons de exécuter l’indexeur à partir du portail Azure afin de pouvoir surveiller l’état et les messages.

En supposant qu’aucune erreur n’est détectée, l’index est maintenant rempli et vous pouvez avancer avec les requêtes et les tests.

Suivi des suppressions

Pour gérer efficacement la suppression d’objets blob, vérifiez que vous avez activé le suivi des suppressions avant l’exécution de votre indexeur pour la première fois. Cette fonctionnalité permet au système de détecter les objets blob supprimés de votre source et de supprimer le contenu correspondant de l’index.

Voir aussi

  • Last updated on