Indexer les données d’Azure Files

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu Azure Files et le rend utilisable dans une requête de Recherche Azure AI. Les entrées de l’indexeur sont vos fichiers, dans un même partage. 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 vient compléter la page Créer un indexeur avec des informations spécifiques à l’indexation de fichiers dans Stockage Azure. 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.

Prérequis

• Stockage Fichier, niveau optimisé pour les transactions.

• Un partage de fichiers SMB fournissant le contenu source. Les partages NFS ne sont pas pris en charge.

• Des fichiers contenant du texte. Si vous avez des données binaires, vous pouvez inclure l’enrichissement par IA pour l’analyse des images.

• Autorisations de lecture sur Stockage Azure. Une chaîne de connexion à « accès total » contient une clé qui accorde l’accès au contenu.

• Utilisez un client REST pour formuler des appels REST semblables à ceux présentés dans cet article.

Formats de document pris en charge

L’indexeur Stockage Fichier 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

Comment les Azure Files sont indexés

Par défaut, la plupart des fichiers sont indexés en tant que document de recherche unique dans l’index, y compris les fichiers avec un contenu structuré, par exemple au format JSON ou CSV, qui sont indexés en tant que bloc de texte unique.

Un document composé ou incorporé (comme une archive ZIP, un document Word avec un e-mail Outlook incorporé intégrant des pièces jointes ou un fichier .MSG avec des pièces jointes) est également indexé comme un seul document. Par exemple, toutes les images extraites des pièces jointes d’un fichier .MSG seront renvoyées dans le champ normalized_images. Si vous avez des images, pensez à ajouter l’enrichissement par IA pour que ce contenu soit plus utile aux recherches.

Le contenu textuel d’un document est extrait dans un champ de type chaîne nommé « content ». Vous pouvez également extraire les métadonnées standard et définies par l’utilisateur.

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.

Vous pouvez utiliser la version 2020-06-30-preview ou ultérieure pour « type » : "azurefile". Nous vous recommandons l’API dans la préversion la plus récente.

1. Créez une source de données pour définir sa définition à l’aide d’une API en préversion pour « type » : "azurefile".

   POST /datasources?api-version=2024-05-01-preview
   {
       "name" : "my-file-datasource",
       "type" : "azurefile",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
   }
   

2. Définissez « type » sur "azurefile" (obligatoire).

3. Définissez « credentials » sur une chaîne de connexion Stockage Azure. La section suivante décrit les formats pris en charge.

4. Définissez « container » sur le partage de fichiers racine, 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 partage de fichiers à l’aide des connexions suivantes.

Ajouter des champs de recherche à un index

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

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

   POST /indexes?api-version=2024-07-01
   {
     "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_path", "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": true, "filterable": true, "sortable": true }        
     ]
   }
   

2. 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. 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. L’indexeur encode automatiquement la propriété de métadonnées de clé, sans configuration ni mappage de champ requis.

   • metadata_storage_path (valeur par défaut) chemin d’accès complet à l’objet ou au fichier

   • metadata_storage_name utilisable uniquement si les noms sont uniques

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

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

4. Ajoutez des champs pour les propriétés de métadonnées standard. Dans l’indexation des fichiers, les propriétés des métadonnées standard sont les mêmes que celles des métadonnées des blobs. L'indexeur Azure Files crée automatiquement des correspondances de mappage des champs internes pour ces propriétés. Celles-ci convertissent les noms de propriétés avec trait d'union en noms de propriétés avec trait de soulignement. Vous devez toujours ajouter les champs que vous souhaitez utiliser dans la définition de l’index, mais vous pouvez omettre de créer des mappages de champs dans la source de données.

   • metadata_storage_name (Edm.String) : le nom du fichier. Par exemple, si vous disposez du fichier /my-share/my-folder/subfolder/resume.pdf, ce champ présente la valeur resume.pdf.
   • metadata_storage_path (Edm.String) : URI complet du fichier, incluant le compte de stockage. Par exemple, https://myaccount.file.core.windows.net/my-share/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 fichier. Par exemple : application/octet-stream.
   • metadata_storage_last_modified (Edm.DateTimeOffset) : horodatage de la dernière modification du fichier. Recherche Azure AI utilise cet horodateur pour identifier les fichiers modifiés afin d’éviter une réindexation complète après l’indexation initiale.
   • metadata_storage_size (Edm.Int64) : taille du fichier en octets.
   • metadata_storage_content_md5 (Edm.String) : code de hachage MD5 du contenu du fichier 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 fichier. Ce jeton ne doit pas être stocké pour une utilisation ultérieure dans la mesure où il peut expirer.

Configurer et exécuter l'indexeur Azure Files

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.

1. 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 :

   POST /indexers?api-version=2024-07-01
   {
     "name" : "my-file-indexer",
     "dataSourceName" : "my-file-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "configuration": {
           "indexedFileNameExtensions" : ".pdf,.docx",
           "excludedFileNameExtensions" : ".png,.jpeg" 
       }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Dans la section « configuration » facultative, indiquez les critères d’inclusion ou d’exclusion. Si aucun fichier n’est spécifié, tous les fichiers du partage de fichiers sont récupérés.

   Si les paramètres indexedFileNameExtensions et excludedFileNameExtensions sont tous deux présents, Recherche Azure AI regarde d’abord indexedFileNameExtensions, puis excludedFileNameExtensions. Si la même extension de fichier figure dans les deux listes, elle est exclue de l’indexation.

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

4. Pour plus d’informations sur les autres propriétés, consultez Créer un indexeur.

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=2024-07-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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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.

É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 :

• Détection des modifications et détection des suppressions
• Indexer de grands jeux de données