Share via

Skapa eller uppdatera datakälla (förhandsversion av REST API)

  • Artikel

Gäller för: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Viktigt

2023-07-01-Preview (inga ändringar).

2021-04-30-Preview lägger till stöd för hanterade identiteter för indexeraranslutningar till andra Azure-resurser:

  • "autentiseringsuppgifter" accepterar ett Azure-resurs-ID som ett värde, förutsatt att söktjänsten körs under en hanterad identitet och Azure-rolltilldelningar ger läsåtkomst till data.
  • "identitet" accepterar en användartilldelad hanterad identitet. Den här egenskapen är på första nivån för dataanslutningar. Den finns även under "encryptionKey" för att hämta en kundhanterad nyckel i Azure Key Vault.
  • Azure Files support finns som förhandsversion. Använd ett förhandsversions-API för att indexeras från den här datakällan.

2020-06-30-Preview lägger till:

  • "dataDeletionDetectionPolicy" accepterar "NativeBlobSoftDeleteDeletionDetectionPolicy" för blobindexerare.
  • Azure Database for MySQL support finns som förhandsversion. Använd ett förhandsversions-API för att indexeras från den här datakällan.
  • Stöd för Cosmos DB MongoDB API och Gremlin API finns i förhandsversion. Använd ett förhandsversions-API för att indexeras från den här datakällan.

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 datakällor som stöds.

Du kan använda post eller PUT på en create-begäran. För båda två innehåller begärandetexten objektdefinitionen.

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

För uppdateringsbegäranden använder du PUT och anger indexerarens namn 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 skrivs den över med den nya definitionen.

Anteckning

När en datakälla finns kan du inte ändra typegenskapen för en uppdateringsbegäran. I stället bör du skapa en ny datakälla med den typ du vill använda.

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 siffra, ha inga snedstreck eller punkter och vara färre än 128 tecken. När du har startat namnet med en bokstav eller siffra kan resten av namnet innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd.
api-version Krävs. Den aktuella förhandsversionen är 2023-07-01-Preview. Fler versioner finns i API-versioner .

Rubriker för begäran

I följande tabell beskrivs de obligatoriska och valfria begärandehuvudena.

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 i begäran, annars krävs en nyckel. En API-nyckel är en unik, systemgenererad sträng som autentiserar begäran till söktjänsten. Skapa begäranden måste innehålla en api-key rubrik som är 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 de viktigaste delarna i definitionen.

{   
    "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" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "identity": (optional) {Sets the Resource ID of a managed identity. See below for details },
    "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.",
      "identity": "(Resource ID of a user-assigned managed identity, used for connecting to key vault)",
      "accessCredentials": (Credentials for connecting to key vault. Omit if using a managed identity) {
        "applicationId": "Azure AD Application ID that has access permissions to the key vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

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, får inte börja eller sluta med bindestreck och får innehålla högst 128 tecken.
beskrivning En valfri beskrivning.
typ Krävs. Måste vara en av de typer av datakällor som stöds:
adlsgen2
för Azure Data Lake Storage Gen2
azureblob för Azure Blob Storage
azurefiles för Azure File Storage
azuresql för Azure SQL Database
azuretable for Azure Table Storage
cosmosdb för Azure Cosmos DB SQL API, MongoDB API, Gremlin API
mysql för Azure Database for MySQL
Autentiseringsuppgifter Krävs. Innehåller en connectionString egenskap som anger hur du ansluter.
container Krävs. Anger containern, samlingen, tabellen eller vyn som innehåller de data som ska indexeras.
dataChangeDetectionPolicy Valfritt. Anger den mekanism som tillhandahålls av dataplattformen för att identifiera ändrade dataobjekt.
dataDeletionDetectionPolicy Valfritt. Identifierar hur dataplattformen tar bort data.
encryptionKey Valfritt. Används för ytterligare kryptering av autentiseringsuppgifter för datakällor via kundhanterade krypteringsnycklar (CMK) i Azure Key Vault. Tillgängligt för fakturerbara söktjänster som skapats på eller efter 2019-01-01.
Inaktiverad Valfritt. Booleskt värde som anger om indexeraren skapas i ett inaktiverat tillstånd, vilket förhindrar att den körs omedelbart. Falskt som standard.
identity Valfritt. Den innehåller en userAssignedIdentity av typen #Microsoft.Azure.Search.DataUserAssignedIdentity och anger den användartilldelade hanterade identiteten för den externa resursen. Den här egenskapen är credentials beroende av att anslutningssträng i rätt format (ett resurs-ID) för hanterade identitetsanslutningar för varje typ av datakälla.

Om egenskapen identity är null görs anslutningen till ett resurs-ID med hjälp av den systemhanterade egenskapen.

Om den här egenskapen är tilldelad till typen #Microsoft.Azure.Search.DataNoneIdentityrensas alla explicita identiteter som angavs tidigare.

Svarsåtgärder

För en lyckad begäran: 201 Skapad om en ny datakälla skapades och 204 Inget innehåll om en befintlig datakälla uppdaterades.

Exempel

Exempel: Azure-roller och en systemtilldelad hanterad identitet

Om din söktjänst har en systemtilldelad hanterad identitet och en rolltilldelning kan datakällans anslutning vara det unika resurs-ID:t för ditt lagringskonto.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
  }

Exempel: Azure-roller och en användartilldelad hanterad identitet (förhandsversion)

Det här exemplet visar en Azure AD autentiserad anslutning för en söktjänst som har en användartilldelad hanterad identitet.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]"
    }
  }

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: Använda alternativet oförändrade eller redigerade 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 ytterligare 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 identity) {
        "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

Exempel: Kryptering av nyckelvalvsanslutningar efter söktjänster som har en användartilldelad hanterad identitet

Det här exemplet utelämnar accessCredentials. För en resurs som har tilldelats en användartilldelad hanterad identitet kan du ange identiteten i encryptionKey och hämta nyckeln med hjälp av identitets- och Azure-rolltilldelningarna.

{
    "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",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-identity"
        }
    }
}

Definitioner

Länk Description
Behållare Anger containern, samlingen, tabellen eller vyn som innehåller de data som ska indexeras.
Autentiseringsuppgifter Innehåller en connectionString egenskap som anger hur en indexerare ansluter till en Azure-resurs.
dataChangeDetectionPolicy Anger den mekanism som tillhandahålls av dataplattformen för att identifiera ändrade data.
dataDeletionDetectionPolicy Anger mekanismen för att identifiera borttagna data.
encryptionKey Konfigurerar en anslutning till Azure Key Vault för kundhanterad kryptering.

container

Anger containern, samlingen, tabellen eller vyn som innehåller de data som ska indexeras.

Attribut Beskrivning
name Krävs. För Azure Cosmos DB anger sql API-samlingen. För Azure Blob Storage anger lagringscontainern. För Azure SQL anger du tabellen eller vyn. Du kan använda schemakvalificerade namn, till exempel [dbo].[mytable]. För Azure Table Storage anger du namnet på tabellen.
query Valfritt. 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).

autentiseringsuppgifter

Innehåller egenskapen "connectionString" som anger hur en indexerare ansluter till en Azure-resurs.

Attribut Beskrivning
Connectionstring Krävs. Anger en anslutning till en indexerares datakälla. Om du uppdaterar datakällans definition krävs inte anslutningssträng. Värdena <unchanged> eller <redacted> kan användas i stället för den faktiska anslutningssträng.

För anslutningar som autentiseras med nycklar eller inloggningsuppgifter visas dessa värden i anslutningssträng. 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.

Om du använder en hanterad identitet för att autentisera kan du utelämna autentiseringsuppgifter för anslutningen.

För anslutningar som autentiseras med hjälp av en hanterad identitet anger anslutningssträng Resurs-ID för Azure (se dessa länkar för anslutningssträng format: Azure Storage, Cosmos DBSQL Database).

Rolltilldelningar som är begränsade till den externa datakällan avgör om indexeraren kan ansluta och söktjänsten måste konfigureras för att köras som en betrodd tjänst i Azure Active Directory.

Om egenskapen "identitet" också anges görs anslutningen med hjälp av den användartilldelade hanterade identiteten för söktjänsten som tillhandahålls av egenskapen "identitet". Om "identitet" annars är ospecificerad eller null sker anslutningen via den systemhanterade identiteten.

dataChangeDetectionPolicy

Anger den mekanism som tillhandahålls av dataplattformen för att identifiera ändrade data. Principer som stöds varierar beroende på datakällans typ.

Attribut Beskrivning
dataChangeDetectionPolicy Valfritt. Giltiga principer inkluderar HighWatermarkChangeDetectionPolicy eller SqlIntegratedChangeDetectionPolicy.

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

SqlIntegratedChangeDetectionPolicyanvä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 .
highWaterMarkColumnName Krävs för HighWatermarkChangeDetectionPolicy. För Cosmos DB måste kolumnen vara _ts egenskap. För Azure SQL rekommenderas en indexerad rowversion kolumn. För Azure Storage är ändringsidentifiering inbyggt med lastModified-värden, vilket eliminerar alla behov av att ange dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Anger den mekanism som tillhandahålls av dataplattformen för att identifiera borttagna data. Principer som stöds varierar beroende på datakällans typ.

Attribut Beskrivning
dataDeletionDetectionPolicy Valfritt. Giltiga värden är SoftDeleteColumnDeletionDetectionPolicy eller NativeBlobSoftDeleteDeletionDetectionPolicy (se Intern mjuk borttagning av blobar (förhandsversion)).

För närvarande ärSoftDeleteColumnDeletionDetectionPolicy den enda allmänt tillgängliga principen, som identifierar borttagna objekt baserat på värdet för en kolumn eller egenskap för mjuk borttagning i datakällan.

softDeleteColumnName" Krävs. Namnet på en kolumn i datakällan som anger en rads borttagningsstatus. Du kan till exempel skapa en kolumn med namnet "IsDeleted". Endast kolumner med sträng-, heltals- eller booleska värden stöds.
softDeleteMarkerValue Krävs. Värdet för kolumnen mjuk borttagning. 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. Om indexeraren läser det här värdet från kolumnen mjuk borttagning tas motsvarande sökdokument bort från sökindexet.

encryptionKey

Konfigurerar en anslutning till Azure Key Vault för kompletterande kundhanterade krypteringsnycklar (CMK). Kryptering med kundhanterade nycklar är inte tillgängligt för kostnadsfria tjänster. För fakturerbara tjänster är den endast tillgänglig för söktjänster som skapats på eller efter 2019-01-01.

En anslutning till nyckelvalvet måste autentiseras. Du kan använda antingen "accessCredentials" eller en hanterad identitet för detta ändamål.

Hanterade identiteter kan vara system- eller användartilldelade (förhandsversion). Om söktjänsten har både en systemtilldelad hanterad identitet och en rolltilldelning som ger läsåtkomst till nyckelvalvet kan du utelämna både "identitet" och "accessCredentials", så autentiserar begäran med hjälp av den hanterade identiteten. Om söktjänsten har användartilldelad identitet och rolltilldelning anger du egenskapen "identitet" till resurs-ID för den identiteten.

Attribut Beskrivning
keyVaultKeyName Krävs. Namnet på den Azure Key Vault-nyckel som används för kryptering.
keyVaultKeyVersion Krävs. Version av Azure Key Vault-nyckeln.
keyVaultUri Krävs. URI för Azure Key Vault (kallas även DNS-namn) som tillhandahåller nyckeln. Ett exempel på en URI kan vara https://my-keyvault-name.vault.azure.net.
accessCredentials Utelämna om du använder en hanterad identitet. Annars inkluderar applicationId egenskaperna accessCredentials för (ett Azure Active Directory-program-ID som har åtkomstbehörighet till din angivna Azure-Key Vault) och applicationSecret (autentiseringsnyckeln för det angivna Azure AD-programmet).
identity Valfritt om du inte använder en användartilldelad hanterad identitet för söktjänstanslutningen till Azure Key Vault. Formatet är "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Se även