Indexer des données à partir du Stockage Blob Azure

Article
03/18/2024

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu à partir du Stockage Blob Azure et le rend accessible à la recherche dans Azure AI Search. 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 vient en complément de l’article Créer un indexeur avec des informations spécifiques au Stockage Blob. 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.

Les indexeurs de blobs sont fréquemment utilisés pour l’enrichissement par IA et le traitement basé sur du texte. Cet article se concentre sur les indexeurs pour l’indexation basée sur le texte, où seuls le contenu textuel et les métadonnées sont ingérés pour les scénarios de recherche en texte intégral.

Prérequis

Stockage Blob Azure, niveau de performance Standard (v2 universel).
Les niveaux d’accès au service Stockage Blob sont chaud, froid et archive. Les indexeurs de recherche ne peuvent accéder qu’aux niveaux chaud et froid.
Objets blob fournissant du contenu et des métadonnées de texte. Si les objets blob contiennent du contenu binaire ou du texte non structuré, envisagez d’ajouter l’enrichissement par IA pour le traitement de l’image et du langage naturel. Le contenu d’un objet blob ne doit pas dépasser les limites de l’indexeur pour votre niveau de service de recherche.
Une configuration réseau et un accès aux données pris en charge. Au minimum, vous avez besoin d’autorisations de lecture dans le Stockage Azure. Une chaîne de connexion de stockage qui inclut une clé d’accès vous donne un accès en lecture au contenu de stockage. Si vous utilisez plutôt des connexions et des rôles Microsoft Entra, vérifiez que l’identité managée du service de recherche dispose des autorisations Lecteur des données blob du stockage.

Par défaut, la recherche et le stockage acceptent les requêtes provenant d’adresses IP publiques. Si la sécurité réseau n’est pas une préoccupation immédiate, vous pouvez indexer les données d’objet blob à l’aide de la chaîne de connexion et des autorisations de lecture. Lorsque vous êtes prêt à ajouter des protections réseau, consultez Accès de l’indexeur au contenu protégé par les fonctionnalités de sécurité réseau Azure pour obtenir des conseils sur l’accès aux données.
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 d’objets blob 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.

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.

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 sont 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 fait 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.

Actuellement, l’indexation des balises d’index blob n’est pas prise en charge par cet indexeur.

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-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Définissez « type » sur "azureblob" (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).

Signature d’accès partagé du conteneur
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
La SAP doit avoir les autorisations de liste et lecture sur le conteneur. Pour plus d’informations, consultez Utilisation des signatures d’accès partagé.

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 :

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
{
    "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, tels que / 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 blob

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 :

POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-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) représente trop ou trop peu par rapport aux ressources disponibles. 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 ». Le mode d’analyse par défaut est un document de recherche par blob. Si les blob sont du texte brut, vous pouvez obtenir de meilleures performances en passant à l’analyse de texte brut. Si vous avez besoin d’une analyse plus granulaire qui mappe des blob à plusieurs documents de recherche, spécifiez un autre mode. L’analyse un-à-plusieurs est prise en charge pour les blob constitués des éléments suivants :
- Documents JSON
- 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=2020-06-30
  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.

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=2020-06-30
{
  "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.