Skapa datakälla (REST API för Azure AI Search)

Artikel
07/10/2024

I Azure AI Search används en datakälla med indexerare som tillhandahåller anslutningsinformation för på begäran eller schemalagd datauppdatering av ett målindex och hämtar data från Azure-datakällor som stöds.

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/datasources?api-version=[api-version]  
    Content-Type: application/json  
    api-key: [admin key]

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

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

HTTPS krävs för alla tjänstbegäranden. Om objektet inte finns skapas det. Om den redan finns uppdateras den till den nya definitionen.

Anteckning

Det maximala antalet index som du kan skapa varierar beroende på prisnivå. Mer information finns i Tjänstbegränsningar.

URI-parametrar

Parameter	Beskrivning
tjänstnamn	Krävs. Ange det unika, användardefinierade namnet på söktjänsten.
datakällans 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

Brödtexten i begäran innehåller en definition av datakällan, som innehåller typen av datakälla, autentiseringsuppgifter för att läsa data, samt en valfri princip för identifiering av dataändringar och identifiering av databorttagning som används för att effektivt identifiera ändrade eller borttagna data i datakällan när de används med en regelbundet schemalagd indexerare.

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

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },
    "container": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

Begäran innehåller följande egenskaper:

Egenskap	Beskrivning
name	Krävs. Namnet på datakällan. Ett datakällans namn får bara innehålla gemener, siffror eller bindestreck, kan inte starta eller sluta med bindestreck och är begränsat till 128 tecken.
beskrivning	En valfri beskrivning.
typ	Krävs. Måste vara en av de datakälltyper som stöds: `azuresql` för Azure SQL Database, Azure SQL Managed Instance eller SQL Server-instans som körs på en virtuell Azure-dator `cosmosdb` för Azure Cosmos DB för NoSQL, Azure Cosmos DB for MongoDB (förhandsversion) eller Azure Cosmos DB för Apache Gremlin (förhandsversion) `azureblob` för Azure Blob Storage `adlsgen2` för Azure Data Lake Storage Gen2 `azuretable` för Azure Table Storage `azurefile` för Azure Files (förhandsversion) `mysql` för Azure Database for MySQL ( förhandsversion) `sharepoint` för SharePoint i Microsoft 365(förhandsversion)
autentiseringsuppgifter	Krävs. Den innehåller en `connectionString` egenskap som anger anslutningssträng för datakällan. Formatet för anslutningssträng beror på datakällans typ: För Azure SQL Database är detta den vanliga SQL Server anslutningssträng. Om du använder Azure Portal för att hämta anslutningssträng väljer du alternativet `ADO.NET connection string` . För Azure Cosmos DB måste anslutningssträng ha följande format: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Alla värden krävs. Du hittar dem i Azure Portal. För Azure Blob Storage definieras de anslutningssträng formaten i avsnittet Autentiseringsuppgifter i Konfigurera blobindexering i Azure AI Search. Azure Storage, Azure SQL Database och Azure Cosmos DB har också stöd för en hanterad identitet anslutningssträng som inte innehåller någon kontonyckel i anslutningssträng. Om du vill använda den hanterade identiteten anslutningssträng format följer du anvisningarna för att konfigurera en indexerareanslutning till en datakälla med hjälp av en hanterad identitet. Om du uppdaterar datakällan krävs inte anslutningssträng. Värdena `<unchanged>` eller `<redacted>` kan användas i stället för den faktiska anslutningssträng.
container	Krävs. Anger vilka data som ska indexeras med egenskaperna `name` (krävs) och `query` (valfritt): `name`För Azure SQL anger du tabellen eller vyn. Du kan använda schemakvalificerade namn, till exempel `[dbo].[mytable]`. För Azure Cosmos DB anger sql API-samlingen. För Azure Blob Storage anger lagringscontainern. För Azure Table Storage anger du namnet på tabellen. `query`: För Azure Cosmos DB kan du ange en fråga som plattar ut en godtycklig JSON-dokumentlayout till ett platt schema som Azure AI Search kan indexera. För Azure Blob Storage kan du ange en virtuell mapp i blobcontainern. För blobsökväg `mycontainer/documents/blob.pdfdocuments` kan till exempel användas som virtuell mapp. För Azure Table Storage kan du ange en fråga som filtrerar den uppsättning rader som ska importeras. För Azure SQL stöds inte frågan. Använd vyer i stället.
dataChangeDetectionPolicy	Valfritt. Används för att identifiera ändrade dataobjekt. Principer som stöds varierar beroende på datakällans typ. Giltiga principer är principen för ändringsidentifiering av högvattenstämpel och SQL Integrated Change Detection Policy. Principen för ändringsidentifiering med hög vattenstämpel beror på en befintlig kolumn eller egenskap som uppdateras tillsammans med andra uppdateringar (alla infogningar resulterar i en uppdatering av vattenstämpelkolumnen) och värdeändringen är högre. För Cosmos DB-datakällor måste du använda `_ts` egenskapen . För Azure SQL är en indexerad `rowversion` kolumn den idealiska kandidaten för användning med principen för högvattenmärke. För Azure Storage är ändringsidentifiering inbyggt med lastModified-värden, vilket eliminerar alla behov av att ange dataChangeDetectionPolicy för blob- eller tabelllagring. SQL Integrated Change Detection Policy används för att referera till de inbyggda funktionerna för ändringsidentifiering i SQL Server. Den här principen kan bara användas med tabeller. Det går inte att använda med vyer. Du måste aktivera ändringsspårning för den tabell som du använder innan du kan använda den här principen. Anvisningar finns i Aktivera och inaktivera ändringsspårning . Mer information om stöd för ändringsidentifiering i indexeraren finns i Ansluta till och indexeras Azure SQL innehåll.
dataDeletionDetectionPolicy	Valfritt. Används för att identifiera borttagna dataobjekt. För närvarande är den enda princip som stöds principen för mjuk borttagning, som identifierar borttagna objekt baserat på värdet för en kolumn eller egenskap för mjuk borttagning i datakällan. Endast kolumner med sträng-, heltals- eller booleska värden stöds. Värdet som används som `softDeleteMarkerValue` måste vara en sträng, även om motsvarande kolumn innehåller heltal eller booleska värden. Om värdet som visas i datakällan till exempel är 1 använder du "1" som `softDeleteMarkerValue`.
encryptionKey	Valfritt. Används för att kryptera datakällan 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.

Svarsåtgärder

För en lyckad begäran: 201 Skapad.

Exempel

Exempel: Azure SQL med ändringsidentifiering (princip för ändringsidentifiering av högvattenstämpel)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}

Exempel: Azure SQL med ändringsidentifiering (SQL Integrated Ändringsspårning Policy)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}

Exempel: Azure SQL med ändringsidentifiering med borttagningsidentifiering

Kom ihåg att egenskaperna för borttagningsidentifiering är softDeleteColumnName och softDeleteMarkerValue.

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}

Exempel: Endast datakälla med nödvändiga egenskaper

Valfria egenskaper som rör identifiering av ändringar och borttagning kan utelämnas om du bara tänker använda datakällan för engångskopiering av data:

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}

Exempel: Utelämna autentiseringsuppgifter

Om du tänker uppdatera datakällan krävs inte autentiseringsuppgifterna. Värdena <unchanged> eller <redacted> kan användas i stället för anslutningssträng.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

Exempel: Krypteringsnycklar

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

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "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)"}
      }
}

Dela via