通过

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

创建或更新数据源（预览版 REST API）

  • 项目

适用于：2023-07-01-Preview。 此版本不再受支持。 将立即升级到较新版本。

重要

2023-07-01-Preview（无更改）。

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

  • “凭据” 接受 Azure 资源 ID 作为值，前提是搜索服务在托管标识下运行，并且 Azure 角色分配授予对数据的读取访问权限。
  • “标识” 接受用户分配的托管标识。 此属性是数据连接的第一级。 它还 “encryptionKey”，用于在 Azure Key Vault 中检索客户管理的密钥。
  • 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 参数

参数 描述
服务名称 必填。 将此设置为搜索服务的唯一用户定义的名称。
数据源名称 如果使用 PUT，则 URI 上是必需的。 名称必须是小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。 使用字母或数字启动名称后，只要短划线不连续，名称的其余部分可以包含任何字母、数字和短划线。
api-version 必填。 有关更多版本，请参阅 API 版本。

请求标头

下表描述了必需的和可选的请求标头。

领域 描述
Content-Type 必填。 将此设置为 application/json
api-key 如果使用 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是唯一的系统生成的字符串，用于对搜索服务的请求进行身份验证。 创建请求必须包含设置为管理密钥的 api-key 标头（而不是查询密钥）。 有关详细信息，请参阅 使用密钥身份验证 连接到 Azure AI 搜索。

请求正文

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

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

请求包含以下属性：

财产 描述
名字 必填。 数据源的名称。 数据源名称只能包含小写字母、数字或短划线，不能以短划线开头或结尾，并且限制为 128 个字符。
描述 可选说明。
类型 必填。 必须是受支持的数据源类型之一：Azure Data Lake Storage Gen2
azureblobAzure Blob 存储
azurefilesAzure 文件存储
azuresqlAzure SQL 数据库
azuretableAzure Cosmos DB SQL API的 Azure 表存储
cosmosdb

adlsgen2， MongoDB API、Gremlin API
mysql for Azure Database for MySQL
凭据 必填。 包含一个 connectionString 属性，该属性指定如何连接。
容器 必填。 指定要编制索引数据的容器、集合、表或视图。
dataChangeDetectionPolicy 自选。 指定数据平台提供的用于标识已更改数据项的机制。
dataDeletionDetectionPolicy 自选。 标识数据平台如何删除数据。
encryptionKey 自选。 用于通过 Azure Key Vault 中的 客户管理的加密密钥（CMK） 对数据源凭据进行其他加密。 可用于在 2019-01-01 之后创建的可计费搜索服务。
禁用 自选。 指示索引器是否处于禁用状态的布尔值，这会阻止索引器立即运行。 默认情况下为 False。
身份 自选。 它包含 #Microsoft.Azure.Search.DataUserAssignedIdentity 类型的 userAssignedIdentity，并指定外部资源的 用户分配的托管标识。 此属性取决于 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" }
}

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

容器

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

属性 描述
名字 必填。 对于 Azure Cosmos DB，指定 SQL API 集合。 对于 Azure Blob 存储，指定存储容器。 对于 Azure SQL，指定表或视图。 可以使用架构限定的名称，例如 [dbo].[mytable]。 对于 Azure 表存储，指定表的名称。
查询 自选。 对于 Azure Cosmos DB，可以指定将任意 JSON 文档布局平展为 Azure AI 搜索可以编制索引的平面架构的查询。 对于 Azure Blob 存储，可以在 Blob 容器中指定虚拟文件夹。 例如，对于 blob 路径 mycontainer/documents/blob.pdf，documents 可用作虚拟文件夹。 对于 Azure 表存储，可以指定要导入的行集的查询。 对于 Azure SQL，不支持查询（改用视图）。

凭据

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

属性 描述
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 门户中找到它们。

如果使用 托管标识对进行身份验证，则可以省略连接上的凭据。

有关使用托管标识进行身份验证的连接，连接字符串指定 Azure 资源 ID（请参阅以下连接字符串格式的链接：Azure 存储、Cosmos DB、SQL 数据库）。

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

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

dataChangeDetectionPolicy

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

属性 描述
dataChangeDetectionPolicy 自选。 有效策略包括 HighWatermarkChangeDetectionPolicy 或 SqlIntegratedChangeDetectionPolicy。

HighWatermarkChangeDetectionPolicy 取决于与其他更新一起更新的现有列或属性（所有插入都会导致对水印列进行更新），值的变化更高。

SqlIntegratedChangeDetectionPolicy 用于引用 SQL Server 中的本机更改检测功能。 此策略只能用于表;它不能与视图一起使用。 需要为正在使用的表启用更改跟踪，然后才能使用此策略。 有关说明，请参阅 启用和禁用更改跟踪。
highWaterMarkColumnName HighWatermarkChangeDetectionPolicy是必需的。 对于 Cosmos DB，列必须 _ts 属性。 对于 Azure SQL，建议使用索引 rowversion 列。 对于 Azure 存储，更改检测是使用 lastModified 值内置的，无需设置 dataChangeDetectionPolicy。

dataDeletionDetectionPolicy

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

属性 描述
dataDeletionDetectionPolicy 自选。 有效值 SoftDeleteColumnDeletionDetectionPolicy 或 NativeBlobSoftDeleteDeletionDetectionPolicy（请参阅 本机 blob 软删除（预览版））。

目前，唯一可用的策略是SoftDeleteColumnDeletionDetectionPolicy，它根据数据源中“软删除”列或属性的值标识已删除的项目。

softDeleteColumnName” 必填。 数据源中列的名称，提供指定行删除状态的值。 例如，可以创建名为“IsDeleted”的列。 仅支持包含字符串、整数或布尔值的列。
softDeleteMarkerValue 必填。 软删除列的值。 用作 softDeleteMarkerValue 的值必须是字符串，即使相应的列保存整数或布尔值。 例如，如果数据源中显示的值为 1，请使用“1”作为 softDeleteMarkerValue。 如果索引器从软删除列读取此值，它将从搜索索引中删除相应的搜索文档。

encryptionKey

配置与 Azure Key Vault 的连接，以补充 客户管理的加密密钥（CMK）。 使用客户管理的密钥进行加密不适用于免费服务。 对于计费服务，它仅适用于在 2019-01-01 之后创建的搜索服务。

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

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

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

另请参阅