升级到 Azure 认知搜索 .NET SDK 版本 10Upgrade to Azure Cognitive Search .NET SDK version 10
如果你使用的是 9.0 或更低版本的 .NET SDK,本文可帮助你升级应用程序,以使用版本 10。If you're using version 9.0 or older of the .NET SDK, this article will help you upgrade your application to use version 10.
Azure 搜索在版本 10 中重命名为 Azure 认知搜索,但命名空间和包名不变。Azure Search is renamed to Azure Cognitive Search in version 10, but namespaces and package names are unchanged. 以前的 SDK 版本(9.0 及更低版本)仍使用以前的名称。Previous versions of the SDK (9.0 and earlier) continue to use the former name. 若要详细了解如何使用 SDK(包括示例),请参阅如何从 .NET 应用程序使用 Azure 认知搜索。For more information about using the SDK, including examples, see How to use Azure Cognitive Search from a .NET Application.
版本 10 中增加了多项功能和 bug 修复,使其功能级别与 REST API 版本 2019-05-06
相同。Version 10 adds several features and bug fixes, bringing it to the same functional level as the REST API version 2019-05-06
. 如果某项更改会中断现有的代码,我们将逐步引导你解决相关的问题。In cases where a change breaks existing code, we'll walk you through the steps required to resolve the issue.
备注
如果你使用的是版本 8.0-preview 或更低版本,应先升级到版本 9,再升级到版本 10。If you're using version 8.0-preview or older, you should upgrade to version 9 first, and then upgrade to version 10. 有关说明,请参阅升级到 Azure 搜索 .NET SDK 版本 9。See Upgrading to the Azure Search .NET SDK version 9 for instructions.
搜索服务实例支持多个 REST API 版本,包括最新的版本。Your search service instance supports several REST API versions, including the latest one. 可以不使用最新版本,但是我们建议迁移代码,以便使用最新版本。You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. 使用 REST API 时,必须在每个请求中通过 api-version 参数指定 API 版本。When using the REST API, you must specify the API version in every request via the api-version parameter. 使用 .NET SDK 时,使用的 SDK 版本确定对应的 REST API 版本。When using the .NET SDK, the version of the SDK you're using determines the corresponding version of the REST API. 如果使用较旧的 SDK,即使已升级服务以支持较新的 API 版本,也可以继续运行代码,而不进行任何更改。If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.
版本 10 中的新增功能What's new in version 10
Azure 认知搜索 .NET SDK 版本 10 面向 REST API 2019-05-06
,其中包含以下更新:Version 10 of the Azure Cognitive Search .NET SDK targets REST API 2019-05-06
with these updates:
- 引入了两项新技能 - 条件技能和文本翻译技能。Introduction of two new skills - Conditional skill and Text Translation skill.
- 重新组织了整形程序技能输入的结构,以适应嵌套上下文的合并。Shaper skill inputs have been restructured to accommodate consolidation from nested contexts. 有关详细信息,请参阅此示例 JSON 定义。For more information, see this example JSON definition.
- 添加了两个新的字段映射函数:Addition of two new field mapping functions:
- 在某些情况下,索引器执行状态中显示的错误和警告可以提供有助于调试的更多详细信息。On certain occasions, errors and warnings that show up in indexer execution status can have additional details that help in debugging.
IndexerExecutionResult
已更新,以反映此行为。IndexerExecutionResult
has been updated to reflect this behavior. - 可以选择性地通过指定
name
属性来识别技能集中定义的单个技能。Individual skills defined within a skillset can optionally be identified by specifying aname
property. ServiceLimits
显示复杂类型的限制,IndexerExecutionInfo
显示相关的索引器限制/配额。ServiceLimits
shows limits for complex types andIndexerExecutionInfo
shows pertinent indexer limits/quotas.
升级步骤Steps to upgrade
按以下方式更新
Microsoft.Azure.Search
的 NuGet 引用:使用 NuGet 包管理器控制台,或者在 Visual Studio 中右键单击项目引用,然后选择“管理 NuGet 程序包...”。Update your NuGet reference forMicrosoft.Azure.Search
using either the NuGet Package Manager Console or by right-clicking on your project references and selecting "Manage NuGet Packages..." in Visual Studio.在 NuGet 已下载新的程序包及其依赖项后,请重新生成项目。Once NuGet has downloaded the new packages and their dependencies, rebuild your project.
如果生成失败,则需要修复每个生成错误。If your build fails, you will need to fix each build error. 有关如何解决每个潜在生成错误的详细信息,请参阅版本 10 中的中断性变更。See Breaking changes in version 10 for details on how to resolve each potential build error.
在修复了任何生成错误或警告后,可以对应用程序进行更改,以利用新功能(如果愿意)。Once you've fixed any build errors or warnings, you can make changes to your application to take advantage of new functionality if you wish. 有关 SDK 中的新功能的详细信息,请参阅版本 10 中的新增功能。New features in the SDK are detailed in What's new in version 10.
版本 10 中的中断性变更Breaking changes in version 10
除重新生成应用程序以外,版本 10 中还有几项可能需要更改代码的中断性变更。There are several breaking changes in version 10 that may require code changes in addition to rebuilding your application.
备注
以下更改列表并不详尽。The list of changes below is not exhaustive. 某些更改可能不会导致生成错误,但在技术上是中断性的,因为它们会破坏与依赖于早期版本 Azure 认知搜索.NET SDK 程序集的程序集的二进制兼容性。Some changes will likely not result in build errors, but are technically breaking since they break binary compatibility with assemblies that depend on earlier versions of the Azure Cognitive Search .NET SDK assemblies. 属于此类别的重大更改也会随建议一起列出。Significant changes that fall under this category are also listed along with recommendations. 升级到版本 10 时请重新生成应用程序,以免出现任何二进制兼容性问题。Please rebuild your application when upgrading to version 10 to avoid any binary compatibility issues.
自定义 Web API 技能定义Custom Web API skill definition
版本 9 和更低版本中错误地指定了自定义 Web API 技能的定义。The definition of the Custom Web API skill was incorrectly specified in version 9 and older.
WebApiSkill
的模型将 HttpHeaders
指定为包含字典的对象属性。The model for WebApiSkill
specified HttpHeaders
as an object property that contains a dictionary. 以这种方式创建带有 WebApiSkill
构造的技能集会导致异常,因为 REST API 会将请求视为格式不当。Creating a skillset with a WebApiSkill
constructed in this manner would result in an exception because the REST API would consider the request badly formed. 此问题已得到更正,HttpHeaders
现在会设置为 WebApiSkill
模型本身上的顶级字典属性 - 请求被视为来自 REST API 的有效请求。This issue has been corrected, by making HttpHeaders
a top-level dictionary property on the WebApiSkill
model itself - which is considered a valid request from the REST API.
例如,如果你以前尝试按如下所示实例化 WebApiSkill
:For example, if you previously attempted to instantiate a WebApiSkill
as follows:
var webApiSkill = new WebApiSkill(
inputs,
outputs,
uri: "https://contoso.example.org")
{
HttpHeaders = new WebApiHttpHeaders()
{
Headers = new Dictionary<string, string>()
{
["header"] = "value"
}
}
};
将它更改为以下代码可以避免 REST API 出现验证错误:change it to the following, to avoid the validation error from the REST API:
var webApiSkill = new WebApiSkill(
inputs,
outputs,
uri: "https://contoso.example.org")
{
HttpHeaders = new Dictionary<string, string>()
{
["header"] = "value"
}
};
整形程序技能允许嵌套的上下文合并Shaper skill allows nested context consolidation
整形程序技能现在允许合并嵌套上下文中的输入。Shaper skill can now allow input consolidation from nested contexts. 为了实现此更改,我们修改了 InputFieldMappingEntry
,这样,只需指定 Source
属性,或者同时指定 SourceContext
和 Inputs
属性,即可将其实例化。To enable this change, we modified InputFieldMappingEntry
so that it can be instantiated by specifying just a Source
property, or both the SourceContext
and Inputs
properties.
你很有可能不需要进行任何代码更改;但请注意,只允许这两种组合中的一种。You will most likely not need to make any code changes; however note that only one of these two combinations is allowed. 这意味着:This means:
- 创建只初始化
Source
的InputFieldMappingEntry
是有效操作。Creating anInputFieldMappingEntry
where onlySource
is initialized is valid. - 创建只初始化
SourceContext
和Inputs
的InputFieldMappingEntry
是有效操作。Creating anInputFieldMappingEntry
where onlySourceContext
andInputs
are initialized is valid. - 涉及这三个属性的所有其他组合是无效的。All other combinations involving those three properties are invalid.
如果你决定开始利用此新功能,请确保在实施该更改之前,先将所有客户端更新为使用版本 10。If you decide to start making use of this new capability, make sure all your clients are updated to use version 10 first, before rolling out that change. 否则,客户端(使用较旧版本的 SDK)对整形程序技能做出的更新可能导致验证错误。Otherwise, there is a possibility that an update by a client (using an older version of the SDK) to the Shaper skill may result in validation errors.
备注
即使已将底层 InputFieldMappingEntry
模型修改为允许从嵌套上下文合并,但只能在整形程序技能的定义内使用该模型。Even though the underlying InputFieldMappingEntry
model has been modified to allow consolidation from nested contexts, it's use is only valid within the definition of a Shaper skill. 在其他技能中使用此功能会在运行时导致验证错误(尽管在编译时是正常的)。Using this capability in other skills, while valid at compile time, will result in a validation error at runtime.
可以按名称识别技能Skills can be identified by a name
技能集中的每个技能现在包含一个新属性 Name
,可以在代码中初始化该属性,以帮助识别该技能。Each skill within a skillset now has a new property Name
, which can be initialized in your code to help identify the skill. 这是可选的操作 - 如果未指定(如果未进行显式代码更改,则默认不会指定),将使用技能集中技能的从 1 开始的索引,为该技能分配一个带有“#”前缀字符的默认名称。This is optional - when unspecified (which is the default, if no explicit code change was made), it is assigned a default name using the 1-based index of the skill in the skillset, prefixed with the '#' character. 例如,在以下技能集定义中(对简洁起见,已跳过大部分初始化步骤):For example, in the following skillset definition (most initializations skipped for brevity):
var skillset = new Skillset()
{
Skills = new List<Skill>()
{
new SentimentSkill(),
new WebApiSkill(),
new ShaperSkill(),
...
}
}
为 SentimentSkill
分配了名称 #1
,为 WebApiSkill
分配了名称 #2
,为 ShaperSkill
分配了名称 #3
,依此类推。SentimentSkill
is assigned a name #1
, WebApiSkill
is assigned #2
, ShaperSkill
is assigned #3
and so on.
如果选择按自定义名称识别技能,请务必先将客户端的所有实例更新到 SDK 版本 10。If you choose to identify skills by a custom name, make sure to update all instances of your clients to version 10 of the SDK first. 否则,可能会出现这种问题:使用较旧 SDK 版本的客户端将技能的 Name
属性设置为 null
,从而导致客户端回退到默认命名方案。Otherwise, there is a possibility that a client using an older version of the SDK could null
out the Name
property of a skill, causing the client to fall back on the default naming scheme.
有关错误和警告的详细信息Details about errors and warnings
ItemError
和 ItemWarning
模型(分别用于封装索引器执行期间发生的错误和警告的详细信息)已经过修改,现在包含三个旨在帮助调试索引器的新属性。ItemError
and ItemWarning
models that encapsulate details of errors and warnings (respectively) that occur during an indexer execution have been modified to include three new properties with the objective to aid in debugging the indexer. 这些属性为:These properties are:
Name
:错误来源的名称。Name
: The name of the source at which the error originated. 例如,错误中可能会提到附加的技能集中的特定技能。For example, it could refer to a particular skill in the attached skillset.Details
:有关错误或警告的其他详细信息。Details
: Additional verbose details about the error or warning.DocumentationLink
:针对具体错误或警告的故障排除指南的链接。DocumentationLink
: A link to a troubleshooting guide for the specific error or warning.
备注
我们已开始组织错误和警告的内容,以尽可能地包含这些有用的信息。We have started to structure our errors and warnings to include these useful details whenever possible. 我们正努力确保在所有错误和警告中提供这些详细信息,但这项工作正在进行,并且不一定总会填充这些附加的详细信息。We are working to make sure that for all errors and warnings these details are present, but it is a work in progress and these additional details may not always be populated.
后续步骤Next steps
- 更改整形程序技能很有可能会对新代码或现有代码造成影响。Changes to the Shaper skill have the most potential impact on new or existing code. 接下来,请务必重新访问这个演示输入结构的示例:整形程序技能 JSON 定义示例As a next step, be sure to revisit this example illustrating the input structure: Shaper skill JSON definition example
- 浏览 AI 扩充概述。Go through the AI enrichment overview.
- 我们欢迎你对 SDK 提供反馈。We welcome your feedback on the SDK. 如果遇到问题,请随时通过 Stack Overflow 向我们寻求帮助。If you encounter problems, feel free to ask us for help on Stack Overflow. 如果找到 Bug,可以在 Azure .NET SDK GitHub 存储库中提出问题。If you find a bug, you can file an issue in the Azure .NET SDK GitHub repository. 务必在问题标题上加前缀“[Azure 认知搜索]”。Make sure to prefix your issue title with "[Azure Cognitive Search]".