Indexdata från Azure Data Lake Storage Gen2

Artikel
02/19/2024

I den här artikeln får du lära dig hur du konfigurerar en indexerare som importerar innehåll från Azure Data Lake Storage (ADLS) Gen2 och gör det sökbart i Azure AI Search. Indata till indexeraren är dina blobar i en enda container. Utdata är ett sökindex med sökbart innehåll och metadata som lagras i enskilda fält.

Den här artikeln kompletterar Skapa en indexerare med information som är specifik för indexering från ADLS Gen2. Den använder REST-API:er för att demonstrera ett arbetsflöde i tre delar som är gemensamt för alla indexerare: skapa en datakälla, skapa ett index, skapa en indexerare. Dataextrahering sker när du skickar begäran skapa indexerare.

Ett kodexempel i C# finns i Index Data Lake Gen2 using Microsoft Entra ID on GitHub (Index Data Lake Gen2 using Microsoft Entra ID on GitHub).

Förutsättningar

ADLS Gen2 med hierarkiskt namnområde aktiverat. ADLS Gen2 är tillgängligt via Azure Storage. När du konfigurerar ett lagringskonto kan du aktivera hierarkiskt namnområde, ordna filer i en hierarki med kataloger och kapslade underkataloger. Genom att aktivera ett hierarkiskt namnområde aktiverar du ADLS Gen2.
Åtkomstnivåer för ADLS Gen2 omfattar frekvent, lågfrekvent och arkiv. Endast frekvent och lågfrekvent kan nås av sökindexerare.
Blobbar som innehåller text. Om du har binära data kan du inkludera AI-berikning för bildanalys. Blobinnehåll får inte överskrida indexeringsgränserna för söktjänstnivån.
Läsbehörigheter för Azure Storage. En "fullständig åtkomst" anslutningssträng innehåller en nyckel som ger åtkomst till innehållet, men om du använder Azure-roller i stället kontrollerar du att söktjänstens hanterade identitet har behörigheter för Storage Blob Data Reader.
Använd en REST-klient för att formulera REST-anrop som liknar dem som visas i den här artikeln.

Kommentar

ADLS Gen2 implementerar en åtkomstkontrollmodell som stöder både rollbaserad åtkomstkontroll i Azure (Azure RBAC) och POSIX-liknande åtkomstkontrollistor (ACL: er) på blobnivå. Azure AI Search stöder inte behörigheter på dokumentnivå. Alla användare har samma åtkomstnivå till allt sökbart och hämtningsbart innehåll i indexet. Om behörigheter på dokumentnivå är ett programkrav bör du överväga säkerhetstrimning som en potentiell lösning.

Dokumentformat som stöds

ADLS Gen2-indexeraren kan extrahera text från följande dokumentformat:

CSV (se Indexering av CSV-blobar)
EML
EPUB
GZ
HTML
JSON (se Indexering av JSON-blobar)
KML (XML för geografiska representationer)
Microsoft Office-format: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook-e-post), XML (både 2003 och 2006 WORD XML)
Öppna dokumentformat: ODT, ODS, ODP
PDF
Oformaterade textfiler (se även Indexering av oformaterad text)
RTF
XML
ZIP

Avgöra vilka blobar som ska indexeras

Innan du konfigurerar indexering granskar du dina källdata för att avgöra om några ändringar ska göras i förväg. En indexerare kan indexeras från en container i taget. Som standard bearbetas alla blobar i containern. Du har flera alternativ för mer selektiv bearbetning:

Placera blobar i en virtuell mapp. En definition av indexerarens datakälla innehåller en frågeparameter som kan ta en virtuell mapp. Om du anger en virtuell mapp indexeras endast dessa blobar i mappen.
Inkludera eller exkludera blobar efter filtyp. Listan med dokumentformat som stöds kan hjälpa dig att avgöra vilka blobar som ska undantas. Du kanske till exempel vill exkludera bild- eller ljudfiler som inte tillhandahåller sökbar text. Den här funktionen styrs via konfigurationsinställningarna i indexeraren.

Inkludera eller exkludera godtyckliga blobar. Om du vill hoppa över en specifik blob av någon anledning kan du lägga till följande metadataegenskaper och värden i blobar i Blob Storage. När en indexerare stöter på den här egenskapen hoppar den över bloben eller dess innehåll i indexeringskörningen.

Egenskapsnamn	Egenskapsvärde	Förklaring
"AzureSearch_Skip"	`"true"`	Instruerar blobindexeraren att hoppa över bloben helt. Varken metadata eller extrahering av innehåll görs. Detta är användbart när en viss blob misslyckas upprepade gånger och avbryter indexeringsprocessen.
"AzureSearch_SkipContent"	`"true"`	Hoppar över innehåll och extraherar bara metadata. detta motsvarar den `"dataToExtract" : "allMetadata"` inställning som beskrivs i konfigurationsinställningarna , bara begränsad till en viss blob.

Om du inte konfigurerar inkluderings- eller exkluderingsvillkor rapporterar indexeraren en icke-berättigad blob som ett fel och går vidare. Om det uppstår tillräckligt många fel kan bearbetningen stoppas. Du kan ange feltolerans i konfigurationsinställningarna för indexeraren.

En indexerare skapar vanligtvis ett sökdokument per blob, där textinnehållet och metadata samlas in som sökbara fält i ett index. Om blobar är hela filer kan du eventuellt parsa dem i flera sökdokument. Du kan till exempel parsa rader i en CSV-fil för att skapa ett sökdokument per rad.

Indexera blobmetadata

Blobmetadata kan också indexeras, och det är användbart om du tror att någon av standard- eller anpassade metadataegenskaperna är användbara i filter och frågor.

Användardefinierade metadataegenskaper extraheras ordagrant. Om du vill ta emot värdena måste du definiera fältet i sökindexet av typen Edm.String, med samma namn som metadatanyckeln för blobben. Om en blob till exempel har en metadatanyckel med Sensitivity värdet Highbör du definiera ett fält med namnet Sensitivity i sökindexet och fyllas med värdet High.

Standardegenskaper för blobmetadata kan extraheras till fält med liknande namn och typ som anges nedan. Blob-indexeraren skapar automatiskt interna fältmappningar för dessa egenskaper för blobmetadata och konverterar det ursprungliga bindestreckade namnet ("metadata-storage-name") till ett understruket motsvarande namn ("metadata_storage_name").

Du måste fortfarande lägga till de understreckade fälten i indexdefinitionen, men du kan utelämna fältmappningar eftersom indexeraren gör associationen automatiskt.

metadata_storage_name (Edm.String) – blobens filnamn. Om du till exempel har en blob /my-container/my-folder/subfolder/resume.pdf är resume.pdfvärdet för det här fältet .
metadata_storage_path (Edm.String) – blobens fullständiga URI, inklusive lagringskontot. Till exempel: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String) – innehållstyp enligt den kod som du använde för att ladda upp bloben. Exempel: application/octet-stream
metadata_storage_last_modified (Edm.DateTimeOffset) – senast ändrad tidsstämpel för bloben. Azure AI Search använder den här tidsstämpeln för att identifiera ändrade blobbar för att undvika att indexera om allt efter den första indexeringen.
metadata_storage_size (Edm.Int64) – blobstorlek i byte.
metadata_storage_content_md5 (Edm.String) – MD5-hash för blobinnehållet, om det är tillgängligt.
metadata_storage_sas_token (Edm.String) – en tillfällig SAS-token som kan användas av anpassade kunskaper för att få åtkomst till bloben. Den här token bör inte lagras för senare användning eftersom den kan upphöra att gälla.

Slutligen kan alla metadataegenskaper som är specifika för dokumentformatet för de blobar som du indexerar också representeras i indexschemat. Mer information om innehållsspecifika metadata finns i Egenskaper för innehållsmetadata.

Det är viktigt att påpeka att du inte behöver definiera fält för alla ovanstående egenskaper i ditt sökindex – samla bara in de egenskaper du behöver för ditt program.

Definiera datakällan

Datakällans definition anger vilka data som ska indexeras, autentiseringsuppgifter och principer för att identifiera ändringar i data. En datakälla definieras som en oberoende resurs så att den kan användas av flera indexerare.

Skapa eller uppdatera en datakälla för att ange dess definition:

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

Ange "typ" till "adlsgen2" (krävs).
Ange "credentials" till en Azure Storage-anslutningssträng. I nästa avsnitt beskrivs de format som stöds.
Ange "container" till blobcontainern och använd "fråga" för att ange eventuella undermappar.

En datakällsdefinition kan också innehålla principer för mjuk borttagning om du vill att indexeraren ska ta bort ett sökdokument när källdokumentet flaggas för borttagning.

Autentiseringsuppgifter och anslutningssträng som stöds

Indexerare kan ansluta till en blobcontainer med hjälp av följande anslutningar.

Lagringskonto med fullständig åtkomst anslutningssträng
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Du kan hämta anslutningssträng från sidan Lagringskonto i Azure-portalen genom att välja Åtkomstnycklar i det vänstra navigeringsfönstret. Se till att välja en fullständig anslutningssträng och inte bara en nyckel.

Hanterad identitet anslutningssträng
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Den här anslutningssträng kräver ingen kontonyckel, men du måste tidigare ha konfigurerat en söktjänst för att ansluta med hjälp av en hanterad identitet.

Signatur för delad åtkomst för lagringskonto** (SAS) anslutningssträng
`{ "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;" }`
SAS bör ha listan och läsbehörigheter för containrar och objekt (blobar i det här fallet).

Kommentar

Om du använder SAS-autentiseringsuppgifter måste du uppdatera autentiseringsuppgifterna för datakällan regelbundet med förnyade signaturer för att förhindra att de upphör att gälla. Om SAS-autentiseringsuppgifterna upphör att gälla misslyckas indexeraren med ett felmeddelande som liknar "Autentiseringsuppgifterna i anslutningssträng är ogiltiga eller har upphört att gälla".

Lägga till sökfält i ett index

I ett sökindex lägger du till fält för att acceptera innehållet och metadata för dina Azure-blobar.

Skapa eller uppdatera ett index för att definiera sökfält som lagrar blobinnehåll och metadata:

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

Skapa ett dokumentnyckelfält ("nyckel": sant). För blobinnehåll är de bästa kandidaterna metadataegenskaper.
- metadata_storage_path (standard) fullständig sökväg till objektet eller filen. Nyckelfältet ("ID" i det här exemplet) fylls i med värden från metadata_storage_path eftersom det är standardvärdet.
- metadata_storage_name, endast användbart om namnen är unika. Om du vill att det här fältet ska vara nyckeln går du "key": true till den här fältdefinitionen.
- En anpassad metadataegenskap som du lägger till i blobar. Det här alternativet kräver att blobuppladdningsprocessen lägger till metadataegenskapen till alla blobar. Eftersom nyckeln är en obligatorisk egenskap kan blobbar som saknar ett värde inte indexeras. Om du använder en anpassad metadataegenskap som en nyckel bör du undvika att göra ändringar i den egenskapen. Indexerare lägger till duplicerade dokument för samma blob om nyckelegenskapen ändras.
Metadataegenskaper innehåller ofta tecken, till exempel och -, som / är ogiltiga för dokumentnycklar. Eftersom indexeraren har egenskapen "base64EncodeKeys" (sant som standard) kodas metadataegenskapen automatiskt utan att det krävs någon konfiguration eller fältmappning.
Lägg till ett "innehållsfält" för att lagra extraherad text från varje fil via blobens "innehållsegenskap". Du behöver inte använda det här namnet, men om du gör det kan du dra nytta av implicita fältmappningar.
Lägg till fält för standardmetadataegenskaper. Indexeraren kan läsa anpassade metadataegenskaper, standardmetadataegenskaper och innehållsspecifika metadataegenskaper .

Konfigurera och köra ADLS Gen2-indexeraren

När indexet och datakällan har skapats är du redo att skapa indexeraren. Indexerarens konfiguration anger indata, parametrar och egenskaper som styr körningstidsbeteenden. Du kan också ange vilka delar av en blob som ska indexeras.

Skapa eller uppdatera en indexerare genom att ge den ett namn och referera till datakällan och målindexet:

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

Ange "batchSize" om standardvärdet (10 dokument) antingen används eller överbelastar tillgängliga resurser. Standard batchstorlekar är specifika för datakällan. Blobindexering anger batchstorleken till 10 dokument som en igenkänning av den större genomsnittliga dokumentstorleken.
Under "konfiguration" styr du vilka blobar som indexeras baserat på filtyp eller lämnar ospecificerat för att hämta alla blobar.

För "indexedFileNameExtensions"anger du en kommaavgränsad lista över filnamnstillägg (med en inledande punkt). Gör samma sak för "excludedFileNameExtensions" att ange vilka tillägg som ska hoppas över. Om samma tillägg finns i båda listorna undantas det från indexering.
Under "konfiguration" anger du "dataToExtract" för att styra vilka delar av blobarna som indexeras:
- "contentAndMetadata" anger att alla metadata och textinnehåll som extraheras från blobben indexeras. Detta är standardvärdet.
- "storageMetadata" anger att endast standardblobegenskaperna och användardefinierade metadata indexeras.
- "allMetadata" anger att standardblobegenskaper och metadata för hittade innehållstyper extraheras från blobinnehållet och indexeras.
Under "konfiguration" anger du "parsingMode" om blobar ska mappas till flera sökdokument, eller om de består av oformaterad text, JSON-dokument eller CSV-filer.
Ange fältmappningar om det finns skillnader i fältnamn eller typ, eller om du behöver flera versioner av ett källfält i sökindexet.

Vid blobindexering kan du ofta utelämna fältmappningar eftersom indexeraren har inbyggt stöd för att mappa egenskaperna "innehåll" och metadata till fält med liknande namn och typ i ett index. För metadataegenskaper ersätter indexeraren automatiskt bindestreck - med understreck i sökindexet.
Mer information om andra egenskaper finns i Skapa en indexerare . Den fullständiga listan över parameterbeskrivningar finns i Blob-konfigurationsparametrar i REST-API:et.

En indexerare körs automatiskt när den skapas. Du kan förhindra detta genom att ange "inaktiverad" till true. Om du vill kontrollera indexerarens körning kör du en indexerare på begäran eller sätter den enligt ett schema.

Kontrollera status för indexerare

Om du vill övervaka indexerarens status och körningshistorik skickar du en get indexer-statusbegäran :

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

Svaret innehåller status och antalet bearbetade objekt. Det bör se ut ungefär som i följande exempel:

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

Körningshistoriken innehåller upp till 50 av de senast slutförda körningarna, som sorteras i omvänd kronologisk ordning så att den senaste körningen kommer först.

Hantera fel

Fel som ofta inträffar under indexering är innehållstyper som inte stöds, innehåll som saknas eller överdimensionerade blobar.

Som standard stoppas blobindexeraren så fort den stöter på en blob med en innehållstyp som inte stöds (till exempel en ljudfil). Du kan använda parametern "excludedFileNameExtensions" för att hoppa över vissa innehållstyper. Du kanske dock vill att indexeringen ska fortsätta även om fel inträffar och sedan felsöka enskilda dokument senare. Mer information om indexeringsfel finns i Felsökningsvägledning för Indexer och Indexer-fel och -varningar.

Det finns fem indexeraregenskaper som styr indexerarens svar när fel inträffar.

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

Parameter	Giltiga värden	beskrivning
"maxFailedItems"	-1, null eller 0, positivt heltal	Fortsätt indexering om fel inträffar när som helst under bearbetningen, antingen när du parsar blobar eller när du lägger till dokument i ett index. Ange dessa egenskaper till antalet godkända fel. Värdet `-1` tillåter bearbetning oavsett hur många fel som inträffar. Annars är värdet ett positivt heltal.
"maxFailedItemsPerBatch"	-1, null eller 0, positivt heltal	Samma som ovan, men används för batchindexering.
"failOnUnsupportedContentType"	sant eller falskt	Om indexeraren inte kan fastställa innehållstypen anger du om jobbet ska fortsätta eller inte.
"failOnUnprocessableDocument"	sant eller falskt	Om indexeraren inte kan bearbeta ett dokument av en innehållstyp som stöds på annat sätt anger du om jobbet ska fortsätta eller inte.
"indexStorageMetadataOnlyForOversizedDocuments"	sant eller falskt	Överdimensionerade blobar behandlas som fel som standard. Om du anger den här parametern till true försöker indexeraren indexeras med metadata även om innehållet inte kan indexeras. Begränsningar för blobstorlek finns i Tjänstgränser.

Begränsningar

Till skillnad från blobindexerare kan ADLS Gen2-indexerare inte använda SAS-token på containernivå för att räkna upp och indexera innehåll från ett lagringskonto. Det beror på att indexeraren gör en kontroll för att avgöra om lagringskontot har hierarkiska namnområden aktiverade genom att anropa API:et Filesystem – Hämta egenskaper. För lagringskonton där hierarkiska namnområden inte är aktiverade rekommenderas kunderna i stället att använda blobindexerare för att säkerställa en högpresterande uppräkning av blobar.
Om egenskapen metadata_storage_path mappas till indexnyckelfältet garanteras inte blobar att indexeras om vid ett katalogbyte. Om du vill indexera om de blobar som ingår i de omdöpta katalogerna uppdaterar LastModified du tidsstämplarna för dem alla.

Nästa steg

Nu kan du köra indexeraren, övervaka status eller schemalägga indexerarens körning. Följande artiklar gäller för indexerare som hämtar innehåll från Azure Storage: