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

创建或更新数据源 (预览版 REST API)

项目
11/13/2023

适用于：2023-07-01-Preview、2021-04-30-Preview、2020-06-30-Preview

重要

2023-07-01-预览版 () 无更改。

2021-04-30-Preview 添加了对索引器与其他 Azure 资源的连接的托管标识支持：

“凭据” 接受 Azure 资源 ID 作为值，前提是搜索服务在托管标识下运行，并且 Azure 角色分配授予对数据的读取访问权限。
“identity” 接受用户分配的托管标识。此属性是数据连接的第一级。它还位于“encryptionKey”下，用于在 Azure 密钥保管库中检索客户管理的密钥。
Azure 文件存储支持以预览版提供。使用预览 API 从此数据源编制索引。

2020-06-30-Preview 添加了：

“dataDeletionDetectionPolicy” 接受 Blob 索引器的“NativeBlobSoftDeleteDeletionDetectionPolicy”。
Azure Database for MySQL支持以预览版提供。使用预览 API 从此数据源编制索引。
Cosmos DB MongoDB API 和 Gremlin API 支持目前为预览版。使用预览 API 从此数据源编制索引。

在 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。如果该对象不存在，则创建该对象。如果已存在，则会使用新定义覆盖它。

注意

数据源存在后，无法更改更新请求中的 type 属性。相反，应使用所需的类型创建新的数据源。

URI 参数

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

请求标头

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

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用的是 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。创建请求必须包含 `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" : (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)"}
      }
}

请求包含以下属性：

属性	说明
name	必需。数据源的名称。数据源名称只能包含小写字母、数字或短划线，不能以短划线开头或结尾，并且不能包含 128 个字符。
description	可选说明。
type	必需。必须是受支持的数据源类型之一： `adlsgen2` for Azure Data Lake Storage Gen2 `azureblob` for Azure Blob 存储 `azurefiles` 适用于 azure 文件存储 `azuresql`的 Azure SQL Database `azuretable` for Azure 表存储 `cosmosdb`，适用于 Azure Cosmos DB SQLAPI、MongoDB API、Gremlin API `mysql` for Azure Database for MySQL
凭据	必需。包含一个 `connectionString` 属性，该属性指定如何连接。
container	必需。指定包含要编制索引的数据的容器、集合、表或视图。
dataChangeDetectionPolicy	可选。指定数据平台提供的用于标识已更改数据项的机制。
dataDeletionDetectionPolicy	可选。标识数据平台如何删除数据。
encryptionKey	可选。用于通过 Azure 密钥保管库中客户管理的加密密钥 (CMK) 对数据源凭据进行额外加密。适用于在 2019-01-01 或之后创建的可计费搜索服务。
disabled	可选。指示是否在禁用状态下创建索引器的布尔值，这会阻止索引器立即运行。默认值为 False。
标识	可选。它包含 `userAssignedIdentity` 类型的 `#Microsoft.Azure.Search.DataUserAssignedIdentity` ，并指定外部资源的用户分配的托管标识。此属性依赖于`credentials`将连接字符串采用正确的格式 (资源 ID) 每种数据源类型的托管标识连接。 `identity`如果该属性为 null，则使用系统托管属性建立与资源 ID 的连接。如果将此属性分配给类型 `#Microsoft.Azure.Search.DataNoneIdentity`，则会清除以前指定的任何显式标识。

响应

对于成功的请求：“201 已创建”（如果已创建新数据源）和“204 无内容”（如果已更新现有数据源）。

示例

示例：Azure 角色和系统分配的托管标识

如果搜索服务具有系统分配的托管标识和角色分配，则数据源连接可以是存储帐户的唯一资源 ID。

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

示例：使用更改检测 (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 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 资源。
dataChangeDetectionPolicy	指定数据平台提供的用于识别已更改数据的机制。
dataDeletionDetectionPolicy	指定用于检测已删除数据的机制。
encryptionKey	配置与 Azure 密钥保管库的连接，以便进行客户管理的加密。

container

指定要编制索引的数据的容器、集合、表或视图。

Attribute 说明

name 必需。对于 Azure Cosmos DB，指定 SQL API 集合。对于Azure Blob 存储，指定存储容器。对于Azure SQL，指定表或视图。可以使用架构限定的名称，如 [dbo].[mytable]。对于 Azure 表存储，指定表的名称。

query 可选。对于 Azure Cosmos DB，允许指定将任意 JSON 文档布局平展为 Azure AI 搜索可以编制索引的平面架构的查询。对于Azure Blob 存储，允许在 Blob 容器中指定虚拟文件夹。例如，对于 blob 路径 mycontainer/documents/blob.pdf，documents 可用作虚拟文件夹。对于 Azure 表存储，允许指定筛选要导入的行集的查询。对于Azure SQL，不支持使用视图 (查询) 。

Attribute	说明
name	必需。对于 Azure Cosmos DB，指定 SQL API 集合。对于Azure Blob 存储，指定存储容器。对于Azure SQL，指定表或视图。可以使用架构限定的名称，如 `[dbo].[mytable]`。对于 Azure 表存储，指定表的名称。
query	可选。对于 Azure Cosmos DB，允许指定将任意 JSON 文档布局平展为 Azure AI 搜索可以编制索引的平面架构的查询。对于Azure Blob 存储，允许在 Blob 容器中指定虚拟文件夹。例如，对于 blob 路径 `mycontainer/documents/blob.pdf`，`documents` 可用作虚拟文件夹。对于 Azure 表存储，允许指定筛选要导入的行集的查询。对于Azure SQL，不支持使用视图 (查询) 。

凭据

包含一个“connectionString”属性，该属性指定索引器如何连接到 Azure 资源。

Attribute 说明

connectionString

Attribute	说明
connectionString	必需。指定与索引器数据源的连接。如果要更新数据源定义，则不需要连接字符串。值 `<unchanged>` 或 `<redacted>` 可用于代替实际连接字符串。对于使用密钥或登录凭据进行身份验证的连接，这些值在连接字符串中可见。连接字符串的格式取决于数据源类型：对于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 门户中找到这些值。如果使用托管标识进行身份验证，则可以省略连接上的凭据。

必需。指定与索引器数据源的连接。如果要更新数据源定义，则不需要连接字符串。值 <unchanged> 或 <redacted> 可用于代替实际连接字符串。

对于使用密钥或登录凭据进行身份验证的连接，这些值在连接字符串中可见。连接字符串的格式取决于数据源类型：

对于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 资源 ID， (查看以下连接字符串格式的链接：Azure 存储、Cosmos DB SQL 数据库) 。

作用域为外部数据源的角色分配确定索引器是否可以连接，并且搜索服务必须配置为在 Azure Active Directory 中作为受信任的服务运行。

如果还指定了“identity”属性，则使用“identity”属性提供的搜索服务用户分配的托管标识建立连接。否则，如果“identity”未指定或为 null，则连接通过系统管理的标识。

dataChangeDetectionPolicy

指定数据平台提供的用于识别已更改数据的机制。支持的策略因数据源类型而异。

Attribute 说明

dataChangeDetectionPolicy

Attribute	说明
dataChangeDetectionPolicy	可选。有效的策略包括 `HighWatermarkChangeDetectionPolicy` 或 `SqlIntegratedChangeDetectionPolicy`。 `HighWatermarkChangeDetectionPolicy` 依赖于与其他更新一起更新的现有列或属性， (所有插入都会导致水印列) 更新，并且值的变化更高。 `SqlIntegratedChangeDetectionPolicy`用于引用 SQL Server 中的本机更改检测功能。此策略只能与表一起使用;它不能与视图一起使用。需要先为要使用的表启用更改跟踪，才可以使用此策略。有关说明，请参阅启用和禁用更改跟踪。
highWaterMarkColumnName	对于 `HighWatermarkChangeDetectionPolicy` 是必需的。对于 Cosmos DB，列必须是 `_ts` 属性。对于Azure SQL，建议使用索引`rowversion`列。对于 Azure 存储，更改检测是内置的，使用 lastModified 值，无需设置 dataChangeDetectionPolicy。

可选。有效的策略包括 HighWatermarkChangeDetectionPolicy 或 SqlIntegratedChangeDetectionPolicy。

HighWatermarkChangeDetectionPolicy 依赖于与其他更新一起更新的现有列或属性， (所有插入都会导致水印列) 更新，并且值的变化更高。

SqlIntegratedChangeDetectionPolicy用于引用 SQL Server 中的本机更改检测功能。此策略只能与表一起使用;它不能与视图一起使用。需要先为要使用的表启用更改跟踪，才可以使用此策略。有关说明，请参阅启用和禁用更改跟踪。

highWaterMarkColumnName 对于 HighWatermarkChangeDetectionPolicy 是必需的。对于 Cosmos DB，列必须是 _ts 属性。对于Azure SQL，建议使用索引rowversion列。对于 Azure 存储，更改检测是内置的，使用 lastModified 值，无需设置 dataChangeDetectionPolicy。

dataDeletionDetectionPolicy

指定数据平台提供的用于标识已删除数据的机制。支持的策略因数据源类型而异。

Attribute	说明
dataDeletionDetectionPolicy	可选。有效值为 `SoftDeleteColumnDeletionDetectionPolicy` 或 `NativeBlobSoftDeleteDeletionDetectionPolicy` (请参阅本机 blob 软删除 (预览) ) 。目前，唯一正式可用的策略是`SoftDeleteColumnDeletionDetectionPolicy`，它根据数据源中“软删除”列或属性的值来标识已删除的项。
softDeleteColumnName”	必需。数据源中提供指定行删除状态的值的列的名称。例如，可以创建名为“IsDeleted”的列。仅支持包含字符串、整数或布尔值的列。
softDeleteMarkerValue	必需。软删除列的值。用作 `softDeleteMarkerValue` 的值必须是字符串，即使相应的列包含整数或布尔值也是如此。例如，如果数据源中显示的值为 1，请使用“1”作为 `softDeleteMarkerValue`。如果索引器从软删除列读取此值，则会从搜索索引中删除相应的搜索文档。

encryptionKey

(CMK) 配置与 Azure 密钥保管库的连接，以获取客户管理的加密密钥。使用客户管理的密钥进行加密不适用于免费服务。对于可计费服务，它仅适用于在 2019-01-01 或之后创建的搜索服务。

必须对与密钥保管库的连接进行身份验证。为此，可以使用“accessCredentials”或托管标识。

托管标识可以是系统分配的，也可以是用户分配的 (预览) 。如果搜索服务同时具有系统分配的托管标识和授予对密钥保管库的读取访问权限的角色分配，则可以省略“identity”和“accessCredentials”，请求将使用托管标识进行身份验证。如果搜索服务具有用户分配的标识和角色分配，请将“identity”属性设置为该标识的资源 ID。

Attribute	说明
keyVaultKeyName	必需。用于加密的 Azure 密钥保管库密钥的名称。
keyVaultKeyVersion	必需。 Azure 密钥保管库密钥的版本。
keyVaultUri	必需。 Azure 密钥保管库 (的 URI 也称为提供密钥的 DNS 名称) 。 URI 示例可能是 `https://my-keyvault-name.vault.azure.net`。
accessCredentials	如果使用托管标识，请省略。否则，的属性`accessCredentials`包括 `applicationId` (对指定的 Azure 密钥保管库) 具有访问权限的 Azure Active Directory 应用程序 ID， (`applicationSecret` 指定的 Azure AD 应用程序的身份验证密钥) 。
标识	可选，除非将用户分配的托管标识用于与 Azure 密钥保管库的搜索服务连接。格式为 `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`。

创建或更新数据源 (预览版 REST API)

URI 参数

请求标头

请求正文

响应

示例

定义

container

凭据

dataChangeDetectionPolicy

dataDeletionDetectionPolicy

encryptionKey

另请参阅

其他资源