Dela via

Indexdata från Azure Blob Storage

  • Artikel

I den här artikeln får du lära dig hur du konfigurerar en indexerare som importerar innehåll från Azure Blob Storage 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.

Om du vill konfigurera och köra indexeraren kan du använda:

Den här artikeln använder REST-API:er för att illustrera varje steg.

Förutsättningar

  • Azure Blob Storage, Standard-prestanda (generell användning v2).

  • Åtkomstnivåer omfattar frekvent, lågfrekvent, kall och arkiv. Indexerare kan hämta blobar på frekventa, lågfrekventa och kalla åtkomstnivåer.

  • Blobar som tillhandahåller textinnehåll och metadata. Om blobar innehåller binärt innehåll eller ostrukturerad text kan du överväga att lägga till AI-berikning för bearbetning av bilder och naturligt språk. Blobinnehåll får inte överskrida indexeringsgränserna för söktjänstnivån.

  • En nätverkskonfiguration och dataåtkomst som stöds. Du behöver minst läsbehörigheter i Azure Storage. En lagrings-anslutningssträng som innehåller en åtkomstnyckel ger dig läsåtkomst till lagringsinnehåll. Om du i stället använder Microsoft Entra-inloggningar och -roller kontrollerar du att söktjänstens hanterade identitet har behörigheter för Storage Blob Data Reader .

    Som standard accepterar både sökning och lagring begäranden från offentliga IP-adresser. Om nätverkssäkerhet inte är ett omedelbart problem kan du indexering av blobdata med bara anslutningssträng- och läsbehörigheter. När du är redo att lägga till nätverksskydd kan du läsa Indexerarens åtkomst till innehåll som skyddas av Azure-nätverkssäkerhetsfunktioner för vägledning om dataåtkomst.

  • Använd en REST-klient för att formulera REST-anrop som liknar dem som visas i den här artikeln.

Uppgifter som stöds

Du kan använda den här indexeraren för följande uppgifter:

Dokumentformat som stöds

Blobindexeraren kan extrahera text från följande dokumentformat:

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.

Ett sammansatt eller inbäddat dokument (till exempel ett ZIP-arkiv, ett Word-dokument med inbäddad Outlook-e-post som innehåller bifogade filer eller en . MSG-fil med bifogade filer) indexeras också som ett enda dokument. Till exempel alla bilder som extraherats från bifogade filer i en . MSG-filen returneras i fältet normalized_images. Om du har bilder kan du överväga att lägga till AI-berikning för att få mer sökverktyg från det innehållet.

Textinnehåll i ett dokument extraheras till ett strängfält med namnet "content". Du kan också extrahera standard- och användardefinierade metadata.

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.

För närvarande stöds inte indexering av blobindextaggar av den här indexeraren.

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.

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

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

  2. Ange "typ" till "azureblob" (krävs).

  3. Ange "autentiseringsuppgifter" till en Azure Storage-anslutningssträng. I nästa avsnitt beskrivs de format som stöds.

  4. 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 Portal 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).
Signatur för delad åtkomst för containrar
{ "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;" }
SAS ska ha listan och läsbehörigheter för containern. Mer information finns i Använda signaturer för delad åtkomst.

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.

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

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-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_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
    ]
}

  2. 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. Indexeraren kodar dock automatiskt nyckelmetadataegenskapen, utan att det krävs någon konfiguration eller fältmappning.

  3. 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.

  4. Lägg till fält för standardmetadataegenskaper. Indexeraren kan läsa anpassade metadataegenskaper, standardmetadataegenskaper och innehållsspecifika metadataegenskaper .

Konfigurera och köra blobindexeraren

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.

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

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

  2. Ange batchSize om standardvärdet (10 dokument) antingen underutnyttjer eller överväldigar 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.

  3. 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.

  4. 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.

  5. Under "konfiguration" anger du "parsingMode". Standardläget för parsning är ett sökdokument per blob. Om blobbar är oformaterad text kan du få bättre prestanda genom att växla till oformaterad textparsing . Om du behöver mer detaljerad parsning som mappar blobar till flera sökdokument anger du ett annat läge. En-till-många-parsning stöds för blobar som består av:

  6. 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.

  7. Mer information om andra egenskaper finns i Skapa en indexerare . Den fullständiga listan över parameterbeskrivningar finns i REST API.

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.

Indexera data från flera Azure Blob-containrar till ett enda index

Tänk på att en indexerare bara kan indexeringsdata från en enda container. Om ditt krav är att indexera data från flera containrar och konsolidera dem till ett enda AI Search-index kan detta uppnås genom att konfigurera flera indexerare, alla riktade till samma index. Tänk på det maximala antalet indexerare som är tillgängliga per SKU.

För att illustrera ska vi ta ett exempel på två indexerare som hämtar data från två olika datakällor med namnet my-blob-datasource1 och my-blob-datasource2. Varje datakälla pekar på en separat Azure Blob-container, men båda direkt till samma index med namnet my-search-index.

Exempel på den första indexerarens definition:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Den andra indexerarens definition som körs parallellt:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

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=2024-07-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":"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
        ]
    }

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. Men du kanske vill indexera för att 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=2024-07-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.

Se även