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

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

在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.pdfdocuments 可用作虚拟文件夹。
对于 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)"}
      }
}

另请参阅