Gegevens indexeren uit Azure Data Lake Storage Gen2

Artikel
02/19/2024

In dit artikel leert u hoe u een indexeerfunctie configureert waarmee inhoud uit Azure Data Lake Storage (ADLS) Gen2 wordt geïmporteerd en deze doorzoekbaar maakt in Azure AI Search. Invoer in de indexeerfunctie zijn uw blobs, in één container. Uitvoer is een zoekindex met doorzoekbare inhoud en metagegevens die zijn opgeslagen in afzonderlijke velden.

Dit artikel is een aanvulling op Een indexeerfunctie maken met informatie die specifiek is voor indexering vanuit ADLS Gen2. Hierbij worden de REST API's gebruikt om een driedelige werkstroom te demonstreren die gebruikelijk is voor alle indexeerfuncties: een gegevensbron maken, een index maken, een indexeerfunctie maken. Gegevensextractie vindt plaats wanneer u de aanvraag Indexeerfunctie maken verzendt.

Zie Index Data Lake Gen2 met behulp van Microsoft Entra-id op GitHub voor een codevoorbeeld in C#.

Vereisten

ADLS Gen2 waarvoor hiërarchische naamruimte is ingeschakeld. ADLS Gen2 is beschikbaar via Azure Storage. Bij het instellen van een opslagaccount kunt u hiërarchische naamruimte inschakelen, bestanden ordenen in een hiërarchie van mappen en geneste submappen. Door een hiërarchische naamruimte in te schakelen, schakelt u ADLS Gen2 in.
Toegangslagen voor ADLS Gen2 zijn dynamisch, statisch en archief. Alleen hot en cool kunnen worden geopend door zoekindexeerfuncties.
Blobs met tekst. Als u binaire gegevens hebt, kunt u AI-verrijking opnemen voor afbeeldingsanalyse. Blob-inhoud kan de indexeerlimieten voor uw zoekservicelaag niet overschrijden.
Leesmachtigingen voor Azure Storage. Een 'volledige toegang' verbindingsreeks bevat een sleutel die toegang verleent tot de inhoud, maar als u in plaats daarvan Azure-rollen gebruikt, moet u ervoor zorgen dat de beheerde identiteit van de zoekservice machtigingen heeft voor opslagblobgegevenslezer.
Gebruik een REST-client om REST-aanroepen te formuleren die vergelijkbaar zijn met de aanroepen die in dit artikel worden weergegeven.

Notitie

ADLS Gen2 implementeert een toegangsbeheermodel dat ondersteuning biedt voor op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) en POSIX-achtige toegangsbeheerlijsten (ACL's) op blobniveau. Azure AI Search biedt geen ondersteuning voor machtigingen op documentniveau. Alle gebruikers hebben hetzelfde toegangsniveau voor alle doorzoekbare en ophaalbare inhoud in de index. Als machtigingen op documentniveau een toepassingsvereiste zijn, kunt u beveiligingsbeperkingen overwegen als een mogelijke oplossing.

Ondersteunde documentindelingen

De ADLS Gen2-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 (e-mailberichten van Outlook), XML (zowel 2003 als 2006 WORD XML)
Documentindelingen openen: ODT, ODS, ODP
PDF
Tekstbestanden zonder opmaak (zie ook Indexering van tekst zonder opmaak)
RTF
XML
ZIP

Bepalen welke blobs moeten worden geïndexeerde

Voordat u indexering instelt, controleert u de brongegevens om te bepalen of er wijzigingen vooraf 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 een indexeerfunctiegegevensbron bevat een queryparameter 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 op bestandstype. De lijst met ondersteunde documentindelingen kan u helpen bepalen welke blobs moeten worden uitgesloten. 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 om welke reden dan ook een specifieke blob 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.

Eigenschapsnaam	Eigenschapwaarde	Uitleg
"AzureSearch_Skip"	`"true"`	Hiermee geeft u de blob-indexeerfunctie de opdracht om de blob volledig over te slaan. Er wordt niet geprobeerd om metagegevens te extraheren of inhoud te extraheren. Dit is handig wanneer een bepaalde blob herhaaldelijk mislukt en het indexeringsproces onderbreekt.
"AzureSearch_SkipContent"	`"true"`	Slaat inhoud over en extraheert alleen de metagegevens. dit komt overeen met de `"dataToExtract" : "allMetadata"` instelling die wordt beschreven in configuratie-instellingen , alleen gericht op een bepaalde blob.

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

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

Blobmetagegevens indexeren

Blobmetagegevens kunnen ook worden geïndexeerd en dat is handig als u denkt dat een van de standaard- of aangepaste metagegevenseigenschappen nuttig is in filters en query's.

Door de gebruiker opgegeven metagegevenseigenschappen worden exacte bewoordingen 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 Sensitivity met waarde Highheeft, moet u een veld definiëren met de naam Sensitivity in uw zoekindex en wordt deze gevuld met de waarde High.

Standaardeigenschappen voor blobmetagegevens kunnen worden geëxtraheerd in op dezelfde manier benoemde en getypte velden, 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 onderstrepingsteken equivalente naam ('metadata_storage_name').

U moet nog steeds de onderstrepingstekenvelden 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) - laatste wijzigingstijdstempel voor de blob. Azure AI Search gebruikt deze tijdstempel om gewijzigde blobs te identificeren, om te voorkomen dat alles na de eerste indexering opnieuw wordt geïndexeerde.
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 metagegevenseigenschappen die specifiek zijn voor de documentindeling van de blobs die u indexeert, ook worden weergegeven in het indexschema. Zie eigenschappen voor inhoudsmetagegevens voor meer informatie over inhoudsspecifieke metagegevens.

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

De gegevensbron definiëren

De definitie van de gegevensbron geeft de gegevens op die moeten worden geïndexeerde, 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-adlsgen2-datasource",
    "type" : "adlsgen2",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Stel 'type' in op "adlsgen2" (vereist).
Ingesteld "credentials" op een Azure Storage-verbindingsreeks. In de volgende sectie worden de ondersteunde indelingen beschreven.
Stel "container" deze 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 verbindingsreeks s

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

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

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

Shared Access Signature** (SAS) voor opslagaccounts verbindingsreeks
`{ "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).

Notitie

Als u SAS-referenties gebruikt, moet u de referenties van de gegevensbron periodiek bijwerken met vernieuwde handtekeningen om te voorkomen dat deze verlopen. Als SAS-referenties verlopen, mislukt de indexeerfunctie met een foutbericht dat lijkt op 'Referenties die zijn opgegeven in de verbindingsreeks ongeldig zijn of zijn 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 waarmee blobinhoud en metagegevens worden opgeslagen:

{
    "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': true'). Voor blob-inhoud zijn de beste kandidaten metagegevenseigenschappen.
- 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 u naar "key": true deze velddefinitie.
- Een aangepaste metagegevenseigenschap die u toevoegt aan blobs. Deze optie vereist dat uw blobuploadproces die metagegevenseigenschap toevoegt aan alle blobs. Omdat de sleutel een vereiste eigenschap is, kunnen blobs die een waarde missen, niet worden geïndexeerd. Als u een aangepaste metagegevenseigenschap als sleutel gebruikt, moet u geen wijzigingen aanbrengen in die eigenschap. Indexeerfuncties voegen dubbele documenten toe voor dezelfde blob als de sleuteleigenschap wordt gewijzigd.
Metagegevenseigenschappen bevatten vaak tekens, zoals / en -, die ongeldig zijn voor documentsleutels. Omdat de indexeerfunctie een eigenschap base64EncodeKeys heeft (standaard true), codeert deze automatisch de metagegevenseigenschap, zonder dat er 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 hiermee kunt u gebruikmaken van impliciete veldtoewijzingen.
Voeg velden toe voor standaardmetagegevenseigenschappen. De indexeerfunctie kan aangepaste metagegevenseigenschappen, standaardmetagegevenseigenschappen en inhoudsspecifieke metagegevenseigenschappen lezen.

De ADLS Gen2-indexeerfunctie configureren en uitvoeren

Zodra de index en de gegevensbron zijn gemaakt, kunt u de indexeerfunctie maken. De configuratie van de indexeerfunctie geeft de invoer, parameters en eigenschappen aan die het gedrag van de uitvoeringstijd regelen. U kunt ook opgeven welke delen van een blob u wilt indexeren.

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

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

Stel batchSize in als de standaardwaarde (10 documenten) onder het gebruik of overweldigende beschikbare resources valt. Standaard batchgrootten zijn gegevensbronspecifiek. Blob-indexering stelt de batchgrootte in op 10 documenten in de herkenning van de grotere gemiddelde documentgrootte.
Bepaal onder Configuratie welke blobs worden geïndexeerd op basis van bestandstype of laat u niet opgegeven om alle blobs op te halen.

Geef "indexedFileNameExtensions"een door komma's gescheiden lijst met bestandsextensies op (met een voorlooppunt). Doe hetzelfde om "excludedFileNameExtensions" aan te geven welke extensies moeten worden overgeslagen. Als dezelfde extensie zich in beide lijsten bevindt, wordt deze uitgesloten van indexering.
Stel onder Configuratie 'dataToExtract' in om te bepalen welke onderdelen 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 standaardblobeigenschappen en metagegevens voor gevonden inhoudstypen worden geëxtraheerd uit de blob-inhoud en geïndexeerd.
Stel onder Configuratie '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 het indexeren van blobs kunt u veldtoewijzingen vaak weglaten omdat de indexeerfunctie ingebouwde ondersteuning heeft voor het toewijzen van de eigenschappen 'inhoud' en metagegevens aan velden met vergelijkbare namen en getypte velden in een index. Voor eigenschappen van metagegevens 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 waar. Als u de uitvoering van de indexeerfunctie wilt beheren, voert u een indexeerfunctie op aanvraag uit of plaatst u deze in een schema.

De status van de indexeerfunctie controleren

Als u de status en uitvoeringsgeschiedenis van de indexeerfunctie wilt controleren, verzendt u een get-indexeerstatusaanvraag :

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

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

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

De uitvoeringsgeschiedenis bevat maximaal 50 van de laatst voltooide uitvoeringen, die in de omgekeerde chronologische volgorde worden gesorteerd, zodat de laatste uitvoering als eerste wordt uitgevoerd.

Afhandeling van fouten

Fouten die vaak optreden tijdens het indexeren, zijn niet-ondersteunde inhoudstypen, ontbrekende inhoud of oversized blobs.

Standaard stopt de blob-indexeerfunctie zodra er een blob met een niet-ondersteund inhoudstype (bijvoorbeeld een audiobestand) optreedt. U kunt de parameter excludedFileNameExtensions gebruiken om bepaalde inhoudstypen over te slaan. Het is echter mogelijk dat indexering wordt voortgezet, zelfs als er fouten optreden en later fouten opsporen in afzonderlijke documenten. Zie richtlijnen voor het oplossen van problemen met indexeerfuncties en indexeerfunctiefouten en waarschuwingen voor meer informatie over indexeerfouten.

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

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

Parameter	Geldige waarden	Beschrijving
"maxFailedItems"	-1, null of 0, positief geheel getal	Ga door met indexeren als er fouten optreden op elk moment van verwerking, ofwel 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 het toestaan van `-1` verwerking, ongeacht het aantal fouten. 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	Oversized blobs worden standaard behandeld als fouten. Als u deze parameter instelt op true, probeert de indexeerfunctie de metagegevens ervan te indexeren, zelfs als de inhoud niet kan worden geïndexeerd. Zie Servicelimieten voor limieten voor blobgrootten.

Beperkingen

In tegenstelling tot blob-indexeerfuncties kunnen ADLS Gen2-indexeerfuncties geen SAS-tokens op containerniveau gebruiken voor het inventariseren en indexeren van inhoud uit een opslagaccount. Dit komt doordat de indexeerfunctie een controle uitvoert om te bepalen of het opslagaccount hiërarchische naamruimten heeft ingeschakeld door het bestandssysteem aan te roepen - Eigenschappen-API ophalen. Voor opslagaccounts waarbij hiërarchische naamruimten niet zijn ingeschakeld, wordt klanten in plaats daarvan aangeraden blobindexeerfuncties te gebruiken om een goed presterende opsomming van blobs te garanderen.
Als de eigenschap metadata_storage_path is toegewezen als het indexsleutelveld, worden blobs niet gegarandeerd opnieuw geïndexeerd na de naam van een map. Als u de blobs die deel uitmaken van de hernoemde mappen opnieuw wilt indexeren, werkt u de LastModified tijdstempels voor alle blobs bij.

Volgende stappen

U kunt nu de indexeerfunctie uitvoeren, de status bewaken of de uitvoering van de indexeerfunctie plannen. De volgende artikelen zijn van toepassing op indexeerfuncties die inhoud ophalen uit Azure Storage: