使用 Azure SDK for JavaUse the Azure SDK for Java

02/02/2021

本文内容

开源 Azure SDK for Java 简化了通过 Java 应用程序代码预配、管理和使用 Azure 资源的过程。The open-source Azure SDK for Java simplifies provisioning, managing, and using Azure resources from Java application code.

重要详细信息Important details

Azure 库可用于从本地或云中运行的 Java 代码与 Azure 服务进行通信。The Azure libraries are how you communicate with Azure services from Java code that you run either locally or in the cloud.

这些库支持 Java 8 及更高版本，并针对 Java 8 基线和最新的 Java“长期支持”版本进行了测试。The libraries support Java 8 and later, and are tested against both the Java 8 baseline and the latest Java 'long-term support' release.

这些库包括完整的 Java 模块支持，这意味着它们完全符合 Java 模块的要求并可以导出所有相关的包以供使用。The libraries include full Java module support, which means that they're fully compliant with the requirements of a Java module and export all relevant packages for use.

Azure SDK for Java 仅由许多与特定 Azure 服务相关的单个 Java 库组成。The Azure SDK for Java is composed solely of many individual Java libraries that relate to specific Azure services. 该“SDK”中没有其他工具。There are no other tools in the "SDK".

有不同的“管理”库和“客户端”库(有时称为“管理平面”库和“数据平面”库)。There are distinct "management" and "client" libraries (sometimes referred to as "management plane" and "data plane" libraries). 每一组的库都有不同的用途，由不同类型的代码使用。Each set serves different purposes and is used by different kinds of code. 有关详细信息，请参阅本文后面的以下部分：For more information, see the following sections later in this article:

可在 Azure for Java 参考(按 Azure 服务进行组织)或 Java API 浏览器(按包名称进行组织)中找到这些库的文档。You can find documentation for the libraries in the Azure for Java Reference organized by Azure Service, or the Java API browser organized by package name.

其他详细信息Other details

Azure SDK for Java 库基于底层 Azure REST API 生成，让你能够通过熟悉的 Java 范例使用这些 API。The Azure SDK for Java libraries build on top of the underlying Azure REST API, allowing you to use those APIs through familiar Java paradigms. 不过，如果需要，始终可以直接通过 Java 代码使用 REST API。However, you can always use the REST API directly from Java code, if you prefer.

可在 GitHub 存储库中找到这些 Azure 库的源代码。You can find the source code for the Azure libraries in the GitHub repository. 作为一个开源项目，你的贡献会受到欢迎！As an open-source project, contributions are welcome!

我们目前正在更新 Azure SDK for Java 库，以共享常见的云模式，如身份验证协议、日志记录、跟踪、传输协议、缓冲响应和重试。We're currently updating the Azure SDK for Java libraries to share common cloud patterns such as authentication protocols, logging, tracing, transport protocols, buffered responses, and retries.

该共享功能包含在 azure-core 库中。This shared functionality is contained in the azure-core library.

有关应用于库的准则的详细信息，请参阅 Java Azure SDK 设计准则。For more information on the guidelines we apply to the libraries, see the Java Azure SDK Design Guidelines.

通过客户端库连接并使用 Azure 资源Connect to and use Azure resources with client libraries

客户端(或“数据平面”)库可帮助你编写 Java 应用程序代码，以与已预配的服务进行交互。The client (or "data plane") libraries help you write Java application code to interact with already-provisioned services. 只有那些支持客户端 API 的服务才存在客户端库。Client libraries exist only for those services that support a client API. 你可以标识它们，因为其 Maven 组 ID 为 com.azure。You can identify them because their Maven group ID is com.azure.

所有 Azure Java 客户端库都遵循相同的 API 设计模式，即提供负责创建客户端实例的 Java 生成器类。All Azure Java client libraries follow the same API design pattern of offering a Java builder class that's responsible for creating an instance of a client. 此模式将客户端的定义和实例化与其操作分离，从而使客户端不可变，因此更易于使用。This pattern separates the definition and instantiation of the client from its operation, allowing the client to be immutable and therefore easier to use. 此外，所有客户端库都遵循几个重要模式：Additionally, all client libraries follow a few important patterns:

支持同步和异步 API 的客户端库必须在单独的类中提供这些 API。Client libraries that support both synchronous and asynchronous APIs must offer these APIs in separate classes. 这意味着，在这些情况下，将有用于同步 API 的 KeyVaultClient 以及用于异步 API 的 KeyVaultAsyncClient。What this means is that in these cases there would be, for example, a KeyVaultClient for sync APIs and a KeyVaultAsyncClient for async APIs.

有一个生成器类负责生成同步和异步 API。There's a single builder class that takes responsibility for building both the sync and async APIs. 生成器的命名方式类似于同步客户端类，其中包含 Builder。The builder is named similarly to the sync client class, with Builder included. 例如 KeyVaultClientBuilder。For example, KeyVaultClientBuilder. 此生成器具有 buildClient() 和 buildAsyncClient() 方法，可根据需要创建客户端实例。This builder has buildClient() and buildAsyncClient() methods to create client instances, as appropriate.

由于这些约定，以 Client 结尾的所有类都是不可变的，并提供与 Azure 服务进行交互的操作。Because of these conventions, all classes ending in Client are immutable and provide operations to interact with an Azure service. 以 ClientBuilder 结尾的所有类都提供用于配置和创建特定客户端类型的实例的操作。All classes that end in ClientBuilder provide operations to configure and create an instance of a particular client type.

客户端库示例Client libraries example

以下代码示例演示如何创建同步 Key Vault KeyClient：The following code example shows how to create a synchronous Key Vault KeyClient:

KeyClient client = new KeyClientBuilder()

.endpoint()

.credential(new DefaultAzureCredentialBuilder().build())

.buildClient();

以下代码示例演示如何创建异步 Key Vault KeyAsyncClient：The following code example shows how to create an asynchronous Key Vault KeyAsyncClient:

KeyAsyncClient client = new KeyClientBuilder()

.endpoint()

.credential(new DefaultAzureCredentialBuilder().build())

.buildAsyncClient();

有关如何使用每个客户端库的详细信息，请参阅 README.md 文件(位于 SDK GitHub 存储库的库项目目录中)。For more information on working with each client library, see the README.md file located in the library's project directory in the SDK GitHub repository. 也可在参考文档和 Azure 示例中找到更多代码片段。You can also find more code snippets in the reference documentation and the Azure Samples.

使用管理库预配和管理 Azure 资源Provision and manage Azure resources with management libraries

管理(或“管理平面”)库可帮助你通过 Java 应用程序代码创建、预配和管理 Azure 资源。The management (or "management plane") libraries help you create, provision and otherwise manage Azure resources from Java application code. 可以在 com.azure.resourcemanager Maven 组 ID 中找到这些库。You can find these libraries in the com.azure.resourcemanager Maven group ID. 所有 Azure 服务都有相应的管理库。All Azure services have corresponding management libraries.

借助管理库，可以编写配置和部署脚本，以执行可通过 Azure 门户或 Azure CLI 执行的相同任务。With the management libraries, you can write configuration and deployment scripts to perform the same tasks that you can through the Azure portal or the Azure CLI.

所有 Azure Java 管理库都提供 *Manager 类作为服务 API，例如，用于 Azure 计算服务的 ComputeManager，或用于常用服务聚合的 AzureResourceManager。All Azure Java management libraries provide a *Manager class as service API, for example, ComputeManager for Azure compute service, or AzureResourceManager for the aggregation of popular services.

管理库示例Management libraries example

以下代码示例演示如何创建 ComputeManager：The following code example shows how to create a ComputeManager:

ComputeManager computeManager = ComputeManager

.authenticate(

new DefaultAzureCredentialBuilder().build(),

new AzureProfile(AzureEnvironment.AZURE));

以下代码示例演示如何预配新的虚拟机：The following code example shows how to provision a new virtual machine:

VirtualMachine virtualMachine = computeManager.virtualMachines()

.define()

.withRegion(Region.US_WEST)

.withExistingResourceGroup()

.withNewPrimaryNetwork("10.0.0.0/28")

.withPrimaryPrivateIPAddressDynamic()

.withoutPrimaryPublicIPAddress()

.withPopularLinuxImage(KnownLinuxVirtualMachineImage.UBUNTU_SERVER_18_04_LTS)

.withRootUsername()

.withSsh()

.create();

以下代码示例演示如何获取现有虚拟机：The following code example shows how to get an existing virtual machine:

VirtualMachine virtualMachine = computeManager.virtualMachines()

.getByResourceGroup(, );

以下代码示例演示如何更新虚拟机并添加新的数据磁盘：The following code example shows how to update the virtual machine and add a new data disk:

virtualMachine.update()

.withNewDataDisk(10)

.apply();

有关如何使用每个管理库的详细信息，请参阅 README.md 文件(位于 SDK GitHub 存储库的库项目目录中)。For more information on working with each management library, see the README.md file located in the library's project directory in the SDK GitHub repository. 也可在参考文档和 Azure 示例中找到更多代码片段。You can also find more code snippets in the reference documentation and the Azure Samples.

获取帮助并与 SDK 团队联系Get help and connect with the SDK team

Post questions to the community on Stack Overflow.

针对 GitHub 存储库中的 SDK 的待解决问题。Open issues against the SDK in the GitHub repository.

在 Twitter 上提及 @AzureSDK。Mention @AzureSDK on Twitter.

后续步骤Next steps

现在，你已了解 Azure SDK for Java 的概念，接下来可以深入了解许多旨在帮助你提高使用库时的工作效率的跨领域概念。Now that you understand what the Azure SDK for Java is, you can take a deep dive into many of the cross-cutting concepts that exist to make you productive when using the libraries. 以下文章提供了良好的起点：The following articles provide good starting points: