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

gäller för: 2023-07-01-Preview. Den här versionen stöds inte längre. Uppgradera omedelbart till en nyare version.

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, hämtar data från datakällor som stöds.

Du kan använda POST eller PUT på en create-begäran. För någon av dem 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.

URI-parametrar

Begärandehuvuden

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

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 periodiskt schemalagd indexerare

Följande JSON är en högnivå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:

Svar

För en lyckad begäran: 201 Skapades 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 söktjänsten 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 autentiserad Azure AD-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 med hög vattenstä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 Change Tracking 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: 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änd alternativet för 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ängen.

{
    "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 nyckelvalvanslutningar efter söktjänster med en användartilldelad hanterad identitet

Det här exemplet utelämnar accessCredentials. För en resurs som har en användartilldelad hanterad identitet tilldelad till den 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

behållare

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

Autentiseringsuppgifter

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

För anslutningar som autentiseras med en hanterad identitet anger anslutningssträngen Azure-resurs-ID :t (se dessa länkar för anslutningssträngformat: Azure Storage, Cosmos DB,SQL 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 söktjänstens användartilldelade hanterade identitet som tillhandahålls av egenskapen "identitet". Om "identiteten" 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.

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.

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", och begäran autentiseras med hjälp av den hanterade identiteten. Om söktjänsten har användartilldelad identitet och rolltilldelning anger du egenskapen "identitet" till resurs-ID:t för den identiteten.

Se även

• översikt över indexerare
• Skapa indexerare
• Kundhanterad kryptering