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

重要

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

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

使用 Java SDK 可实现真正的混合云开发人员体验。 通过在 Java SDK 中 POM.xml 切换版本依赖项,可帮助你在公共 Azure 资源之间切换为 Azure Stack Hub 中的资源来实现混合云开发。

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

可以通过采用现有的 com.azure.resourcemanager 依赖项并将版本从 x.y.z 中更改为 Azure tack Hub 中的资源,将应用定向到 x.y.z-hybrid资源。 混合包(为 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。 可以在使用用于 Java 的 Azure SDK 中找到有关设置开发环境的先决条件的详细信息

  1. 安装 Git。 可以在 入门 - 安装 Git 时找到安装 Git 的官方说明。

  2. 安装 Java SDK 并将环境变量设置为 JAVA_HOME Java 开发工具包的二进制文件的位置。 可以找到 OpenJDK 的可下载安装媒体说明。 安装 8 或更高版本的 Java 开发人员工具包。

  3. 安装 Apache Maven。 可以在 Apache Maven 项目中找到说明。 安装 Apache Maven 为 3.0 或更高版本。

Java 和 API 版本配置文件

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

  • 若要使用最新的配置文件,依赖项为 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:

  1. 按照官方说明安装 Git。 请参阅 入门 - 安装 Git

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

  3. 若要安装正确的依赖项包,请在 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>
    
  4. 需要安装的包集取决于要使用的配置文件版本。 配置文件版本的包名称为:

    • com.microsoft.azure.profile_2019_03_01_hybrid
    • com.microsoft.azure
      • 最新的

个人资料

对于包含日期的配置文件,若要使用不同的 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 配置文件的摘要

订阅

如果还没有订阅,请创建订阅,并保存稍后要使用的订阅 ID。 有关如何创建订阅的详细信息,请参阅此文档

服务主体

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

租户 ID

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

注册资源提供程序

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

Azure Stack 资源管理器终结点

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

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

示例 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"]
      }
}

信任 Azure Stack Hub CA 根证书

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

Windows操作系统

  1. 将 Azure Stack Hub 自签名证书导出到桌面。

  2. 在命令提示符中,将目录更改为 %JAVA_HOME%\bin.

  3. 运行下面的命令:

    .\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 构建的最新配置文件。 将此配置文件用于与 Azure Stack Hub 最兼容的服务,前提是你使用的是 1904 或更高版本。

  • com.microsoft.azure.profile_2018_03_01_hybrid:为 Azure Stack Hub 生成的配置文件。 将此配置文件用于与 Azure Stack Hub 版本 1808 或更高版本兼容的服务。

  • 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;
}

示例单元测试项目

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

    git clone https://github.com/Azure-Samples/Hybrid-Java-Samples.git -b resourcegroup-2019-03-01-hybrid
    
  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={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 中,使用 而不是 导出

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

    // Get Azure Stack Hub cloud endpoints
    final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);
    
  6. Pom.xml 文件中,添加以下依赖项以使用 Azure Stack Hub 的 2019-03-01-hybrid 配置文件。 此依赖项为计算、网络、存储、Key Vault 和应用服务资源提供程序安装与此配置文件关联的模块:

    <dependency>
      <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
      <artifactId>azure</artifactId>
      <version>1.0.0-beta-1</version>
    </dependency>
    
  7. 在打开以设置环境变量的命令提示符中,输入以下命令:

    mvn clean compile exec:java
    

示例

请参阅此示例存储库,获取最新 (track 2) 示例代码。 有关 track 1 示例代码,请参阅此示例存储库。 根 README.md 描述一般要求,每个子目录都包含一个具体示例,并附有 README.md 关于如何运行该示例的说明。

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

后续步骤

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