在 Azure Stack Hub 中将 API 版本配置文件与 Java 配合使用

项目
10/30/2024

重要

Java SDK 已从轨道 1 更新为跟踪 2。建议尽快迁移到轨道 2 SDK。有关说明，请参阅此迁移指南。

用于 Azure Stack Hub 资源管理器的 Java SDK 提供了相关工具来帮助构建和管理基础结构。该 SDK 中的资源提供程序包括计算、网络、存储、应用服务和 Azure Key Vault。可以在 GitHub 上找到混合 Java 示例存储库。本文将帮助你设置你的环境、获取正确的凭据、获取存储库，并在 Azure Stack Hub 中创建资源组。

使用 Java SDK 可以获得真正的混合云开发人员体验。帮助你在全局 Azure 资源与 Azure Stack Hub 中的资源之间进行切换，从而在 Java SDK 的 POM.xml 中切换版本依赖项，启用混合云开发。

要使用服务的最新版本，请使用最新配置文件作为依赖项。

通过使用现有的 com.azure.resourcemanager 依赖项并将版本从 x.y.z 更改为 x.y.z-hybrid，可以将应用定位到 Azure Stack Hub 中的资源。混合包（提供对 Azure Stack Hub 的支持）在版本的末尾使用 -hybrid 后缀，例如 1.0.0-hybrid。这将指向与版本关联的终结点的静态集合。

要获取最新的配置文件，请采用现有的 com.azure.resourcemanager 依赖项，并将版本更改为最新。最新的配置文件 Java 包可提供一致的 Azure 体验。这些包与 Azure com.azure.resourcemanager 共享相同的组 ID。项目 ID 和命名空间也与全局 Azure 相同。这有助于将 Azure 应用移植到 Azure Stack Hub。要详细了解作为混合配置文件的一部分在 Azure Stack Hub 中使用的终结点，请参阅 API 配置文件摘要。

该配置文件在 Maven 项目的 pom.xml 文件中被指定为依赖项。如果从下拉列表中选择正确的类，则该配置文件将自动加载模块（与使用 .NET 时一样）。

设置开发环境

若要准备运行 SDK 的环境，可以使用 ECLIPSE 或 Visual Studio Code 等 IDE，但需要安装 Git、Java SDK 和 Apache Maven。要详细了解设置开发环境的先决条件，请参阅使用 Azure SDK for Java

安装 Git。可以在入门 - 安装 Git 中找到安装 Git 的官方说明。
安装 Java SDK 并将 JAVA_HOME 环境变量设置为 Java 开发工具包的二进制文件的位置。你可以找到 OpenJDK 的可下载安装媒体说明。安装版本 8 或更高版本的 Java 开发人员工具包。
安装 Apache Maven。可在 Apache Maven Project 中找到相关说明。安装 Apache Maven 3.0 版本或更高版本。

Java 与 API 版本配置文件

若要使用所有服务的最新版本，请使用 latest 配置文件作为依赖项。

若使用 latest 配置文件，则依赖项为 com.microsoft.azure。
若要使用 Azure Stack Hub 中提供的最新支持的服务，请使用 com.microsoft.azure.profile_2019_03_01_hybrid 配置文件。
- 在 Pom.xml 文件中将配置文件指定为依赖项，如果从下拉列表中选择了正确的类，则会自动加载模块（就像使用 .NET 一样）。

依赖项如下所示：

<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>

若要使用特定资源提供程序中某个资源类型的特定 API 版本，请使用通过 Intellisense 定义的特定 API 版本。

可以在同一应用中组合所有选项。

安装 Azure Java SDK

执行以下步骤安装 Java SDK：

按照正式说明安装 Git。请参阅入门 - 安装 Git。
按照说明安装 Java SDK 和 Maven。正确的版本是 Java 开发人员工具包的版本 8。正确的 Apache Maven 是 3.0 或更高版本。若要完成快速入门，必须将 JAVA_HOME 环境变量设置为 Java 开发工具包的安装位置。有关详细信息，请参阅使用 Java 和 Maven 创建第一个函数。

若要安装正确的依赖项包，请在 Java 应用中打开 Pom.xml 文件。添加一个依赖项，如以下代码中所示：

<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>

需要安装的包取决于你要使用的配置文件版本。配置文件版本的包名如下：
- com.microsoft.azure.profile_2019_03_01_hybrid
- com.microsoft.azure
  - latest

配置文件

对于包含日期的配置文件，若要使用不同的 SDK 配置文件或版本，请替换中 com.microsoft.azure.profile<date>_hybrid 的日期。例如，对于 2008 版本，配置文件为 2019_03_01，字符串变为 com.microsoft.azure.profile_2019_03_01_hybrid。请注意，有时，SDK 团队会更改包的名称，因此仅用不同日期替换字符串的日期可能不起作用。请参阅下表，了解配置文件与 Azure Stack 版本的关联。

Azure Stack 版本	配置文件
2311	2020_09_01
2301	2020_09_01
2206	2020_09_01
2108	2020_09_01
2102	2020_09_01
2008	2019_03_01

有关 Azure Stack Hub 和 API 配置文件的详细信息，请参阅 API 配置文件的摘要。

服务主体

应创建服务主体及其关联环境信息并将其保存到某个位置。建议使用具有 owner 角色的服务主体，但根据该示例，contributor 角色即可满足要求。有关必需值，请参阅示例存储库中的自述文件。读取的这些值可以是 SDK 语言支持的任何格式，例如我们的示例使用的 JSON 文件格式。并非所有这些值都可以使用，具体取决于所运行的示例。有关更新的示例代码或详细信息，请参阅示例存储库。

租户 ID

若要查找 Azure Stack Hub 的目录或租户 ID，请按照此文中的说明进行操作。

注册资源提供程序

遵循此文档注册所需的资源提供程序。根据要运行的示例，将需要这些资源提供程序。例如，如果要运行 VM 示例，则需要 Microsoft.Compute 资源提供程序注册。

Azure Stack 资源管理器终结点

Azure 资源管理器 (ARM) 是一种管理框架，可供管理员用来部署、管理和监视 Azure 资源。 Azure 资源管理器可以通过单个操作以组任务而不是单个任务的形式处理这些任务。可以从资源管理器终结点获取元数据信息。该终结点返回 JSON 文件，其中包含运行代码所需的信息。

Azure Stack 开发工具包 (ASDK) 中的 ResourceManagerEndpointUrl 是：https://management.local.azurestack.external/。
集成系统中的 ResourceManagerEndpointUrl 为 https://management.region.<fqdn>/，其中 <fqdn> 是完全限定的域名。
检索所需的元数据：<ResourceManagerUrl>/metadata/endpoints?api-version=1.0。有关可用的 API 版本，请参阅 Azure REST API 规范。例如，在 2020-09-01 配置文件版本中，可以将资源提供程序 microsoft.resources 的 api-version 更改为 2019-10-01。

示例 JSON：

{
   "galleryEndpoint": "https://portal.local.azurestack.external:30015/",
   "graphEndpoint": "https://graph.windows.net/",
   "portal Endpoint": "https://portal.local.azurestack.external/",
   "authentication": 
      {
         "loginEndpoint": "https://login.windows.net/",
         "audiences": ["https://management.yourtenant.onmicrosoft.com/3cc5febd-e4b7-4a85-a2ed-1d730e2f5928"]
      }
}

信任 Azure Stack Hub CA 根证书

如果使用的是 Azure Stack 开发工具包 (ASDK)，则必须信任远程计算机上的 CA 根证书。不需要信任 Azure Stack Hub 集成系统的 CA 根证书。

Windows

将 Azure Stack Hub 自签名证书导出到桌面。
在命令提示符下，将目录更改为 %JAVA_HOME%\bin。

运行以下命令：

.\keytool.exe -importcert -noprompt -file <location of the exported certificate here> -alias root -keystore %JAVA_HOME%\lib\security\cacerts -trustcacerts -storepass changeit

现有 API 配置文件

com.microsoft.azure.profile_2019_03_01_hybrid：为 Azure Stack Hub 构建的最新配置文件。使用此配置文件可以使服务与版本 1904 或更高版本的 Azure Stack Hub 最兼容。
com.microsoft.azure.profile_2018_03_01_hybrid：为 Azure Stack Hub 构建的配置文件。使用此配置文件可以使服务与版本 1808 或更高版本的 Azure Stack Hub 兼容。
com.microsoft.azure：包含所有服务的最新版本的配置文件。使用所有服务的最新版本。

有关 Azure Stack Hub 和 API 配置文件的详细信息，请参阅 API 配置文件的摘要。

Azure Java SDK API 配置文件的使用

以下代码用于在 Azure Stack Hub 上对服务主体进行身份验证。它使用租户 ID 和特定于 Azure Stack Hub 的身份验证基准创建令牌：

AzureTokenCredentials credentials = new ApplicationTokenCredentials(client, tenant, key, AZURE_STACK)
                    .withDefaultSubscriptionID(subscriptionID);
Azure azureStack = Azure.configure()
                    .withLogLevel(com.microsoft.rest.LogLevel.BASIC)
                    .authenticate(credentials, credentials.defaultSubscriptionID());

此代码可让你使用 API 配置文件依赖项将应用成功部署到 Azure Stack Hub。

定义 Azure Stack Hub 环境设置函数

若要将 Azure Stack Hub 云注册到正确的终结点，请使用以下代码：

// Get Azure Stack Hub cloud endpoints
final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);

AzureEnvironment AZURE_STACK = new AzureEnvironment(new HashMap<String, String>() {
                {
                    put("managementEndpointUrl", settings.get("audience"));
                    put("resourceManagerEndpointUrl", armEndpoint);
                    put("galleryEndpointUrl", settings.get("galleryEndpoint"));
                    put("activeDirectoryEndpointUrl", settings.get("login_endpoint"));
                    put("activeDirectoryResourceID", settings.get("audience"));
                    put("activeDirectoryGraphResourceID", settings.get("graphEndpoint"));
                    put("storageEndpointSuffix", armEndpoint.substring(armEndpoint.indexOf('.')));
                    put("keyVaultDnsSuffix", ".vault" + armEndpoint.substring(armEndpoint.indexOf('.')));
                }
            });

前面代码中的 getActiveDirectorySettings 调用从元数据终结点检索终结点。它从所做的调用声明环境变量：

public static HashMap<String, String> getActiveDirectorySettings(String armEndpoint) {

    HashMap<String, String> adSettings = new HashMap<String, String>();
    try {

        // create HTTP Client
        HttpClient httpClient = HttpClientBuilder.create().build();

        // Create new getRequest with below mentioned URL
        HttpGet getRequest = new HttpGet(String.format("%s/metadata/endpoints?api-version=1.0",
                             armEndpoint));

        // Add additional header to getRequest which accepts application/xml data
        getRequest.addHeader("accept", "application/xml");

        // Execute request and catch response
        HttpResponse response = httpClient.execute(getRequest);

        // Check for HTTP response code: 200 = success
        if (response.getStatusLine().getStatusCode() != 200) {
            throw new RuntimeException("Failed : HTTP error code : " + response.getStatusLine().getStatusCode());
        }

        String responseStr = EntityUtils.toString(response.getEntity());
        JSONObject responseJson = new JSONObject(responseStr);
        adSettings.put("galleryEndpoint", responseJson.getString("galleryEndpoint"));
        JSONObject authentication = (JSONObject) responseJson.get("authentication");
        String audience = authentication.get("audiences").toString().split("\"")[1];
        adSettings.put("login_endpoint", authentication.getString("loginEndpoint"));
        adSettings.put("audience", audience);
        adSettings.put("graphEndpoint", responseJson.getString("graphEndpoint"));

    } catch (ClientProtocolException cpe) {
        cpe.printStackTrace();
        throw new RuntimeException(cpe);
    } catch (IOException ioe) {
        ioe.printStackTrace();
        throw new RuntimeException(ioe);
    }
    return adSettings;
}

示例单元测试项目

使用以下命令克隆存储库：

git clone https://github.com/Azure-Samples/Hybrid-Java-Samples.git -b resourcegroup-2019-03-01-hybrid

创建 Azure 服务主体并分配用于访问订阅的角色。有关如何创建服务主体的说明，请参阅使用 Azure PowerShell 创建具有证书的服务主体。
检索以下必需的环境变量：
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_SUBSCRIPTION_ID
- ARM_ENDPOINT
- RESOURCE_LOCATION
使用命令提示符，根据从已创建的服务主体检索的信息设置以下环境变量：
- export AZURE_TENANT_ID={your tenant ID}
- export AZURE_CLIENT_ID={your client ID}
- export AZURE_CLIENT_SECRET={your client secret}
- export AZURE_SUBSCRIPTION_ID={your subscription ID}
- export ARM_ENDPOINT={your Azure Stack Hub Resource Manager URL}
- export RESOURCE_LOCATION={location of Azure Stack Hub}
在 Windows 中，请使用 set 而不是 export。

使用 getActiveDirectorySettings 函数检索 Azure 资源管理器元数据终结点。

// Get Azure Stack Hub cloud endpoints
final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);

在 Pom.xml 文件中，添加以下依赖项，以便将 2019-03-01-hybrid 配置文件用于 Azure Stack Hub。此依赖项将为计算、网络、存储、Key Vault 和应用服务资源提供程序安装与此配置文件关联的模块：
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
在打开的用于设置环境变量的命令提示符中，输入以下命令：
```
mvn clean compile exec:java
```

示例

有关最新更新 (跟踪 2) 示例代码，请参阅此示例存储库。有关跟踪 1 示例代码，请参阅此示例存储库。根 README.md 描述一般要求，每个子目录都包含一个特定示例，内有其自己的关于如何运行该示例的 README.md。

有关适用于 Azure Stack 版本 2008 或配置文件 2019-03-01 及更低版本的示例，请参阅此文。

后续步骤

了解有关 API 配置文件的详细信息：

通过