你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建数据源 (Azure 认知搜索 REST API)

项目
12/01/2022

在Azure 认知搜索中，数据源与索引器一起使用，为目标索引的临时或计划数据刷新提供连接信息，从支持的 Azure 数据源拉取数据。

可以在请求上使用 POST 或 PUT。对于任一对象，请求正文中的 JSON 文档提供对象定义。

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 参数

参数	描述
服务名称	必需。将其设置为搜索服务的唯一用户定义的名称。
数据源名称 (data source name)	如果使用 PUT，则需要 URI。名称必须是小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。使用字母或数字开始名称后，名称的其余部分可以包含任何字母、数字和短划线，前提是短划线不连续。
api-version	必需。当前稳定版本为 `api-version=2020-06-30`. 有关更多版本，请参阅 API 版本。

请求标头

下表介绍必需和可选的请求标头。

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	必需。 `api-key` 用于对搜索服务的请求进行身份验证。它是一个字符串值，对于服务是唯一的。创建请求必须包括 `api-key` 设置为管理员密钥的标头 (，而不是查询密钥) 。可以在Azure 门户的搜索服务仪表板中找到 API 密钥。

请求正文

请求正文包含数据源定义，而数据源定义包括数据源的类型、用于读取数据的凭据，以及可选的数据更改检测策略和数据删除检测策略，将这些策略与定期计划的索引器一起使用时，可以有效地识别数据源中已更改或已删除的数据

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

请求包含以下属性：

属性	说明
name	必需。数据源的名称。数据源名称必须仅包含小写字母、数字或短划线，不能以短划线开头或结尾，长度限制为 128 个字符。
description	可选说明。
type	必需。必须是受支持的数据源类型之一： `azuresql` 对于 azure Cosmos DB SQL API `azureblob`的 Azure VM `cosmosdb` 上运行的Azure SQL数据库或SQL Server实例 Azure Blob 存储 `adlsgen2`，Azure Data Lake Storage Gen2 `azuretable`用于 Azure 表存储
凭据	必需。它包含一个 `connectionString` 属性，该属性指定数据源的连接字符串。连接字符串的格式取决于数据源类型：对于Azure SQL数据库，这是通常SQL Server连接字符串。如果使用Azure 门户检索连接字符串，请选择该`ADO.NET connection string`选项。对于 Azure Cosmos DB，连接字符串必须采用以下格式： `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"` 所有值都是必需的。可以在 Azure 门户中找到这些值。对于Azure Blob 存储，连接字符串格式在“如何在认知搜索中配置 Blob 索引”部分中定义。 Azure 存储、Azure SQL数据库和 Azure Cosmos DB 还支持在连接字符串中不包含帐户密钥的托管标识连接字符串。若要使用托管标识连接字符串格式，请按照说明使用托管标识设置到数据源的索引器连接。如果要更新数据源，则不需要连接字符串。值 `<unchanged>` 或 `<redacted>` 可用于代替实际连接字符串。
container	必需。指定要使用`name`所需的 () 和`query` (可选) 属性编制索引的数据：：`name` 对于Azure SQL，指定表或视图。可以使用架构限定的名称，如 `[dbo].[mytable]`。对于 Azure Cosmos DB，指定 SQL API 集合。对于Azure Blob 存储，指定存储容器。对于 Azure 表存储，指定表的名称。 `query`：对于 Azure Cosmos DB，可以指定将任意 JSON 文档布局平展为Azure 认知搜索可以编制索引的平面架构的查询。对于Azure Blob 存储，可以在 Blob 容器中指定虚拟文件夹。例如，对于 blob 路径 `mycontainer/documents/blob.pdf`，`documents` 可用作虚拟文件夹。对于 Azure 表存储，可以指定要导入的行集的查询。对于Azure SQL，不支持查询。请改用视图。
dataChangeDetectionPolicy	可选。用于标识已更改的数据项。支持的策略因数据源类型而异。有效策略是高水印更改检测策略和 SQL 集成更改检测策略。高水印更改检测策略取决于与其他更新一起更新的现有列或属性， (所有插入都会导致对水印列的更新) ，并且值的变化更高。对于 Cosmos DB 数据源，必须使用该 `_ts` 属性。对于Azure SQL，索引`rowversion`列是用于高水印策略的理想候选列。对于 Azure 存储，更改检测是使用 lastModified 值内置的，无需为 blob 或表存储设置 dataChangeDetectionPolicy。 SQL 集成更改检测策略用于引用SQL Server中的本机更改检测功能。此策略仅适用于表，不适用于视图。需要先为要使用的表启用更改跟踪，才可以使用此策略。有关说明，请参阅启用和禁用更改跟踪。有关索引器中更改检测支持的详细信息，请参阅“连接到”和“索引”Azure SQL内容。
dataDeletionDetectionPolicy	可选。用于标识已删除的数据项。目前，唯一受支持的策略是软删除策略，该策略根据数据源中“软删除”列或属性的值标识已删除的项目。仅支持字符串、整数或布尔值的列。用作 `softDeleteMarkerValue` 的值必须是字符串，即使相应的列包含整数或布尔值也是如此。例如，如果数据源中显示的值为 1，请使用“1”作为 `softDeleteMarkerValue`。
encryptionKey	可选。用于使用自己的密钥（在 Azure 密钥保管库中管理）加密静态数据源。可用于在 2019-01-01 之后创建的可计费搜索服务。节 `encryptionKey` 包含用户定义 `keyVaultKeyName` (所需的) 、系统生成的 `keyVaultKeyVersion` (所需的) ，以及 `keyVaultUri` 提供所需的密钥 (，也称为 DNS 名称) 。示例 URI 可能是“https://my-keyvault-name.vault.azure.net"。（可选）可以指定 `accessCredentials` 是否不使用托管系统标识。 `accessCredentials`属性包括`applicationId`已授予对指定 Azure 密钥保管库) 的访问权限的 Azure Active Directory 应用程序 ID (，以及`applicationSecret`指定 Azure AD 应用程序) 的 (身份验证密钥。下一部分中的示例说明了语法。

响应

对于成功的请求：“201 已创建”。

示例

示例：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

回想一下，用于删除检测的属性和 softDeleteColumnNamesoftDeleteMarkerValue。

{   
    "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 密钥保管库中使用客户管理的密钥进行加密。

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

创建数据源 (Azure 认知搜索 REST API)

URI 参数

请求标头

请求正文

响应

示例

另请参阅

其他资源

其他资源