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

  • 作者
    • WenJie Yu

适用于：Azure Stack 集成系统和 Azure Stack 开发工具包

用于 Azure Stack 资源管理器的 Java SDK 提供了相关工具来帮助构建和管理基础结构。 该 SDK 中的资源提供程序包括了计算、网络、存储、应用服务和 KeyVault。 Java SDK 纳入了 API 配置文件，其方法是：将依赖项包括在 Pom.xml 文件中，由后者加载 .java 文件中的正确模块。 不过，可以添加多个作为依赖项的配置文件，例如，添加 2018-03-01-hybrid 或 latest 作为 Azure 配置文件。 使用这些依赖项来加载正确的模块，这样在创建资源类型时，就可以从那些要使用的配置文件中选择具体的 API 版本。 这样就可以使用 Azure 中的最新版本，同时使用 Azure Stack 的最新 API 版本进行开发。 使用 Java SDK 可以获得真正的混合云开发人员体验。 Java SDK 中的 API 配置文件可以用来在公有云 Azure 资源和 Azure Stack 中的资源之间进行切换，实现混合云开发。

Java 与 API 版本配置文件

API 配置文件是资源提供程序和 API 版本的组合。 可以使用 API 配置文件获取资源提供程序包中每个资源类型的最新且最稳定的版本。

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

    • 若使用 latest 配置文件，则依赖项为 com.microsoft.azure。

    • 若要使用与 Azure Stack 兼容的服务，请使用 com.microsoft.azure.profile_2018_03_01_hybrid 配置文件。

      • 请在 Pom.xml 文件中将其指定为依赖项，如果从下拉列表中选择了正确的类，则会自动加载模块，就像使用 .NET 一样。

      • 每个模块的顶部如下所示：
        Import com.microsoft.azure.management.resources.v2018_03_01.ResourceGroup

    • 依赖项如下所示：

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

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

请注意，可以在同一应用程序中组合所有选项。

安装 Azure Java SDK

使用以下步骤安装 Java SDK：

  1. 按照正式说明安装 Git。 有关说明，请参阅入门 - 安装 Git。

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

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

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

  4. 需安装的包取决于要使用的配置文件版本。 配置文件版本的包名如下：

    • com.microsoft.azure.profile_2018_03_01_hybrid
    • com.microsoft.azure
      • latest

  5. 如果不可用，请创建一个订阅，并保存订阅 ID 供以后使用。 有关如何创建订阅的说明，请参阅在 Azure Stack 中创建套餐的订阅。

  6. 创建服务主体并保存客户端 ID 和客户端机密。 有关如何为 Azure Stack 创建服务主体的说明，请参阅提供对 Azure Stack 的应用程序访问权限。 请注意，创建服务主体时的客户端 ID 也称为应用程序 ID。

  7. 确保服务主体在订阅上具有“参与者/所有者”角色。 有关如何将角色分配到服务主体的说明，请参阅提供对 Azure Stack 的应用程序访问权限。

先决条件

若要将 Azure Java SDK 与 Azure Stack 配合使用，必须提供以下值，然后使用环境变量来设置值。 若要设置环境变量，请参阅表后针对操作系统的说明。

值 环境变量 说明
租户 ID AZURE_TENANT_ID Azure Stack 租户 ID 的值。
客户端 ID AZURE_CLIENT_ID 在本文档上一部分创建服务主体时保存的服务主体应用程序 ID。
订阅 ID AZURE_SUBSCRIPTION_ID 订阅 ID 用于访问 Azure Stack 中的套餐。
客户端机密 AZURE_CLIENT_SECRET 创建服务主体时保存的服务主体应用程序机密。
资源管理器终结点 ARM_ENDPOINT 请参阅 Azure Stack 资源管理器终结点。
位置 RESOURCE_LOCATION Azure Stack 本地

若要查找 Azure Stack 的租户 ID，请按此处提供的说明操作。 若要设置环境变量，请执行以下操作：

Microsoft Windows

若要在 Windows 命令提示符中设置环境变量，请使用以下格式：

Set AZURE_TENANT_ID=<Your_Tenant_ID>

基于 MacOS、Linux 和 Unix 的系统

在基于 Unix 的系统中，可以使用以下命令：

Export AZURE_TENANT_ID=<Your_Tenant_ID>

Azure Stack 资源管理器终结点

Azure 资源管理器是一种管理框架，可供管理员用来部署、管理和监视 Azure 资源。 Azure 资源管理器可以通过单个操作以组任务而不是单个任务的形式处理这些任务。

可以从资源管理器终结点获取元数据信息。 该终结点返回 JSON 文件，以及运行代码所需的信息。

请注意以下事项：

  • Azure Stack 开发工具包 (ASDK) 中的 ResourceManagerUrl 为： https://management.local.azurestack.external/

  • 集成系统中的 ResourceManagerUrl 为：https://management.<location>.ext-<machine-name>.masd.stbtest.microsoft.com/

检索所需的元数据：<ResourceManagerUrl>/metadata/endpoints?api-version=1.0。

示例 JSON 文件：

{ 
   "galleryEndpoint": "https://portal.local.azurestack.external:30015/",
   "graphEndpoint": "https://graph.chinacloudapi.cn/",
   "portal Endpoint": "https://portal.local.azurestack.external/",
   "authentication": 
      {
      "loginEndpoint": "https://login.chinacloudapi.cn/",
      "audiences": ["https://management.<yourtenant>.partner.onmschina.cn/3cc5febd-e4b7-4a85-a2ed-1d730e2f5928"]
      }
}

现有 API 配置文件

  1. com.microsoft.azure.profile_2018_03_01_hybrid：为 Azure Stack 构建的最新配置文件。 请将此配置文件用于与 Azure Stack 最兼容的服务，前提是使用 1808 或更高的戳记。

  2. com.microsoft.azure：包含所有服务的最新版本的配置文件。 使用所有服务的最新版本。

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

Azure Java SDK API 配置文件的使用

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

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。

定义 Azure Stack 环境设置函数

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

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);

使用 API 配置文件的示例

若要使用 .NET 和 Azure Stack API 配置文件来创建解决方案，可以将以下 GitHub 示例用作参考：

示例单元测试项目

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

    git clone https://github.com/Azure-Samples/Hybrid-resources-java-manage-resource-group.git

  2. 创建 Azure 服务主体并分配用于访问订阅的角色。 有关如何创建服务主体的说明，请参阅使用 Azure PowerShell 创建具有证书的服务主体。

  3. 检索以下必需的环境变量值：

    • AZURE_TENANT_ID
    • AZURE_CLIENT_ID
    • AZURE_CLIENT_SECRET
    • AZURE_SUBSCRIPTION_ID
    • ARM_ENDPOINT
    • RESOURCE_LOCATION

  4. 使用命令提示符，根据从已创建的服务主体检索的信息设置以下环境变量：

    • export AZURE_TENANT_ID={你的租户 ID}
    • export AZURE_CLIENT_ID={你的客户端 ID}
    • export AZURE_CLIENT_SECRET={你的客户端机密}
    • export AZURE_SUBSCRIPTION_ID={你的订阅 ID}
    • export ARM_ENDPOINT={你的 Azure Stack 资源管理器 URL}
    • export RESOURCE_LOCATION={Azure Stack 的位置}

    在 Windows 中，请使用 set 而不是 export。

  5. 使用 getactivedirectorysettings 代码检索 arm 元数据终结点，使用 HTTP 客户端设置终结点信息。

    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);

  6. 在 pom.xml 文件中添加以下依赖项，以便使用 Azure Stack 的 2018-03-01-hybrid 配置文件。 此依赖项将为计算、网络、存储、KeyVault 和应用服务资源提供程序安装与此配置文件相关联的模块。

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

  7. 在打开的用于设置环境变量的命令提示符中，输入以下行：

    mvn clean compile exec:java

后续步骤

有关 API 配置文件的详细信息，请参阅：