管理 Azure Stack 中的 API 版本配置文件Manage API version profiles in Azure Stack

适用于:Azure Stack 集成系统和 Azure Stack 开发工具包Applies to: Azure Stack integrated systems and Azure Stack Development Kit

API 配置文件指定 Azure 资源提供程序和 Azure REST 终结点的 API 版本。API profiles specify the Azure resource provider and the API version for Azure REST endpoints. 可以使用 API 配置文件以不同的语言创建自定义客户端。You can create custom clients in different languages using API profiles. 每个客户端都使用 API 配置文件来与 Azure Stack 的正确的资源提供程序和 API 版本通信。Each client uses an API profile to contact the correct resource provider and API version for Azure Stack.

可以创建一个应用来与 Azure 资源提供程序配合运行,而无需明确区分与 Azure Stack 兼容的每个资源提供程序 API 的版本。You can create an app to work with Azure resource providers without having to sort out exactly which version of each resource provider API is compatible with Azure Stack. 只需将应用程序对应到某个配置文件,SDK 就能还原到正确的 API 版本。Just align your application to a profile; the SDK reverts to the correct API version.

本主题帮助读者了解:This topic helps you:

  • Azure Stack 的 API 配置文件。Understand API profiles for Azure Stack.
  • 了解如何使用 API 配置文件来开发解决方案。Learn how you can use API profiles to develop your solutions.
  • 查看在何处查找代码特定的指导。See where to find code-specific guidance.

API 配置文件的摘要Summary of API profiles

  • API 配置文件用于表示一组 Azure 资源提供程序及其 API 版本。API profiles are used to represent a set of Azure resource providers and their API versions.
  • API 配置文件是为了让你创建跨多个 Azure 云的模板而创建的。API profiles were created for you to create templates across multiple Azure clouds. 配置文件提供兼容且稳定的接口。Profiles provide a compatible and stable interface.
  • 配置文件每年发布四次。Profiles are released four times a year.
  • 使用了以下三个配置文件命名约定:Three profile naming conventions are used:
    • latestlatest
      包含全球 Azure 中发布的最新 API 版本。Contains the most recent API versions released in global Azure.
    • yyyy-mm-dd-hybridyyyy-mm-dd-hybrid
      每两年发布一次,此版本注重于跨多个云的一致性和稳定性。Released biannually, this release focuses on consistency and stability across multiple clouds. 此配置文件以实现最佳 Azure Stack 兼容性为目标。This profile targets optimal Azure Stack compatibility.
    • yyyy-mm-dd-profile 在最佳稳定性与最新功能之间实现平衡。yyyy-mm-dd-profile Balances optimal stability and the latest features.

Azure API 配置文件和 Azure Stack 兼容性Azure API profiles and Azure Stack compatibility

最新 Azure API 配置文件与 Azure Stack 不兼容。The newest Azure API profiles are not compatible with Azure Stack. 可以使用以下命名约定来标识要将哪些配置文件用于 Azure Stack 解决方案。You can use the following naming conventions to identify which profiles to use for your Azure Stack solutions.

最新Latest
此配置文件包含可在全球 Azure 中找到的最新 API 版本,这些版本在 Azure Stack 中不起作用。This profile has the most up-to-date API versions found in global Azure, which do not work in Azure Stack. Latest 包含的重大更改最多。Latest has the largest number of breaking changes. 此配置文件不考虑稳定性以及与其他云的兼容性。The profile puts aside stability and compatibility with other clouds. 如果尝试使用最新的 API 版本,则应使用最新配置文件。If you are trying to use the most up-to-date API versions, Latest is the profile you should use.

Yyyy-mm-dd-hybridYyyy-mm-dd-hybrid
此配置文件在每年的三月份和九月份发布。This profile is released in March and September every year. 它具有最佳的稳定性以及与各种云的兼容性。It has optimal stability and compatibility with various clouds. Yyyy-mm-dd-hybrid 是以全球 Azure 和 Azure Stack 作为应用目标而设计的。Yyyy-mm-dd-hybrid is designed to target global Azure and Azure Stack. 此配置文件中列出的 Azure API 版本将与 Azure Stack 上列出的相同。The Azure API versions listed in this profile will be the same as the ones that are listed on Azure Stack. 可以使用此配置文件来为混合云解决方案开发代码。You can use this profile to develop code for hybrid cloud solutions.

yyyy-mm-dd-profileyyyy-mm-dd-profile
此配置文件在六月份和九月份针对全球 Azure 发布。This profile is released for global Azure in June and December. 此配置文件对 Azure Stack 不起作用;通常,其中包含许多重大更改。It does not work with Azure Stack; typically, there will be many breaking changes. 虽然它在最佳稳定性与最新功能之间实现了平衡,但最新配置文件与此配置文件之间的区别是最新配置文件始终包含最新的 API 版本,无论 API 是何时发布的。Although it balances optimal stability and the latest features, the difference between Latest and this profile is that Latest always consists of the newest API versions, regardless of when the API was released. 例如,如果明天为“计算 API”创建一个新的 API 版本,则该 API 版本将列在最新配置文件中,但不会列在 yyyy-mm-dd-profile 中,因为此配置文件已经存在。For example, if a new API version is created for the Compute API tomorrow, that API version is listed in the Latest, but not in the yyyy-mm-dd-profile profile, because this profile already exists. yyyy-mm-dd-profile 涵盖了六月份或九月份之前发布的最新版本。yyyy-mm-dd-profile covers the most up-to-date versions released before June or before December.

Azure 资源管理器 API 配置文件Azure Resource Manager API profiles

Azure Stack 不使用全球 Azure 中提供的最新版 API。Azure Stack does not use the latest version of the API versions found in global Azure. 在创建解决方案时,必须为每个 Azure 资源提供程序查找与 Azure Stack 兼容的 API 版本。When you create a solution, you must find the API version for each Azure resource provider that is compatible with Azure Stack.

你可以使用 API 配置文件,而无需研究 Azure Stack 支持的每个资源提供程序和特定版本。Rather than research every resource provider and the specific version supported by Azure Stack, you can use an API profile. 配置文件会指定一组资源提供程序和 API 版本。The profile specifies a set of resource providers and API versions. SDK 或者使用 SDK 生成的工具将还原到配置文件中指定的目标 api-versionThe SDK, or a tool built with the SDK, will revert to the target api-version specified in the profile. 使用 API 配置文件可以指定应用到整个模板的配置文件版本,在运行时,Azure 资源管理器会选择正确的资源版本。With API profiles, you can specify a profile version that applies to an entire template and at runtime, the Azure Resource Manager selects the right version of the resource.

API 配置文件可与使用 Azure 资源管理器的工具(例如 PowerShell、Azure CLI、SDK 中提供的代码,以及 Microsoft Visual Studio)配合运行。API profiles work with tools that use Azure Resource Manager, such as PowerShell, Azure CLI, code provided in the SDK, and Microsoft Visual Studio. 工具和 SDK 可以使用配置文件来读取生成应用程序时要包含的模块和库的版本。Tools and SDKs can use profiles to read which version of the modules and libraries to include when building an application.

例如,如果通过 PowerShell 使用支持 api-version 2016-03-30 的 Microsoft.Storage 资源提供程序创建存储帐户,并使用 api-version 为 2015-12-01 的 Microsoft.Compute 资源提供程序创建 VM,则必须查看哪个 PowerShell 模块支持将 2016-03-30 用于存储,以及哪个模块支持将 2015-02-01 用于计算,然后安装这两个模块。For example, if you use PowerShell to create a storage account using the Microsoft.Storage resource provider, which supports api-version 2016-03-30 and a VM using the Microsoft.Compute resource provider with api-version 2015-12-01, you must look up which PowerShell module supports 2016-03-30 for Storage, and which module supports 2015-02-01 for Compute, and then install them. 可以改用配置文件。Instead, you can use a profile. 使用 cmdlet Install-Profile <profilename>,然后 PowerShell 会加载正确的模块版本。Use the cmdlet Install-Profile <profilename>, and PowerShell loads the right version of the modules.

同样,在使用 Python SDK 生成基于 Python 的应用程序时,可以指定配置文件。Similarly, when using the Python SDK to build a Python-based application, you can specify the profile. SDK 将为脚本中指定的资源提供程序加载正确的模块。The SDK loads the right modules for the resource providers that you have specified in your script.

开发人员可以专注于编写解决方案。As a developer, you can focus on writing your solution. 无需研究哪些 API 版本、资源提供程序和云可一起运行,而可以使用配置文件,确定代码可跨所有支持该配置文件的云运行。Instead of researching which API versions, resource provider, and cloud work together, you can use a profile and know that your code works across all clouds that support that profile.

API 配置文件代码示例API profile code samples

可以借助代码示例,通过配置文件将采用偏好语言的解决方案与 Azure Stack 相集成。You can find code samples to help you integrate your solution with your preferred language with Azure Stack by using profiles. 目前可以找到以下语言的指导和示例:Currently, you can find guidance and samples for the following languages:

  • .NET 可以使用 .NET API 配置文件获取资源提供程序包中每个资源类型的最新且最稳定的版本。.NET You can use the .NET API profile to get the latest, most stable version of each resource type in a resource provider package. 有关详细信息,请参阅在 Azure Stack 中将 API 版本配置文件与 .NET 配合使用For more information, see Use API version profiles with .NET in Azure Stack.
  • PowerShellPowerShell
    可以使用通过 PowerShell 库提供的 AzureRM.Bootstrapper 模块来获取使用 API 版本配置文件所需的 PowerShell cmdlet。You can use the AzureRM.Bootstrapper module available through the PowerShell Gallery to get the PowerShell cmdlets required to work with API version profiles. 有关信息,请参阅使用适用于 PowerShell 的 API 版本配置文件For information, see Use API version profiles for PowerShell.
  • Azure CLIAzure CLI
    可将环境配置更新为使用 Azure Stack 特定的 API 版本配置文件。You can update your environment configuration to use the Azure Stack specific API version profile. 有关信息,请参阅使用适用于 Azure CLI 的 API 版本配置文件For information, see Use API version profiles for Azure CLI.
  • GoGo
    在 Go SDK 中,配置文件结合了不同服务的不同版本的不同资源类型。In the Go SDK, a profile is a combination of different resource types with different versions from different services. 配置文件在 profiles/ 路径下提供,其版本采用 YYYY-MM-DD 格式。Profiles are available under the profiles/path, with their version in the YYYY-MM-DD format. 有关信息,请参阅使用适用于 Go 的 API 版本配置文件For information, see Use API version profiles for Go.
  • RubyRuby
    用于 Azure Stack 资源管理器的 Ruby SDK 提供了相关工具来帮助构建和管理基础结构。The Ruby SDK for the Azure Stack Resource Manager provides tools to help you build and manage your infrastructure. 该 SDK 中的资源提供程序包括了采用 Ruby 语言的计算、虚拟网络和存储提供程序。Resource providers in the SDK include compute, virtual networks, and storage with the Ruby language. 有关信息,请参阅将 API 版本配置文件与 Ruby 配合使用For information, see Use API version profiles with Ruby
  • PythonPython
    Python SDK 支持 API 版本配置文件将不同的云平台(例如 Azure Stack 和 Azure 公有云)用作目标。The Python SDK supports API version profiles to target different cloud platforms such as Azure Stack and global Azure. 可以使用 API 配置文件为混合云创建解决方案。You can use API profiles to create solutions for a hybrid cloud. 有关信息,请参阅将 API 版本配置文件与 Python 配合使用For information, see Use API version profiles with Python

后续步骤Next steps