Dela via


Skapa indexerare (REST API för Azure AI Search)

En indexerare automatiserar indexering från Azure-datakällor som stöds, till exempel Azure Storage, Azure SQL Database och Azure Cosmos DB för att nämna några. Indexerare använder en fördefinierad datakälla och ett index för att upprätta en indexeringspipeline som extraherar och serialiserar källdata och skickar dem till en söktjänst för datainmatning. För AI-berikning av bild och ostrukturerad text kan indexerare också acceptera en kompetensuppsättning som definierar AI-bearbetning.

När du skapar en indexerare läggs den till i söktjänsten och den körs. Om begäran lyckas fylls indexet i med sökbart innehåll från datakällan.

Du kan använda POST eller PUT på begäran. För någon av dem innehåller JSON-dokumentet i begärandetexten objektdefinitionen.

POST https://[service name].search.windows.net/indexers?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]  

Du kan också använda PUT och ange indexerarens namn på URI:n.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]    

HTTPS krävs för alla tjänstbegäranden. Om indexeraren inte finns skapas den. Om den redan finns uppdateras den till den nya definitionen, men du måste utfärda en Run Indexer-begäran om du vill köra indexeraren.

Indexerarens konfiguration varierar beroende på typen av datakälla. För dataplattformsspecifik vägledning om hur du skapar indexerare börjar du med Indexerare-översikten, som innehåller den fullständiga listan över relaterade artiklar.

URI-parametrar

Parameter Beskrivning
tjänstnamn Krävs. Ange det unika, användardefinierade namnet på söktjänsten.
indexerarens namn Krävs på URI:n om du använder PUT. Namnet måste vara gemener, börja med en bokstav eller ett tal, ha inga snedstreck eller punkter och vara färre än 128 tecken. namnet måste börja med en bokstav eller ett tal, men resten av namnet kan innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd.
api-version Krävs. En lista över versioner som stöds finns i API-versioner .

Rubriker för begäran

I följande tabell beskrivs nödvändiga och valfria begärandehuvuden.

Fält Description
Content-Type Krävs. Ange detta till application/json
api-key Valfritt om du använder Azure-roller och en ägartoken anges på begäran, annars krävs en nyckel. Skapa begäranden måste innehålla en api-key rubrik inställd på din administratörsnyckel (till skillnad från en frågenyckel). Mer information finns i Ansluta till Azure AI Search med nyckelautentisering .

Begärandetext

En datakälla, ett index och en kompetensuppsättning ingår i en indexerares definition, men var och en är en oberoende komponent som kan användas i olika kombinationer. Du kan till exempel använda samma datakälla med flera indexerare eller samma index med flera indexerare eller flera indexerare som skriver till ett enda index.

Följande JSON är en övergripande representation av definitionens huvuddelar.

{   
    "name" : (optional on PUT; required on POST) "Name of the indexer",  
    "description" : (optional) "Anything you want, or nothing at all", 
    "dataSourceName" : (required) "Name of an existing data source",  
    "targetIndexName" : (required) "Name of an existing index",  
    "skillsetName" : (required for AI enrichment) "Name of an existing skillset",
    "disabled" : (optional) Boolean value indicating whether the indexer is disabled. False by default,
    "schedule" : (optional but runs once immediately if unspecified) { ... },  
    "parameters": { (optional)
       "batchSize": null,
       "maxFailedItems": 0,
       "maxFailedItemsPerBatch": 0,
       "base64EncodeKeys": null,
       "configuration": { (optional, mostly specific to the data source)
            "executionEnvironment": null
        }
      }, 
    "fieldMappings" : (optional) { ... },
    "outputFieldMappings" : (required for AI enrichment) { ... },
    "encryptionKey":(optional) { }
} 

Begäran innehåller följande egenskaper:

Egenskap Beskrivning
name Krävs. Namnet måste vara gemener, börja med en bokstav eller ett tal, ha inga snedstreck eller punkter och vara färre än 128 tecken. Namnet måste börja med en bokstav eller ett tal, men resten av namnet kan innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd.
dataSourceName Krävs. Namnet på en befintlig datakälla. Den innehåller ofta egenskaper som en indexerare kan använda för att utnyttja källplattformens egenskaper. Därför avgör den datakälla som du skickar till indexeraren tillgängligheten för vissa egenskaper och parametrar, till exempel filtrering av innehållstyper i Azure-blobar. eller frågetimeout för Azure SQL Database.
targetIndexName Krävs. Namnet på ett befintligt indexschema. Den definierar fältsamlingen som innehåller sökbara, filterbara, hämtningsbara och andra attribut som avgör hur fältet används. Under indexeringen crawlar indexeraren datakällan, spricker dokument och extraherar information, serialiserar resultatet till JSON och indexerar nyttolasten baserat på det schema som definierats för ditt index.
skillsetName Krävs för AI-berikning. Namnet på en befintlig kompetensuppsättning, en per indexerare. Precis som med datakällor och index är en kompetensuppsättning en oberoende definition som du bifogar till en indexerare. Du kan återanvända en kompetensuppsättning med andra indexerare, men varje indexerare kan bara använda en kompetensuppsättning i taget.
schedule Valfritt, men körs en gång omedelbart om det är ospecificerat och inte inaktiverat. Ett schema innehåller interval (krävs) och startTime (valfritt). Mer information finns i Schemalägga en indexerare.

interval anger hur ofta indexeraren körs. Det minsta tillåtna intervallet är fem minuter. den längsta är en dag. Det måste formateras som ett XSD-värde för "dayTimeDuration" (en begränsad delmängd av ett ISO 8601-varaktighetsvärde ). Mönstret för detta är: "P[nD][T[nH][nM]]". Exempel: PT15M för var 15:e minut, PT2H var 2:e timme.

startTime är en UTC-datetime när indexeraren ska börja köras.
Inaktiverad Valfritt. Booleskt värde som anger om indexeraren är inaktiverad. Ange den här egenskapen om du vill skapa en indexerare utan att omedelbart köra den. Falskt som standard.
parametrar Valfritt. Egenskaper för att ändra körningsbeteende.

"batchSize" (heltal). Anger antalet objekt som läse från datakällan och indexeras som en enda batch för att förbättra prestandan. Standardvärdet är källspecifikt (1 000 för Azure SQL Database och Azure Cosmos DB, 10 för Azure Blob Storage).

"maxFailedItems" (heltal). Anger antalet fel som ska tolereras innan en indexerare körs som ett fel. Standardvärdet är 0. Ange till -1 om du inte vill att några fel ska stoppa indexeringsprocessen. Använd Hämta indexeringsstatus för att hämta information om misslyckade dokument.

"maxFailedItemsPerBatch" (heltal). Anger antalet fel som ska tolereras i varje batch innan en indexerare körs som ett fel. Standardvärdet är 0. Ange till -1 om du inte vill att några fel ska stoppa indexeringsprocessen.

"base64EncodeKey" (Booleskt). Anger om dokumentnycklar som innehåller ogiltiga tecken ska kodas.

"configuration". Egenskaper som varierar beroende på datakällan.

"executionEnvironment" (sträng). Åsidosätter körningsmiljön som väljs av interna systemprocesser. Du måste uttryckligen ange körningsmiljön till Private om indexerare har åtkomst till externa resurser över privata slutpunktsanslutningar. Den här inställningen är under "configuration". För datainmatning är den här inställningen endast giltig för tjänster som etableras som Basic eller Standard (S1, S2, S3). För bearbetning av AI-berikande innehåll är den här inställningen endast giltig för S2 och S3. Giltiga värden är skiftlägesokänsliga och består av [null eller ospecificerat], Standard (standard) eller Private.
fieldMappings Valfritt. Associerar uttryckligen ett källfält med ett målfält i sökindexet. Används när käll- och målfält har olika namn eller typer, eller när du vill ange en funktion. Ett fieldMappings avsnitt innehåller sourceFieldName (obligatoriskt, ett fält i den underliggande datakällan), targetFieldName (krävs, ett fält i ett index) och ett valfritt mappingFunction för kodning av utdata. En lista över funktioner och exempel som stöds finns i fältmappningsfunktioner. Mer allmän information finns i Fältmappningar och transformeringar.
outputFieldMappings Krävs för en berikningspipeline. Mappar utdata från en kompetensuppsättning till ett index eller en projektion. Ett outputFieldMappings avsnitt innehåller sourceFieldName (krävs, en nod i ett berikande träd), targetFieldName (krävs, ett fält i ett index) och ett valfritt mappingFunction för kodning av utdata. En lista över funktioner och exempel som stöds finns i fältmappningsfunktioner. Mer allmän information finns i Mappa utdatafält från en kompetensuppsättning.
encryptionKey Valfritt. Används för att kryptera en indexerares definition i vila med dina egna nycklar som hanteras i azure-Key Vault. Tillgängligt för fakturerbara söktjänster som skapats på eller efter 2019-01-01.

Ett encryptionKey avsnitt innehåller en användardefinierad keyVaultKeyName (obligatorisk), ett systemgenererat (obligatoriskt keyVaultKeyVersion ) och en keyVaultUri som tillhandahåller nyckeln (krävs, även kallat DNS-namn). Ett exempel på URI kan vara "https://my-keyvault-name.vault.azure.net".

Du kan också ange accessCredentials om du inte använder en hanterad systemidentitet. Egenskaper för accessCredentials inkluderar applicationId (Microsoft Entra ID program-ID som har beviljats åtkomstbehörigheter till din angivna Azure-Key Vault) och applicationSecret (autentiseringsnyckel för det registrerade programmet). Ett exempel i nästa avsnitt illustrerar syntaxen.

Blobkonfigurationsparametrar

Flera parametrar är exklusiva för en viss indexerare, till exempel Azure Blob Indexing.

Parameter Ange och tillåtna värden Användning
"parsingMode" Sträng
"text"
"delimitedText"
"json"
"jsonArray"
"jsonLines"
För Azure-blobar anger du till för att text förbättra indexeringsprestanda för oformaterade textfiler i Blob Storage.
För CSV-blobar anger du till delimitedText när blobar är vanliga CSV-filer.
För JSON-blobar anger du till för att json extrahera strukturerat innehåll eller för att jsonArray extrahera enskilda element i en matris som separata dokument i Azure AI Search. Använd jsonLines för att extrahera enskilda JSON-entiteter, avgränsade med en ny rad, som separata dokument i Azure AI Search.
"excludedFileNameExtensions" Sträng
kommaavgränsad lista
Användardefinierade
Ignorera alla filtyper i listan för Azure-blobar. Du kan till exempel exkludera ".png, .png, .mp4" för att hoppa över filerna under indexeringen.
"indexedFileNameExtensions" Sträng
kommaavgränsad lista
Användardefinierade
För Azure-blobar väljer du blobar om filtillägget finns i listan. Du kan till exempel fokusera indexering på specifika programfiler ".docx, .pptx, .msg" för att specifikt inkludera dessa filtyper.
"failOnUnsupportedContentType" Boolesk
true
false (standard)
För Azure-blobar anger du till false om du vill fortsätta indexera när en innehållstyp som inte stöds påträffas och du inte känner till alla innehållstyper (filtillägg) i förväg.
"failOnUnprocessableDocument" Boolesk
true
false (standard)
För Azure-blobar anger du till false om du vill fortsätta indexeringen om ett dokument inte indexerar.
"indexStorageMetadataOnly
ForOversizedDocuments"
Booleskt sant
false (standard)
För Azure-blobar anger du den här egenskapen till true att fortfarande indexeras lagringsmetadata för blobinnehåll som är för stort för att bearbetas. Överdimensionerade blobar behandlas som fel som standard. Begränsningar för blobstorlek finns i Tjänstgränser.
"delimitedTextHeaders" Sträng
kommaavgränsad lista
Användardefinierade
För CSV-blobar anger en kommaavgränsad lista över kolumnrubriker, som är användbar för att mappa källfält till målfält i ett index.
"delimitedTextDelimiter" Sträng
enstaka tecken
Användardefinierade
För CSV-blobar anger slutpunktsgränsaren för CSV-filer där varje rad startar ett nytt dokument (till exempel "|").
"firstLineContainsHeaders" Boolesk
true (standard)
falskt
För CSV-blobar anger att den första (icke-tomma) raden för varje blob innehåller rubriker.
"documentRoot" Sträng
användardefinierad sökväg
För JSON-matriser, givet ett strukturerat eller halvstrukturerat dokument, kan du ange en sökväg till matrisen med den här egenskapen.
"dataToExtract" Sträng
"storageMetadata"
"allMetadata"
"contentAndMetadata" (standard)
För Azure-blobar:
Ange till att "storageMetadata" index bara indexering av standardblobegenskaper och användardefinierade metadata.
Ange till för att "allMetadata" extrahera metadata som tillhandahålls av Azure Blob Storage-undersystemet och innehållstypspecifika metadata (till exempel metadata som är unika för bara .png filer) indexeras.
Ange till för att "contentAndMetadata" extrahera alla metadata och textinnehåll från varje blob.

För bildanalys i AI-berikning, när "imageAction" är inställt på ett annat värde än "none", "dataToExtract" talar inställningen om för indexeraren vilka data som ska extraheras från bildinnehåll. Gäller för inbäddat bildinnehåll i ett .PDF eller annat program, eller bildfiler som .jpg och .png, i Azure-blobar.
"imageAction" Sträng
"none"
"generateNormalizedImages"
"generateNormalizedImagePerPage"
För Azure-blobar anger du till för att"none" ignorera inbäddade bilder eller bildfiler i datauppsättningen. Det här är standardinställningen.

För bildanalys i AI-berikning anger du till"generateNormalizedImages" att extrahera text från bilder (till exempel ordet "stopp" från ett trafikstopptecken) och bäddar in den som en del av innehållsfältet. Under bildanalysen skapar indexeraren en matris med normaliserade bilder som en del av dokumentets sprickbildning och bäddar in den genererade informationen i innehållsfältet. Den här åtgärden kräver att "dataToExtract" den är inställd på "contentAndMetadata". En normaliserad bild refererar till ytterligare bearbetning som resulterar i enhetlig bildutdata, storlek och roterad för att främja konsekvent rendering när du inkluderar bilder i visuella sökresultat (till exempel fotografier i samma storlek i en grafkontroll som visas i JFK-demonstrationen). Den här informationen genereras för varje bild när du använder det här alternativet.

Om du anger kommer "generateNormalizedImagePerPage"PDF-filer att behandlas på olika sätt i stället för att extrahera inbäddade bilder, så återges varje sida som en bild och normaliseras därefter. Den här processen per sida förväntas ta mycket längre tid än "generateNormalizedImages". Filtyper som inte är PDF-filer behandlas på samma sätt som om "generateNormalizedImages" de angavs.

Om du ställer in konfigurationen "imageAction" på något annat värde än "none" krävs att en kompetensuppsättning också är kopplad till indexeraren och kan vara en process med låg prestanda avsiktligt.
"normalizedImageMaxWidth"
"normalizedImageMaxHeight"
Alla heltal mellan 50-10000 Den maximala bredden eller höjden (i bildpunkter) för normaliserade bilder som genereras när en "imageAction" anges. Standardvärdet är 2 000.

Standardvärdet på 2 000 bildpunkter för normaliserade bilders maximala bredd och höjd baseras på de maximala storlekar som stöds av OCR-färdigheten och bildanalysfärdigheten. OCR-färdigheten stöder en maximal bredd och höjd på 4 200 för icke-engelska språk och 1 0000 för engelska. Om du ökar maxgränserna kan bearbetningen misslyckas på större bilder beroende på din definition av kompetensuppsättningen och språket i dokumenten.
"allowSkillsetToReadFileData" Boolesk
true
false (standard)
Om du anger parametern "allowSkillsetToReadFileData" till true skapas en sökväg /document/file_data som är ett objekt som representerar ursprungliga fildata som laddats ned från din blobdatakälla. På så sätt kan du skicka ursprungliga fildata till en anpassad färdighet för bearbetning i berikningspipelinen eller till färdigheten Extrahering av dokument. Objektet som genereras definieras på följande sätt: { "$type": "file", "data": "BASE64 encoded string of the file" }

Om du anger parametern "allowSkillsetToReadFileData" till true krävs att en kompetensuppsättning kopplas till indexeraren och att parametern "parsingMode" är inställd på "default", "text" eller "json".
"pdfTextRotationAlgorithm" Sträng
"none" (standard)
"detectAngles"
Om du anger parametern "pdfTextRotationAlgorithm" till "detectAngles" kan det ge bättre och mer läsbar textextrahering från PDF-filer som har roterad text i dem. Observera att det kan finnas en liten prestanda påföljd när den här parametern används. Den här parametern gäller endast PDF-filer och endast pdf-filer med inbäddad text. Om den roterade texten visas i en inbäddad bild i PDF-filen gäller inte den här parametern.

Om parametern "pdfTextRotationAlgorithm" ska anges till "detectAngles" krävs att parametern "parsingMode" är inställd på "default".

Konfigurationsparametrar för Azure Cosmos DB

Följande parametrar är specifika för Cosmos DB-indexerare.

Parameter Ange och tillåtna värden Användning
"assumeOrderByHighWaterMarkColumn" Boolesk För Cosmos DB-indexerare med SQL API anger du den här parametern för att ge ett tips till Cosmos DB om att frågan som används för att returnera dokument för indexering i själva verket sorteras _ts efter kolumnen. Om du anger den här parametern får du bättre resultat för scenarier med inkrementell indexering.

Azure SQL konfigurationsparametrar

Följande parametrar är specifika för Azure SQL Database.

Parameter Ange och tillåtna värden Användning
"queryTimeout" Sträng
"hh:mm:ss"
"00:05:00"
För Azure SQL Database anger du den här parametern för att öka tidsgränsen utöver standardvärdet på 5 minuter.
"convertHighWaterMarkToRowVersion" Boolesk Ställ in den här parametern på "true" om du vill använda datatypen rowversion för kolumnen med högvattenmärke. När den här egenskapen är inställd på true subtraherar indexeraren en från värdet för rowversion innan indexeraren körs. Det gör det eftersom vyer med en-till-många-kopplingar kan ha rader med duplicerade radversionsvärden. Om du subtraherar en ser du till att indexerarfrågan inte missar dessa rader.
"disableOrderByHighWaterMarkColumn" Boolesk Ange "true" för den här parametern om du vill inaktivera ORDER BY-beteendet i frågan som används för ändringsidentifiering. Om du använder principen för ändringsidentifiering med högvattenmärke använder indexeraren WHERE- och ORDER BY-satser för att spåra vilka rader som behöver indexering (WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]). Den här parametern inaktiverar ORDER BY-beteendet. Indexeringen avslutas snabbare, men kompromissen är att om indexeraren avbryts av någon anledning måste hela indexerarjobbet upprepas i sin helhet.

Svarsåtgärder

201 Skapades för en lyckad begäran.

Exempel

Exempel: Indexerare med schema och allmänna parametrar

Skapar en indexerare som kopierar data från tabellen som datakällan refererar ordersds till till indexet enligt ett schema som startar den orders 1 januari 2021 UTC och körs varje timme. Varje anrop av indexerare lyckas om högst 5 objekt inte kan indexeras i varje batch och högst 10 objekt inte kan indexeras totalt.

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 }  
}

Anteckning

Om en indexerare är inställd på ett visst schema men upprepade gånger misslyckas i samma dokument om och om igen varje gång den körs, börjar indexeraren köras med ett mindre frekvent intervall (upp till maximalt minst en gång var 24:e timme) tills den lyckas igen. Om du tror att du har åtgärdat det problem som gjorde att indexeraren fastnade vid en viss tidpunkt kan du utföra en återställning, följt av en körning på begäran, av indexeraren, och om det lyckas återgår indexeraren till sitt angivna schemaintervall igen.

Exempel: Indexerare med blobparametrar

En indexerare kan välja att använda konfigurationsparametrar som ändrar körningsbeteenden. Konfigurationsparametrar avgränsas med kommatecken i indexerarbegäran och är specifika för en datakälla. Följande konfigurationsparametrar innehåller instruktioner som används för att indexa blobar.

  {
    "name" : "my-blob-indexer-for-cognitive-search",
    ... other indexer properties
    "parameters" : 
      { 
      "maxFailedItems" : "15", 
      "batchSize" : "100", 
      "configuration" : 
          { 
          "parsingMode" : "json", 
          "indexedFileNameExtensions" : ".json, .jpg, .png",
          "imageAction" : "generateNormalizedImages",
          "dataToExtract" : "contentAndMetadata" ,
          "executionEnvironment": "Standard"
          } 
      }
  }

Exempel: Indexerare med fältmappningar

Mappa en källtabells fält _id till ett "id" fält i ett sökindex. Azure AI Search tillåter inte att ett fältnamn börjar med ett understreck. En fältmappning kan lösa namnskillnader. Både käll- och målfältnamn är skiftlägesokänsliga. Mer information finns i Fältmappningar och transformeringar.

"fieldMappings" : [
    { "sourceFieldName" : "_id", "targetFieldName" : "id" },
    { "sourceFieldName" : "_timestamp", "targetFieldName" : "timestamp" }
]

Exempel: Indexerare med AI-berikning

Visar en AI-berikning, vilket anges av referensen till en skillset och outputFieldMappings. Kompetensuppsättningar är resurser på hög nivå som definieras separat. Det här exemplet är en förkortning av indexerarens definition i självstudien om AI-berikning.

{
  "name":"demoindexer",	
  "dataSourceName" : "demodata",
  "targetIndexName" : "demoindex",
  "skillsetName" : "demoskillset",
  "fieldMappings" : [
    {
        "sourceFieldName" : "content",
        "targetFieldName" : "content"
    }
   ],
  "outputFieldMappings" : 
  [
    {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
    },
  ],
  "parameters":
  {
  	"maxFailedItems":-1,
  	"configuration": 
    {
    "dataToExtract": "contentAndMetadata",
    "imageAction": "generateNormalizedImages"
    }
  }
}

Exempel: Indexerare med mappningar för kompetensuppsättningar och utdatafält

I AI-berikningsscenarier där en kompetensuppsättning är bunden till en indexerare måste du lägga outputFieldMappings till för att associera utdata från ett berikningssteg som tillhandahåller innehåll till ett sökbart fält i indexet. sourceFieldName är en nod i ett berikande träd. Det kan vara en sammansatt struktur som skapas under berikning från två separata fält i källdokumentet. targetFieldName är ett fält i ett sökindex. Mer information finns i Mappa utdatafält från en kompetensuppsättning.

"outputFieldMappings" : [
      {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
      },
      {
        "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
        "targetFieldName" : "keyphrases"
      },
      {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "language",
          "mappingFunction": null
      }      
  ]

Exempel: Krypteringsnycklar

Krypteringsnycklar är kundhanterade nycklar som används för ytterligare kryptering. Mer information finns i Kryptering med kundhanterade nycklar i Azure Key Vault.

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 },
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

Se även