Indexer les données de Azure Files (préversion)

L’indexeur Azure Files (préversion) importe du contenu à partir d’un partage de fichiers dans un index 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 d’une recherche stockés dans des champs individuels.

Pour configurer et exécuter l’indexeur, vous pouvez utiliser :

• API REST de la préversion du service de recherche, n’importe quelle version préliminaire.
• Un package Kit de développement logiciel (SDK) Azure, n’importe quelle version.
• Assistant d'importation de données dans le portail Azure.

Conditions préalables

• Azure Files, niveau optimisé pour les transactions.

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

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

• Les fichiers sources traités par l’indexeur Azure Files utilisent la taille de fichier source partagée et les limites de caractères extraites pour les indexeurs de type blob.

• Autorisations de lecture sur stockage Azure. Un chaîne de connexion « accès complet » inclut une clé qui accorde l’accès au contenu.

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

Tâches prises en charge

Vous pouvez utiliser cet indexeur pour les tâches suivantes :

• Indexation des données et indexation incrémentielle : L’indexeur peut indexer des fichiers et des métadonnées associées à partir de tables. Il détecte les fichiers et métadonnées nouveaux et mis à jour par le biais de la détection de modifications intégrée. Vous pouvez configurer l’actualisation des données selon une planification ou à la demande.
• Détection de suppression : L’indexeur peut détecter les suppressions par le biais de métadonnées personnalisées.
• L’IA appliquée via des ensembles de compétences :Skillsets est entièrement prise en charge par l’indexeur. Cela inclut des fonctionnalités clés telles que la vectorisation intégrée qui ajoute des étapes de segmentation et d’incorporation de données.
• Modes d’analyse : L’indexeur prend en charge les modes d’analyse JSON si vous souhaitez analyser des tableaux ou des lignes JSON dans des documents de recherche individuels. Il prend également en charge le mode d’analyse Markdown.
• Compatibilité avec d’autres fonctionnalités : L’indexeur est conçu pour fonctionner en toute transparence avec d’autres fonctionnalités d’indexeur, telles que les sessions de débogage, le cache d’indexeur pour les enrichissements incrémentiels et la base de connaissances.

Formats de document pris en charge

L’indexeur Azure Files peut extraire du texte des formats de document suivants :

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

Comment les Azure Files sont indexées

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 du contenu structuré, tels que JSON ou CSV, qui sont indexés en tant que bloc de texte unique.

Document composé ou incorporé (tel qu’une archive ZIP, un document Word avec un e-mail incorporé Outlook contenant des pièces jointes ou un . Le fichier MSG avec pièces jointes) est également indexé en tant que document unique. Par exemple, toutes les images extraites des pièces jointes d'un fichier .MSG seront retournées dans le champ normalized_images. Si vous avez des images, envisagez d’ajouter l’enrichissement par IA pour obtenir plus d’utilitaire de recherche à partir de ce contenu.

Le contenu textuel d’un document est extrait dans un champ de chaîne nommé « content ». Vous pouvez également extraire des 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 pour identifier les modifications apportées aux données. Une source de données est définie comme une ressource indépendante afin qu’elle puisse être utilisée par plusieurs indexeurs.

Vous pouvez utiliser 2020-06-30-preview ou version ultérieure pour « type » : "azurefile". Nous vous recommandons la dernière API en préversion.

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=2026-08-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 un stockage Azure chaîne de connexion. La section suivante décrit les formats pris en charge.

4. Définissez « conteneur » sur le partage de fichiers racine et utilisez « query » pour spécifier les sous-dossiers.

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.

Identifiants 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 search, 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 des champs de recherche qui stockent le contenu et les métadonnées des fichiers.

   POST /indexes?api-version=2026-04-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 (« clé » : true). Pour le contenu blob, les meilleurs candidats sont les propriétés des métadonnées. Les propriétés de métadonnées incluent souvent des caractères, tels que / et -, qui ne sont pas valides pour les clés de document. L’indexeur encodera automatiquement la propriété de métadonnées de clé, sans configuration ni mappage de champ requis.

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

   • metadata_storage_name utilisable uniquement si les noms sont uniques

   • Propriété de métadonnées personnalisée que vous ajoutez aux objets blob. Cette option nécessite que votre processus de chargement d’objets blob ajoute cette propriété de métadonnées à tous les objets blob. Étant donné que la clé est une propriété requise, tous les objets blob qui manquent une valeur ne sont 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é clé est modifiée.

3. Ajoutez un champ « contenu » pour stocker le texte extrait de chaque fichier via la propriété « content » de l’objet blob. Vous n’êtes pas obligé d’utiliser ce nom, mais cela 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 de fichiers, les propriétés de métadonnées standard sont identiques aux propriétés de métadonnées d’objet blob. L’indexeur Azure Files crée automatiquement des mappages internes de champs pour ces propriétés, qui convertissent les noms de propriétés avec trait d’union en noms de propriétés soulignés. Vous devez toujours ajouter les champs que vous souhaitez utiliser la définition d’index, mais vous pouvez omettre de créer des mappages de champs dans la source de données.

   • metadata_storage_name (Edm.String) : nom de fichier. Par exemple, si vous avez un fichier /my-share/my-folder/subfolder/resume.pdf, la valeur de ce champ est resume.pdf.
   • metadata_storage_path (Edm.String) : URI complet du fichier, y compris 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 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 modifié pour le fichier. Recherche Azure AI utilise cet horodatage pour identifier les fichiers modifiés, afin d’éviter de réindexer tout après l’indexation initiale.
   • metadata_storage_size (Edm.Int64) : taille de fichier en octets.
   • metadata_storage_content_md5 (Edm.String) - Hachage MD5 du contenu du fichier, le cas échéant.
   • 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, car 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 de temps d’exécution.

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

   POST /indexers?api-version=2026-04-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 facultative « configuration », fournissez tous les critères d’inclusion ou d’exclusion. Si elle n’est pas spécifiée, tous les fichiers du partage de fichiers sont récupérés.

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

3. Spécifiez des mappages de champs s’il existe des différences dans le nom ou le type de champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

   Dans l’indexation de fichiers, vous pouvez souvent omettre les correspondances de champs, car l’indexeur dispose d'un support intégré pour mapper les propriétés de « contenu » et de métadonnées à des champs portant des noms et types similaires 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 d’autres propriétés, consultez Créer un indexeur .

Un indexeur s’exécute automatiquement lors de sa création. Vous pouvez empêcher cela en définissant « désactivé » sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le selon une planification.

Vérifier l’état de l’indexeur

Pour surveiller l'état de l'indexeur et l'historique d'exécution, envoyez une requête Get Indexer Status :

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

La réponse inclut l’état et le nombre d’éléments traités. Il 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 des dernières exécutions terminées, triées dans l’ordre chronologique inverse afin que la dernière exécution soit effectuée 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 extrayent du contenu à partir de stockage Azure :

• Détection des modifications et détection de suppression
• Indexer des jeux de données volumineux