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

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

项目
02/28/2024

在 Azure AI 搜索中，数据源与索引器一起使用，为目标索引的按需或计划数据刷新提供连接信息，从支持的 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 版本。

请求标头

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

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用 Azure 角色并且请求中提供了持有者令牌，则为可选，否则需要密钥。创建请求必须包含 `api-key` 设置为管理密钥 (而不是查询密钥) 的标头。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

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

以下 JSON 是定义main部分的高级表示形式。

{   
    "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 SQL Database、SQL Server Azure SQL 托管实例在 Azure VM 上运行的 Azure Cosmos`cosmosdb` DB for NoSQL、Azure Cosmos DB for MongoDB (预览) 或 Azure Cosmos DB for Apache Gremlin (预览) `azureblob` `adlsgen2`适用于 azure 表存储 `azurefile`的 Azure Data Lake Storage Gen2 `azuretable` Azure Blob 存储 Azure 文件存储 (预览版) `mysql`Azure Database for MySQL (预览版) `sharepoint` microsoft 365 (预览版中的 SharePoint)
凭据	必需。它包含一个`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 存储，连接字符串格式在如何在 Azure AI 搜索中配置 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 AI 搜索可以编制索引的平面架构的查询。对于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 密钥保管库) 的访问权限 (Microsoft Entra ID 应用程序 ID，以及`applicationSecret`已注册应用程序) (身份验证密钥。下一部分中的示例演示了语法。

响应

对于成功的请求：“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" }
}

示例：使用 SQL 集成更改跟踪策略) (更改检测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.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 密钥保管库中使用客户管理的密钥进行加密。

{
    "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": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

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

URI 参数

请求标头

请求正文

响应

示例

另请参阅

其他资源