Gegevens uit Azure Blob Storage indexeren

Artikel
03/23/2023
13 minuten om te lezen

In dit artikel leert u hoe u een indexeerfunctie configureert die inhoud importeert uit Azure Blob Storage en deze doorzoekbaar maakt in Azure Cognitive Search. Invoer voor de indexeerfunctie zijn uw blobs, in één container. Uitvoer is een zoekindex met doorzoekbare inhoud en metagegevens die zijn opgeslagen in afzonderlijke velden.

In dit artikel wordt Een indexeerfunctie maken aangevuld met informatie die specifiek is voor Blob Storage. De REST API's worden gebruikt om een driedelige werkstroom te demonstreren die alle indexeerfuncties gemeen hebben: een gegevensbron maken, een index maken, een index maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken indient.

Blob-indexeerfuncties worden vaak gebruikt voor zowel AI-verrijking als tekstverwerking. Dit artikel is gericht op indexeerfuncties voor op tekst gebaseerde indexering, waarbij alleen de tekstinhoud en metagegevens worden opgenomen voor zoekscenario's in volledige tekst.

Vereisten

Azure Blob Storage, Standaardprestaties (algemeen gebruik v2).
Toegangslagen voor Blob Storage zijn Dynamisch, Statisch en Archief. Alleen dynamisch en statisch zijn toegankelijk voor zoekindexeerfuncties.
Blobs met tekstinhoud en metagegevens. Als blobs binaire inhoud of ongestructureerde tekst bevatten, kunt u ai-verrijking toevoegen voor de verwerking van afbeeldingen en natuurlijke taal. Blob-inhoud mag de limieten voor de indexeerfunctie voor uw zoekservicelaag niet overschrijden.
Een ondersteunde netwerkconfiguratie en gegevenstoegang. U hebt minimaal leesmachtigingen nodig in Azure Storage. Een opslag-connection string met een toegangssleutel geeft u leestoegang tot opslaginhoud. Als u in plaats daarvan Azure AD aanmeldingen en rollen gebruikt, moet u ervoor zorgen dat de beheerde identiteit van de zoekservice machtigingen voor lezer voor opslagblobgegevens heeft.

Standaard accepteren zowel zoeken als opslag aanvragen van openbare IP-adressen. Als netwerkbeveiliging niet direct een probleem is, kunt u blobgegevens indexeren met alleen de connection string- en leesmachtigingen. Wanneer u klaar bent om netwerkbeveiligingen toe te voegen, raadpleegt u Toegang van indexeerfunctie tot inhoud die wordt beveiligd door Azure-netwerkbeveiligingsfuncties voor hulp bij gegevenstoegang.
Gebruik een REST-client, zoals de Postman-app, als u REST-aanroepen wilt formuleren die vergelijkbaar zijn met de aanroepen die in dit artikel worden weergegeven.

Ondersteunde documentindelingen

De blob-indexeerfunctie kan tekst extraheren uit de volgende documentindelingen:

CSV (zie CSV-blobs indexeren)
EML
EPUB
GZ
HTML
JSON (zie JSON-blobs indexeren)
KML (XML voor geografische weergaven)
Microsoft Office-indelingen: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook-e-mails), XML (zowel 2003 als 2006 WORD XML)
Documentindelingen openen: ODT, ODS, ODP
PDF
Tekstbestanden zonder opmaak (zie ook Tekst zonder opmaak indexeren)
RTF
XML
ZIP

Bepalen welke blobs u wilt indexeren

Voordat u indexeren instelt, controleert u de brongegevens om te bepalen of er vooraf wijzigingen moeten worden aangebracht. Een indexeerfunctie kan inhoud van één container tegelijk indexeren. Standaard worden alle blobs in de container verwerkt. U hebt verschillende opties voor meer selectieve verwerking:

Plaats blobs in een virtuele map. Een definitie van de gegevensbron van een indexeerfunctie bevat een 'query'-parameter die een virtuele map kan gebruiken. Als u een virtuele map opgeeft, worden alleen die blobs in de map geïndexeerd.
Blobs opnemen of uitsluiten per bestandstype. De lijst met ondersteunde documentindelingen kan u helpen bepalen welke blobs u wilt uitsluiten. U kunt bijvoorbeeld afbeeldings- of audiobestanden uitsluiten die geen doorzoekbare tekst bieden. Deze mogelijkheid wordt beheerd via configuratie-instellingen in de indexeerfunctie.

Willekeurige blobs opnemen of uitsluiten. Als u een specifieke blob om welke reden dan ook wilt overslaan, kunt u de volgende metagegevenseigenschappen en -waarden toevoegen aan blobs in Blob Storage. Wanneer een indexeerfunctie deze eigenschap tegenkomt, wordt de blob of de inhoud ervan in de indexeringsuitvoering overgeslagen.

Naam van eigenschap	Eigenschapswaarde	Uitleg
"AzureSearch_Skip"	`"true"`	Geeft de blob-indexeerfunctie de opdracht om de blob volledig over te slaan. Er wordt geen poging uitgevoerd om metagegevens of inhoud te extraheren. Dit is handig wanneer een bepaalde blob herhaaldelijk mislukt en het indexeringsproces onderbreekt.
"AzureSearch_SkipContent"	`"true"`	Inhoud overslaan en alleen de metagegevens worden geëxtraheerd. dit komt overeen met de `"dataToExtract" : "allMetadata"` instelling die wordt beschreven in configuratie-instellingen , alleen gericht op een bepaalde blob.

Als u geen opname- of uitsluitingscriteria instelt, rapporteert de indexeerfunctie een niet in aanmerking komende blob als een fout en gaat verder. Als er voldoende fouten optreden, kan de verwerking worden gestopt. U kunt fouttolerantie opgeven in de configuratie-instellingen van de indexeerfunctie.

Een indexeerfunctie maakt doorgaans één zoekdocument per blob, waarin de tekstinhoud en metagegevens worden vastgelegd als doorzoekbare velden in een index. Als blobs hele bestanden zijn, kunt u deze mogelijk parseren in meerdere zoekdocumenten. U kunt bijvoorbeeld rijen in een CSV-bestand parseren om één zoekdocument per rij te maken.

Blobmetagegevens indexeren

Blob-metagegevens kunnen ook worden geïndexeerd. Dit is handig als u denkt dat een van de standaardeigenschappen of aangepaste metagegevens van pas komt in filters en query's.

Eigenschappen van door de gebruiker opgegeven metagegevens worden letterlijk geëxtraheerd. Als u de waarden wilt ontvangen, moet u het veld definiëren in de zoekindex van het type Edm.String, met dezelfde naam als de metagegevenssleutel van de blob. Als een blob bijvoorbeeld een metagegevenssleutel heeft van Sensitivity met waarde High, moet u een veld met de naam Sensitivity definiëren in uw zoekindex en wordt dit ingevuld met de waarde High.

Eigenschappen van standaardblobmetagegevens kunnen worden geëxtraheerd in velden met een vergelijkbare naam en type, zoals hieronder wordt vermeld. De blob-indexeerfunctie maakt automatisch interne veldtoewijzingen voor deze eigenschappen van blobmetagegevens, waarbij de oorspronkelijke naam met afbreekstreepjes ('metadata-storage-name') wordt geconverteerd naar een equivalente naam met onderstreping ('metadata_storage_name').

U moet nog steeds de onderstrepingsvelden toevoegen aan de indexdefinitie, maar u kunt veldtoewijzingen weglaten omdat de indexeerfunctie de koppeling automatisch maakt.

metadata_storage_name (Edm.String): de bestandsnaam van de blob. Als u bijvoorbeeld een blob /my-container/my-folder/submap/resume.pdf hebt, is resume.pdfde waarde van dit veld .
metadata_storage_path (Edm.String): de volledige URI van de blob, inclusief het opslagaccount. Bijvoorbeeld: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String): inhoudstype zoals opgegeven door de code die u hebt gebruikt om de blob te uploaden. Bijvoorbeeld application/octet-stream.
metadata_storage_last_modified (Edm.DateTimeOffset): tijdstempel voor de laatste wijziging voor de blob. Azure Cognitive Search gebruikt deze tijdstempel om gewijzigde blobs te identificeren, om te voorkomen dat alles opnieuw wordt geïndexeerd na de eerste indexering.
metadata_storage_size (Edm.Int64): blobgrootte in bytes.
metadata_storage_content_md5 (Edm.String): MD5-hash van de blobinhoud, indien beschikbaar.
metadata_storage_sas_token (Edm.String): een tijdelijk SAS-token dat kan worden gebruikt door aangepaste vaardigheden om toegang te krijgen tot de blob. Dit token mag niet worden opgeslagen voor later gebruik, omdat het mogelijk verloopt.

Ten slotte kunnen eigenschappen van metagegevens die specifiek zijn voor de documentindeling van de blobs die u indexeert, ook worden weergegeven in het indexschema. Zie Eigenschappen van inhoudsmetagegevens voor meer informatie over inhoudsspecifieke metagegevens.

Het is belangrijk om erop te wijzen dat u geen velden hoeft te definiëren voor alle bovenstaande eigenschappen in uw zoekindex. Leg alleen de eigenschappen vast die u nodig hebt voor uw toepassing.

De gegevensbron definiëren

De definitie van de gegevensbron specificeert de te indexeren gegevens, referenties en beleidsregels voor het identificeren van wijzigingen in de gegevens. Een gegevensbron wordt gedefinieerd als een onafhankelijke resource, zodat deze kan worden gebruikt door meerdere indexeerfuncties.

Een gegevensbron maken of bijwerken om de definitie ervan in te stellen:

{
    "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>" }
}

Stel 'type' in op "azureblob" (vereist).
Stel 'referenties' in op een Azure Storage-connection string. In de volgende sectie worden de ondersteunde indelingen beschreven.
Stel 'container' in op de blobcontainer en gebruik 'query' om submappen op te geven.

Een definitie van een gegevensbron kan ook beleid voor voorlopig verwijderen bevatten, als u wilt dat de indexeerfunctie een zoekdocument verwijdert wanneer het brondocument wordt gemarkeerd voor verwijdering.

Ondersteunde referenties en verbindingsreeksen

Indexeerfuncties kunnen verbinding maken met een blobcontainer met behulp van de volgende verbindingen.

Opslagaccounts met volledige toegang connection string
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
U kunt de connection string ophalen op de pagina Opslagaccount in Azure Portal door Toegangstoetsen te selecteren in het linkernavigatiedeelvenster. Zorg ervoor dat u een volledige connection string selecteert en niet alleen een sleutel.

Beheerde identiteit connection string
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Voor deze connection string is geen accountsleutel vereist, maar u moet eerder een zoekservice hebben geconfigureerd om verbinding te maken met behulp van een beheerde identiteit.

Sas-connection string (Shared Access Signature) voor opslagaccounts
`{ "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;" }`
De SAS moet de lijst- en leesmachtigingen hebben voor containers en objecten (in dit geval blobs).

Handtekening voor gedeelde toegang tot container
`{ "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;" }`
De SAS moet de lijst- en leesmachtigingen voor de container hebben. Zie Shared Access Signatures gebruiken voor meer informatie.

Notitie

Als u SAS-referenties gebruikt, moet u de referenties van de gegevensbron regelmatig bijwerken met vernieuwde handtekeningen om te voorkomen dat ze verlopen. Als SAS-referenties verlopen, mislukt de indexeerfunctie met een foutbericht dat lijkt op 'Referenties die zijn opgegeven in de connection string zijn ongeldig of verlopen'.

Zoekvelden toevoegen aan een index

Voeg in een zoekindex velden toe om de inhoud en metagegevens van uw Azure-blobs te accepteren.

Een index maken of bijwerken om zoekvelden te definiëren die blobinhoud en metagegevens opslaan:

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 },        
    ]
  }
}

Maak een documentsleutelveld ('sleutel': waar).) Voor blob-inhoud zijn metagegevenseigenschappen de beste kandidaten.
- metadata_storage_path (standaard) volledig pad naar het object of bestand. Het sleutelveld ('ID' in dit voorbeeld) wordt gevuld met waarden uit metadata_storage_path omdat dit de standaardwaarde is.
- metadata_storage_name, alleen bruikbaar als namen uniek zijn. Als u dit veld als sleutel wilt gebruiken, gaat "key": true u naar deze velddefinitie.
- Een aangepaste metagegevenseigenschap die u toevoegt aan blobs. Deze optie vereist dat uw blob-uploadproces die metagegevenseigenschap toevoegt aan alle blobs. Omdat de sleutel een vereiste eigenschap is, worden blobs waarvoor een waarde ontbreekt, niet geïndexeerd. Als u een aangepaste metagegevenseigenschap als sleutel gebruikt, moet u voorkomen dat u wijzigingen aanbrengt in die eigenschap. Indexeerfuncties voegen dubbele documenten toe voor dezelfde blob als de sleuteleigenschap verandert.
Eigenschappen van metagegevens bevatten vaak tekens, zoals / en -, die ongeldig zijn voor documentsleutels. Omdat de indexeerfunctie de eigenschap base64EncodeKeys heeft (standaard waar), wordt automatisch de eigenschap metagegevens gecodeerd, zonder dat er een configuratie of veldtoewijzing is vereist.
Voeg een 'inhoudsveld' toe om geëxtraheerde tekst uit elk bestand op te slaan via de eigenschap 'inhoud' van de blob. U hoeft deze naam niet te gebruiken, maar als u dit doet, kunt u profiteren van impliciete veldtoewijzingen.
Voeg velden toe voor standaardeigenschappen van metagegevens. De indexeerfunctie kan aangepaste metagegevenseigenschappen, standaardeigenschappen voor metagegevens en inhoudsspecifieke metagegevenseigenschappen lezen.

De blobindexeerfunctie configureren en uitvoeren

Zodra de index en gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen op die het gedrag van de runtime beheren. U kunt ook opgeven welke onderdelen van een blob moeten worden geïndexeert.

Maak of werk een indexeerfunctie bij door deze een naam te geven en te verwijzen naar de gegevensbron en doelindex:

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" : [ ]
}

Stel in batchSize als de standaardwaarde (10 documenten) onderbenutte of overweldigende beschikbare resources is. Standaardbatchgrootten zijn gegevensbronspecifiek. Blob-indexering stelt de batchgrootte in op 10 documenten ter erkenning van de grotere gemiddelde documentgrootte.
Bepaal onder 'configuratie' welke blobs worden geïndexeerd op basis van bestandstype, of laat dit niet opgegeven om alle blobs op te halen.

Geef voor "indexedFileNameExtensions"een door komma's gescheiden lijst met bestandsextensies op (met een voorlooppunt). Doe hetzelfde voor "excludedFileNameExtensions" om aan te geven welke extensies moeten worden overgeslagen. Als dezelfde extensie in beide lijsten voorkomt, wordt deze uitgesloten van indexering.
Stel onder 'configuratie' 'dataToExtract' in om te bepalen welke delen van de blobs worden geïndexeerd:
- 'contentAndMetadata' geeft aan dat alle metagegevens en tekstuele inhoud die uit de blob is geëxtraheerd, worden geïndexeerd. Dit is de standaardwaarde.
- 'storageMetadata' geeft aan dat alleen de standaard blobeigenschappen en door de gebruiker opgegeven metagegevens worden geïndexeerd.
- 'allMetadata' geeft aan dat standaard blobeigenschappen en eventuele metagegevens voor gevonden inhoudstypen worden geëxtraheerd uit de blob-inhoud en geïndexeerd.
Stel onder 'configuration' 'parsingMode' in als blobs moeten worden toegewezen aan meerdere zoekdocumenten of als ze bestaan uit tekst zonder opmaak, JSON-documenten of CSV-bestanden.
Geef veldtoewijzingen op als er verschillen zijn in veldnaam of -type, of als u meerdere versies van een bronveld in de zoekindex nodig hebt.

Bij blobindexering kunt u veldtoewijzingen vaak weglaten, omdat de indexeerfunctie ingebouwde ondersteuning biedt voor het toewijzen van de eigenschappen 'inhoud' en metagegevens aan velden met namen en typen in een index. Voor metagegevenseigenschappen vervangt de indexeerfunctie automatisch afbreekstreepjes - door onderstrepingstekens in de zoekindex.
Zie Een indexeerfunctie maken voor meer informatie over andere eigenschappen. Zie Blob-configuratieparameters in de REST API voor de volledige lijst met parameterbeschrijvingen.

Een indexeerfunctie wordt automatisch uitgevoerd wanneer deze wordt gemaakt. U kunt dit voorkomen door 'uitgeschakeld' in te stellen op true. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze volgens een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt bewaken, verzendt u een aanvraag Om de status van de indexeerfunctie op te halen :

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

Het antwoord bevat de status en het aantal verwerkte items. Dit moet er ongeveer uitzien als in het volgende voorbeeld:

    {
        "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
        ]
    }

Uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in omgekeerde chronologische volgorde zijn gesorteerd, zodat de meest recente uitvoering als eerste wordt uitgevoerd.

Fouten verwerken

Fouten die vaak optreden tijdens het indexeren zijn onder andere niet-ondersteunde inhoudstypen, ontbrekende inhoud of te grote blobs.

Standaard stopt de blob-indexeerfunctie zodra deze een blob met een niet-ondersteund inhoudstype (bijvoorbeeld een audiobestand) tegenkomt. U kunt de parameter excludedFileNameExtensions gebruiken om bepaalde inhoudstypen over te slaan. Het is echter mogelijk dat u wilt indexeren om door te gaan, zelfs als er fouten optreden, en vervolgens later fouten in afzonderlijke documenten op te sporen. Zie Richtlijnen voor het oplossen van problemen met indexeerfuncties en Indexer-fouten en -waarschuwingen voor meer informatie over indexeerfouten.

Er zijn vijf eigenschappen van de indexeerfunctie die het antwoord van de indexeerfunctie bepalen wanneer er fouten optreden.

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

Parameter	Geldige waarden	Description
"maxFailedItems"	-1, null of 0, positief geheel getal	Ga door met indexeren als er fouten optreden op een bepaald verwerkingspunt, tijdens het parseren van blobs of tijdens het toevoegen van documenten aan een index. Stel deze eigenschappen in op het aantal acceptabele fouten. Een waarde van `-1` staat verwerking toe, ongeacht het aantal fouten dat optreedt. Anders is de waarde een positief geheel getal.
"maxFailedItemsPerBatch"	-1, null of 0, positief geheel getal	Hetzelfde als hierboven, maar wordt gebruikt voor batchindexering.
"failOnUnsupportedContentType"	waar of onwaar	Als de indexeerfunctie het inhoudstype niet kan bepalen, geeft u op of de taak moet worden voortgezet of mislukt.
"failOnUnprocessableDocument"	waar of onwaar	Als de indexeerfunctie een document van een anderszins ondersteund inhoudstype niet kan verwerken, geeft u op of de taak moet worden voortgezet of mislukt.
"indexStorageMetadataOnlyForOversizedDocuments"	waar of onwaar	Te grote blobs worden standaard behandeld als fouten. Als u deze parameter instelt op true, probeert de indexeerfunctie de metagegevens te indexeren, zelfs als de inhoud niet kan worden geïndexeerd. Zie Servicelimieten voor limieten voor blobgrootte.

Volgende stappen

U kunt nu bepalen hoe u de indexeerfunctie uitvoert, de status bewaakt of de uitvoering van de indexeerfunctie plant. De volgende artikelen zijn van toepassing op indexeerfuncties die inhoud ophalen uit Azure Storage: