建立或更新資料來源 （預覽 REST API）

適用於：2023-07-01-Preview。 不再支援此版本。 立即 升級至較新版本。

在 Azure AI 搜尋中，數據源會與 索引器搭配使用，提供目標索引的隨選或排程數據重新整理連線資訊，從 支援的數據源提取數據。

您可以在建立要求上使用 POST 或 PUT。 對於任一個，要求主體會提供物件定義。

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

針對更新要求，請使用 PUT 並在 URI 上指定索引器名稱。

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

所有服務要求都需要 HTTPS。 如果物件不存在，則會建立它。 如果已經存在，則會使用新的定義覆寫它。

URI 參數

要求標頭

下表描述必要和選擇性的要求標頭。

要求本文

要求的本文包含數據源定義，其中包括數據源類型、讀取數據的認證，以及選擇性的數據變更偵測和數據刪除偵測原則，這些原則可用來在搭配定期排程的索引器使用時，有效識別數據源中已變更或刪除的數據

下列 JSON 是定義主要部分的高階表示法。

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

要求包含下列屬性：

回應

若要求成功：如果已建立新的數據源，則建立 201;如果現有數據源已更新，則為 204 沒有內容。

例子

範例：Azure 角色和系統指派的受控識別

如果您的搜尋服務具有系統指派的受控識別和角色指派，數據源聯機可以是記憶體帳戶的唯一資源標識符。

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

範例：Azure 角色和使用者指派的受控識別（預覽版）

此範例示範具有使用者指派受控識別之搜尋服務的 Azure AD 驗證連線。

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

範例：具有變更偵測的 Azure SQL（高水位線變更偵測原則）

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

範例：具有變更偵測的 Azure SQL （SQL 整合式變更追蹤原則）

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

範例：具有變更偵測與刪除偵測的 Azure SQL

回想一下，刪除偵測的屬性是 “softDeleteColumnName” 和 “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" }  
}  

範例：僅具有必要屬性的數據源

如果您只想要針對資料的一次性復本使用資料源，則可以省略與變更和刪除偵測相關的選擇性屬性：

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

範例：使用未變更或修訂的認證選項

如果您想要更新數據源，則不需要認證。 <unchanged> 或 <redacted> 的值可用來取代連接字串。

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

範例：加密金鑰

加密金鑰是用於其他加密的客戶自控金鑰。 如需詳細資訊，請參閱在 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)"}
      }
}

範例：搜尋服務具有使用者指派受控識別的加密密鑰保存庫連線

此範例省略 accessCredentials。 對於具有 使用者指派受控識別的資源， 指派給它，您可以在 encryptionKey 中指定身分識別，並使用該身分識別和 Azure 角色指派來擷取密鑰。

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

定義

容器

指定要編製索引之數據的容器、集合、數據表或檢視表。

憑據

包含 「connectionString」 屬性，指定索引器如何連接到 Azure 資源。

如需使用受控識別進行驗證的連線，連接字串會指定 Azure 資源識別元（請參閱下列連接字串格式的連結：Azure 記憶體、Cosmos DB、SQL Database）。

限定於外部數據源的角色指派會判斷索引器是否可以連線，而且搜尋服務必須設定為在 Azure Active Directory 中以受信任的服務身分執行。

如果同時指定 「身分識別」屬性，則會使用 「身分識別」屬性所提供的搜尋服務使用者指派的受控識別來建立連線。 否則，如果未指定「身分識別」或 Null，則聯機會透過系統管理的身分識別。

dataChangeDetectionPolicy

指定數據平臺提供的機制，以識別已變更的數據。 支持的原則會根據數據源類型而有所不同。

dataDeletionDetectionPolicy

指定數據平台為識別已刪除資料所提供的機制。 支持的原則會根據數據源類型而有所不同。

encryptionKey

設定與 Azure Key Vault 的連線，以取得補充 客戶管理的加密密鑰 （CMK）。 使用客戶管理的金鑰加密不適用於免費服務。 針對可計費的服務，它僅適用於在 2019-01-01 之後建立的搜尋服務。

必須驗證金鑰保存庫的連線。 您可以針對此目的使用 「accessCredentials」 或受控識別。

受控識別可以是系統或使用者指派（預覽）。 如果搜尋服務同時具有系統指派的受控識別，以及授與密鑰保存庫讀取許可權的角色指派，您可以省略「身分識別」和「accessCredentials」，而要求將會使用受控識別進行驗證。 如果搜尋服務具有使用者指派的身分識別和角色指派，請將 “identity” 屬性設定為該身分識別的資源標識符。

另請參閱

• 索引器概觀
• 建立索引器
• 客戶管理的加密