Indexer des données à partir d'Azure Data Lake Storage Gen2

Article
02/19/2024

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir d’Azure Data Lake Storage (ADLS) Gen2 et le rend utilisable dans une requête Recherche Azure AI. Les entrées de l’indexeur sont vos blobs, dans un seul conteneur. La sortie est un index de recherche avec du contenu et des métadonnées pouvant faire l’objet de recherches stockés dans des champs individuels.

Cet article est un complément de Créer un indexeur avec des informations spécifiques de l’indexation à partir d’ADLS Gen2. Il utilise les API REST pour illustrer un workflow en trois parties commun à tous les indexeurs : créer une source de données, créer un index, créer un indexeur. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Pour obtenir un exemple de code en C#, consultez Indexer Data Lake Gen2 à l’aide de Microsoft Entra ID sur GitHub.

Prérequis

ADLS Gen2 avec espace de noms hiérarchique activé. ADLS Gen2 est disponible via Stockage Azure. Lorsque vous configurez un compte de stockage, vous avez la possibilité d’activer un espace de noms hiérarchique, organisant les fichiers dans une hiérarchie de répertoires et de sous-répertoires imbriqués. En activant un espace de noms hiérarchique, vous activez ADLS Gen2.
Les niveaux d’accès pour ADLS Gen2 comprennent les niveaux chaud, froid et archive. Les indexeurs de recherche ne peuvent accéder qu’aux niveaux chaud et froid.
Des blobs contenant du texte. Si vous avez des données binaires, vous pouvez inclure l’enrichissement par IA pour l’analyse des images. Le contenu d’un objet blob ne doit pas dépasser les limites de l’indexeur pour votre niveau de service de recherche.
Autorisations de lecture sur Stockage Azure. Une chaîne de connexion « accès total » inclut une clé qui accorde l’accès au contenu, mais si vous utilisez des rôles Azure à la place, vérifiez que l’identité managée du service de recherche dispose des autorisations Lecteur des données Blob du stockage.
Utilisez un client REST pour formuler des appels REST semblables à ceux présentés dans cet article.

Remarque

ADLS Gen2 implémente un modèle de contrôle d’accès qui prend en charge le contrôle d’accès en fonction du rôle Azure (RBAC Azure) et les listes de contrôle d’accès (ACL) de type POSIX au niveau du blob. Recherche Azure AI ne prend pas en charge les autorisations au niveau du document. Tous les utilisateurs ont le même niveau d’accès à l’ensemble du contenu pouvant faire l’objet d’une recherche et être récupéré dans l’index. Si les autorisations de niveau document sont une exigence de l’application, envisagez le filtrage de sécurité comme solution potentielle.

Formats de document pris en charge

L’indexeur ADLS Gen2 peut extraire du texte à partir des formats de document suivants :

CSV (consultez Indexation d’objets blob CSV)
EML
EPUB
GZ
HTML
JSON (consultez l’indexation d’objets JSON blobs)
KML (XML pour les représentations géographiques)
Formats Microsoft Office : DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (e-mails Outlook), XML (XML WORD 2003 et 2006)
Formats de document ouverts : ODT, ODS, ODP
PDF
Fichiers de texte brut (voir aussi l’indexation de texte brut)
RTF
XML
ZIP

Déterminer les blobs à indexer

Avant de configurer l’indexation, passez en revue vos données sources pour déterminer si des changements doivent être effectués. Un indexeur peut indexer le contenu d’un conteneur à la fois. Par défaut, tous les blobs du conteneur sont traités. Vous avez plusieurs options pour un traitement plus sélectif :

Placez les blobs dans un dossier virtuel. Une définition de source de données d’indexeur comprend un paramètre « query » qui peut prendre un dossier virtuel. Si vous spécifiez un dossier virtuel, seuls les blobs du dossier sont indexés.
Ajoutez ou excluez des blobs par type de fichier. La liste de formats de document pris en charge peut vous aider à déterminer les blobs à exclure. Par exemple, vous pouvez exclure des fichiers image ou audio qui ne fournissent pas de texte pouvant faire l’objet d’une recherche. Cette fonctionnalité est contrôlée par les paramètres de configuration de l’indexeur.

Ajoutez ou excluez des blobs arbitraires. Si vous voulez ignorer un blob spécifique pour une raison quelconque, vous pouvez ajouter les propriétés et valeurs de métadonnées suivantes aux blobs dans le Stockage Blob. Quand un indexeur rencontre ces propriétés, il ignore le blob ou son contenu dans l’exécution de l’indexation.

Nom de la propriété	Valeur de la propriété	Explication
"AzureSearch_Skip"	`"true"`	Indique à l’indexeur d’objets blob d’ignorer complètement l’objet blob. Ni l’extraction des métadonnées, ni l’extraction de contenu n’est tentée. Cette propriété est utile lorsqu’un objet blob spécifique échoue à plusieurs reprises et interrompt le processus d’indexation.
"AzureSearch_SkipContent"	`"true"`	Ignore le contenu et extrait uniquement les métadonnées. Cela équivaut au paramètre `"dataToExtract" : "allMetadata"` décrit dans les paramètres de configuration, limité à un blob en particulier.

Si vous ne configurez pas de critères d’inclusion ou d’exclusion, l’indexeur signale les blobs inéligibles comme des erreurs et continue son travail. Si trop d’erreurs se produisent, le traitement peut s’arrêter. Vous pouvez spécifier une tolérance d’erreurs dans les paramètres de configuration de l’indexeur.

Un indexeur crée généralement un document de recherche par blob, où le contenu texte et les métadonnées sont capturés sous forme de champs pouvant faire l’objet d’une recherche dans un index. Si les blobs sont des fichiers entiers, vous pouvez potentiellement les analyser dans plusieurs documents de recherche. Par exemple, vous pouvez analyser les lignes d’un fichier CSV pour créer un document de recherche par ligne.

Indexation de métadonnées blob

Les métadonnées de blob peuvent également être indexées, ce qui est utile si vous pensez que les propriétés de métadonnées standard ou personnalisées seront utiles dans les filtres et les requêtes.

Les propriétés de métadonnées spécifiées par l’utilisateur sont extraites mot pour mot. Pour recevoir les valeurs, vous devez définir le champ dans l’index de recherche de type Edm.String, avec le même nom que la clé de métadonnées du blob. Par exemple, si un blob a une clé de métadonnées de Sensitivity avec la valeur High, vous devez définir un champ nommé Sensitivity dans votre index de recherche et il sera rempli avec la valeur High.

Les propriétés de métadonnées de blob standard peuvent être extraites dans des champs de même nom et de même type, comme indiqué ci-dessous. L’indexeur de blobs crée automatiquement des mappages de champs internes pour ces propriétés de métadonnées de blob, en convertissant le nom original avec traits d’union (« metadata-storage-name ») en un nom équivalent avec traits de soulignement (« metadata_storage_name »).

Vous devez toujours ajouter les champs avec traits de soulignement à la définition de l’index, mais vous pouvez omettre les mappages de champs, car l’indexeur fera l’association automatiquement.

metadata_storage_name (Edm.String) : nom de fichier du blob. Par exemple, si vous disposez de l’objet blob /my-container/my-folder/subfolder/resume.pdf, ce champ présente la valeur resume.pdf.
metadata_storage_path (Edm.String) : URI complet du blob, incluant le compte de stockage. Par exemple, https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String) : type de contenu tel que spécifié par le code que vous avez utilisé pour charger le blob. Par exemple : application/octet-stream.
metadata_storage_last_modified (Edm.DateTimeOffset) : horodatage de la dernière modification du blob. Recherche Azure AI utilise cet horodatage pour identifier les objets blob modifiés, afin d’éviter une réindexation complète après l’indexation initiale.
metadata_storage_size (Edm.Int64) : taille du blob en octets.
metadata_storage_content_md5 (Edm.String) : code de hachage MD5 du contenu du blob s’il est disponible.
metadata_storage_sas_token (Edm.String) : jeton SAP temporaire qui peut être utilisé par des compétences personnalisées pour accéder au blob. Ce jeton ne doit pas être stocké pour une utilisation ultérieure dans la mesure où il peut expirer.

Enfin, toutes les propriétés de métadonnées spécifiques du format de document des blobs que vous indexez peuvent également être représentées dans le schéma d’index. Pour plus d’informations sur les métadonnées spécifiques au contenu, consultez Propriétés des métadonnées de contenu.

Il est important de souligner que vous n’avez pas besoin de définir les champs relatifs à chacune des propriétés ci-dessus dans votre index de recherche. Il vous suffit de capturer les propriétés dont vous avez besoin pour votre application.

Définir la source de données

La définition de la source de données spécifie les données à indexer, les informations d’identification et les stratégies permettant d’identifier les changements de données. Une source de données est définie comme une ressource indépendante de manière à pouvoir être utilisée par plusieurs indexeurs.

Créez ou mettez à jour une source de données pour régler sa définition :

{
    "name" : "my-adlsgen2-datasource",
    "type" : "adlsgen2",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Définissez « type » sur "adlsgen2" (obligatoire).
Définissez "credentials" sur une chaîne de connexion Stockage Azure. La section suivante décrit les formats pris en charge.
Définissez "container" sur le conteneur de blobs et utilisez « query » pour spécifier tout sous-dossier.

Une définition de source de données peut également inclure des stratégies de suppression réversible si vous souhaitez que l’indexeur supprime un document de recherche lorsque le document source est marqué pour suppression.

Informations d’identification et chaînes de connexion prises en charge

Les indexeurs peuvent se connecter à un conteneur de blobs à l’aide des connexions suivantes.

Chaîne de connexion au compte de stockage avec accès complet
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Vous pouvez obtenir la chaîne de connexion à partir de la page du compte de stockage dans Portail Azure en sélectionnant Clés d’accès dans le volet de navigation de gauche. Veillez à sélectionner une chaîne de connexion complète et pas seulement une clé.

Chaîne de connexion d’identité managée
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Cette chaîne de connexion ne nécessite pas de clé de compte, mais vous devez avoir préalablement configuré un service de recherche pour la connexion avec une identité managée.

Chaîne de connexion de la signature d’accès partagé** (SAP) au compte de stockage
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
La SAP doit avoir les autorisations de liste et de lecture sur les conteneurs et les objets (blob en l’occurrence).

Remarque

Si vous utilisez des informations d’identification d’une SAP, vous devez mettre à jour les informations d’identification de la source de données régulièrement avec des signatures renouvelées afin d’éviter leur expiration. Si les informations d’identification de la SAP expirent, l’indexeur échoue avec un message d’erreur tel que « Les informations d’identification fournies dans la chaîne de connexion sont invalides ou ont expiré. »

Ajouter des champs de recherche à un index

Dans un index de recherche, ajoutez des champs pour accepter le contenu et les métadonnées de vos blobs Azure.

Créez ou mettez à jour un index pour définir les champs de recherche qui stockeront le contenu et les métadonnées des objets blob :

{
    "name" : "my-search-index",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }     
    ]
}

Créez un champ de clé de document ("key": true). Pour le contenu des blobs, les meilleurs candidats sont les propriétés de métadonnées.
- metadata_storage_path (valeur par défaut) chemin complet de l’objet ou du fichier. Le champ de clé (« ID » dans cet exemple) est rempli avec les valeurs de metadata_storage_path, car il s’agit de la valeur par défaut.
- metadata_storage_name, utilisable uniquement si les noms sont uniques. Pour que ce champ désigne la clé, déplacez "key": true vers cette définition de champ.
- Une propriété de métadonnées personnalisée que vous ajoutez aux objets blob. Cette option contraint votre processus de chargement de blob à ajouter cette propriété de métadonnées à tous les blobs. Étant donné que la clé est une propriété obligatoire, les blobs auxquels il manque une valeur ne seront pas indexés. Si vous utilisez une propriété de métadonnées personnalisée comme clé, évitez d’apporter des modifications à cette propriété. Les indexeurs ajoutent des documents en double pour le même objet blob si la propriété de clé est modifiée.
Les propriétés de métadonnées incluent souvent des caractères (par exemple / et -) qui ne sont pas valides pour les clés de document. Comme l’indexeur possède une propriété « base64EncodeKeys » (true par défaut), il encode automatiquement la propriété de métadonnées, sans qu’aucune configuration ni aucun mappage de champs ne soit nécessaire.
Ajoutez un champ « content » pour stocker le texte extrait de chaque fichier via la propriété « content » du blob. Vous n’êtes pas obligé d’utiliser ce nom, mais le faire vous permet de tirer parti des mappages de champs implicites.
Ajoutez des champs pour les propriétés de métadonnées standard. L’indexeur peut lire les propriétés des métadonnées personnalisées, celles des métadonnées standard et celles des métadonnées spécifiques au contenu.

Configurer et exécuter l’indexeur ADLS Gen2

Une fois l’index et la source de données créés, vous êtes prêt à créer l’indexeur. La configuration de l’indexeur spécifie les entrées, les paramètres et les propriétés qui contrôlent les comportements d’exécution. Vous pouvez également spécifier les parties d’un blob à indexer.

Créez ou mettez à jour un indexeur en lui attribuant un nom, et en référençant la source de données et l’index cible :

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "base64EncodeKeys": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Définissez « batchSize » si la valeur par défaut (10 documents) sous-utilise les ressources disponibles ou les épuise. Les tailles de lot par défaut sont spécifiques à la source de données. L’indexation des objets blob définit la taille des lots à 10 documents en fonction de la taille moyenne des documents la plus élevée.
Sous « configuration », contrôlez les blobs qui sont indexés à partir du type de fichier ou ne spécifiez pas de valeur pour récupérer tous les blobs.

Pour "indexedFileNameExtensions", fournissez une liste d’extensions de fichier (avec un point au début) séparées par des virgules. Procédez de la même façon pour "excludedFileNameExtensions", afin d’indiquer les extensions qui doivent être ignorées. Si la même extension figure dans les deux listes, elle est exclue de l’indexation.
Sous « configuration », définissez « dataToExtract » pour contrôler les parties des blobs qui sont indexées :
- contentAndMetadata spécifie que toutes les métadonnées et tous les contenus textuels extraits de l’objet blob sont indexés. Il s’agit de la valeur par défaut.
- storageMetadata spécifie que seules les propriétés standard et les métadonnées spécifiées par l’utilisateur sont indexées.
- allMetadata spécifie que les propriétés de blob standard et toutes les métadonnées pour les types de contenu trouvés sont extraites du contenu du blob et indexées.
Sous « configuration », définissez « parsingMode » si les blobs doivent être mappés à plusieurs documents de recherche, ou s’ils se composent de texte brut, de documents JSON ou de fichiers CSV.
Spécifiez les mappages de champs s’il existe des différences dans le nom ou le type du champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

Dans l’indexation des blobs, il est souvent possible d’omettre les mappages de champs, car l’indexeur dispose d’une prise en charge intégrée du mappage des propriétés « content » et de métadonnées vers des champs de même nom et de même type dans un index. Pour les propriétés de métadonnées, l’indexeur remplace automatiquement les traits d’union - par des traits de soulignement dans l’index de recherche.
Pour plus d’informations sur les autres propriétés, consultez Créer un indexeur. Pour obtenir la liste complète des descriptions des paramètres, consultez Paramètres de configuration des blobs dans l’API REST.

Un indexeur s’exécute automatiquement quand il est créé. Vous pouvez l’éviter en définissant « disabled » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le dans une planification.

Vérifier l’état de l’indexeur

Pour monitorer l’état de l’indexeur et l’historique d’exécution, envoyez une demande Obtenir l’état de l’indexeur :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

La réponse comprend l’état et le nombre d’éléments traités. Le résultat doit ressembler à l’exemple suivant :

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

L’historique d’exécution contient jusqu’à 50 exécutions les plus récentes, classées par ordre chronologique inversé, la dernière exécution apparaissant en premier.

Gérer les erreurs

Les erreurs qui se produisent généralement pendant l’indexation incluent les types de contenu non pris en charge, le contenu manquant ou les blobs surdimensionnés.

Par défaut, l’indexeur de blobs s’arrête dès qu’il rencontre un blob dont le type de contenu n’est pas pris en charge (par exemple, un fichier audio). Vous pouvez utiliser le paramètre « excludedFileNameExtensions » pour ignorer certains types de contenu. Toutefois, vous pourriez vouloir procéder à l’indexation même si des erreurs se produisent, puis déboguer les documents individuels plus tard. Pour plus d’informations sur les erreurs de l’indexeur, consultez Guide de résolution des problèmes de l’indexeur et Erreurs et avertissements de l’indexeur.

Il existe cinq propriétés d’indexeur qui contrôlent la réponse de l’indexeur lorsque des erreurs se produisent.

PUT /indexers/[indexer name]?api-version=2023-11-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Paramètre	Valeurs valides	Description
« maxFailedItems »	-1, nul ou 0, entier positif	Poursuivez l’indexation si des erreurs se produisent à un moment quelconque du traitement, que ce soit durant l’analyse de blobs ou l’ajout de documents à un index. Définissez ces propriétés sur le nombre d’échecs acceptables. La valeur `-1` permet le traitement, quel que soit le nombre d’erreurs qui se produisent. Dans le cas contraire, la valeur est un entier positif.
« maxFailedItemsPerBatch »	-1, nul ou 0, entier positif	Identique à ce qui précède, mais utilisé pour l’indexation par lots.
« failOnUnsupportedContentType »	True ou False	Si l’indexeur ne parvient pas à déterminer le type de contenu, spécifiez s’il faut poursuivre le travail ou le mettre en échec.
« failOnUnprocessableDocument »	True ou False	Si l’indexeur ne parvient pas à traiter un document d’un type de contenu autrement pris en charge, spécifiez s’il faut poursuivre le travail ou le mettre en échec.
« indexStorageMetadataOnlyForOversizedDocuments »	True ou False	Par défaut, les objets blob surdimensionnés sont traités comme des erreurs. Si vous définissez ce paramètre sur true, l’indexeur essaiera d’indexer ses métadonnées même si le contenu ne peut pas être indexé. Pour connaître les limites de taille des blobs, consultez Limites du service.

Limites

Contrairement aux indexeurs de blobs, les indexeurs ADLS Gen2 ne peuvent pas utiliser les jetons SAS au niveau du conteneur pour énumérer et indexer le contenu d’un compte de stockage. Cela est dû au fait que l’indexeur vérifie si le compte de stockage a des espaces de noms hiérarchiques activés en appelant le système de fichiers – Obtenir l’API propriétés. Pour les comptes de stockage où les espaces de noms hiérarchiques ne sont pas activés, les clients sont plutôt recommandés d’utiliser indexeurs d’objets blob pour garantir une énumération performante des objets blob.
Si la propriété metadata_storage_path est mappée comme champ de clé d’index, les objets blob ne sont pas garantis pour être réindexés lors d’un renommage de répertoire. Si vous souhaitez réindexer les objets blob qui font partie des répertoires renommés, mettez à jour les horodatages LastModified pour tous ces objets.

Étapes suivantes

Vous pouvez maintenant exécuter l’indexeur, surveiller l’état ou planifier l’exécution de l’indexeur. Les articles suivants s’appliquent aux indexeurs qui extraient du contenu de Stockage Azure :