Azure Stack Hub での Java による API バージョンのプロファイルの使用

[アーティクル]
10/30/2024

重要

Java SDK は、トラック 1 からトラック 2 に更新されました。できるだけ早くトラック 2 SDK に移行することをお勧めします。手順については、こちらの移行ガイドを参照してください。

Azure Stack Hub Resource Manager 向けの Java SDK には、インフラストラクチャの構築と管理に役立つツールが用意されています。 SDK のリソースプロバイダーには、コンピューティング、ネットワーク、ストレージ、アプリサービス、および Azure KeyVault が含まれます。 GitHub で、ハイブリッド Java サンプルリポジトリを見つけることができます。この記事では、環境を設定し、適切な資格情報を取得し、リポジトリを取得して、Azure Stack Hub でリソースグループを作成する方法について説明します。

Java SDK を使用すると、真のハイブリッドクラウド開発者エクスペリエンスを実現できます。 Java SDK に含まれている POM.xml のバージョンの依存関係を切り替えることで、グローバルな Azure リソースと Azure Stack Hub 上のリソース間を切り替えることができ、ハイブリッドクラウド開発を行うことができます。

サービスの最新バージョンを使用するには、依存関係として latest プロファイルを使用します。

既存の com.azure.resourcemanager の依存関係を取得することで Azure Stack Hub のリソースをお使いのアプリの対象とし、バージョンを x.y.z から x.y.z-hybrid に変更することができます。 Azure Stack Hub をサポートするハイブリッドパッケージでは、バージョンの末尾に -hybrid サフィックス (1.0.0-hybrid など) を使用します。これにより、そのバージョンに関連付けられているエンドポイントの静的コレクションが参照されます。

latest プロファイルを取得するには、既存の com.azure.resourcemanager 依存関係を取得し、バージョンを latest に変更します。 latest プロファイル 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 Development Kit のバイナリの場所に設定します。 OpenJDK のダウンロード可能なインストールメディアの手順をご覧ください。 Java Developer Kit のバージョン 8 以降をインストールします。
Apache Maven をインストールします。手順については、「Apache Maven プロジェクト」を参照してください。 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 Developer Kit のバージョン 8 です。 Apache Maven の適切なバージョンは 3.0 以降です。このクイックスタートを完了するには、JAVA_HOME 環境変数を Java Development Kit のインストール場所に設定する必要があります。詳細については、「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

Profiles

日付を含むプロファイルの場合、別の 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 ロールで十分な場合もあります。必要な値については、サンプルリポジトリの README を参照してください。これらの値は、JSON ファイル (このサンプルで使っているもの) など、SDK 言語がサポートする任意の形式で読み取ることができます。実行するサンプルによっては、これらの値のすべてが使われるわけではありません。更新されたサンプルコードや詳細情報については、サンプルリポジトリを参照してください。

テナント ID

Azure Stack Hub のディレクトリまたはテナント ID を確認するには、この記事の手順に従ってください。

リソースプロバイダーを登録する

こちらのドキュメントに従って、必要なリソースプロバイダーを登録してください。実行するサンプルに応じて、これらのリソースプロバイダーが必要になります。たとえば、VM サンプルを実行する場合は、Microsoft.Compute リソースプロバイダーの登録が必要です。

Azure Stack Resource Manager エンドポイント

Azure Resource Manager (ARM) は、管理者が Azure リソースのデプロイ、管理、監視を行えるようにするための管理フレームワークです。 Azure Resource Manager では、これらのタスクを個別に処理するのではなく、グループとして単一の操作で処理することができます。 Resource Manager エンドポイントからメタデータ情報を取得できます。エンドポイントは、コードを実行するために必要な情報と共に、JSON ファイルを返します。

Azure Stack Development Kit (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 では、api-version を、リソースプロバイダー 2019-10-01 用の microsoft.resources に変更することができます。

サンプル 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 Development Kit (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 では、export ではなく set を使用します。
Azure Resource Manager のメタデータエンドポイントを取得するには、getActiveDirectorySettings の関数を使用します。
```
// Get Azure Stack Hub cloud endpoints
final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);
```
Pom.xml ファイルで、Azure Stack Hub 用の 2019-03-01-hybrid プロファイルを使用するために次の依存関係を追加します。この依存関係では、Compute、Networking、Storage、Key Vault、App Services のリソースプロバイダー用の、このプロファイルに関連付けられているモジュールがインストールされます。
```
<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 プロファイルに関する詳細情報

次の方法で共有

Azure Stack Hub での Java による API バージョンのプロファイルの使用

開発環境を設定する

Java と API バージョンのプロファイル

Azure Java SDK のインストール

Profiles

サブスクリプション

サービスプリンシパル

テナント ID

リソースプロバイダーを登録する

Azure Stack Resource Manager エンドポイント

Azure Stack Hub の CA ルート証明書を信頼する

Windows

既存の API プロファイル

Azure Java SDK API プロファイルの使用

Azure Stack Hub 環境設定関数の定義

単体テストプロジェクトのサンプル

サンプル

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Stack Hub での Java による API バージョンのプロファイルの使用

開発環境を設定する

Java と API バージョンのプロファイル

Azure Java SDK のインストール

Profiles

サブスクリプション

サービス プリンシパル

テナント ID

リソース プロバイダーを登録する

Azure Stack Resource Manager エンドポイント

Azure Stack Hub の CA ルート証明書を信頼する

Windows

既存の API プロファイル

Azure Java SDK API プロファイルの使用

Azure Stack Hub 環境設定関数の定義

単体テスト プロジェクトのサンプル

サンプル

次のステップ

フィードバック

その他のリソース

サービスプリンシパル

リソースプロバイダーを登録する

単体テストプロジェクトのサンプル