Verwenden von API-Versionsprofilen mit Java in Azure Stack Hub

Artikel
04/08/2024

Wichtig

Das Java SDK wurde von Track 1 auf Track 2 aktualisiert. Es wird empfohlen, so schnell wie möglich zum Track 2 SDK zu migrieren. Anweisungen finden Sie in diesem Migrationsleitfaden.

Das Java SDK für Azure Stack Hub Resource Manager stellt Tools zum Erstellen und Verwalten Ihrer Infrastruktur bereit. Zu den Ressourcenanbietern im SDK zählen Compute, Netzwerk, Speicher, App-Dienste und Azure Key Vault. Sie finden das Repository mit Java-Hybridbeispielen auf GitHub. Dieser Artikel unterstützt Sie beim Einrichten Ihrer Umgebung, beim Abrufen der richtigen Anmeldeinformationen und des Repositorys sowie beim Erstellen einer Ressourcengruppe in Azure Stack Hub.

Das Java-SDK ermöglicht eine echte Hybrid Cloud-Entwicklungsumgebung. Das Umschalten der Versionsabhängigkeiten in POM.xml im Java SDK ermöglichen die Entwicklung für Hybrid Cloud, da Sie zwischen globalen Azure-Ressourcen und Ressourcen in Azure Stack Hub wechseln können.

Verwenden Sie das aktuelle Profil als Abhängigkeit, um die aktuellen Versionen der Dienste zu nutzen.

Sie können Ihre App auf Ressourcen in Azure Stack Hub ausrichten, indem Sie die Version Ihrer vorhandenen Abhängigkeit com.azure.resourcemanager von x.y.z in x.y.z-hybrid ändern. Die Hybridpakete, die Unterstützung für Azure Stack Hub bieten, verwenden das Suffix -hybrid am Ende der Version, z. B. 1.0.0-hybrid. Dadurch wird auf eine statische Sammlung von Endpunkten verwiesen, die der Version zugeordnet sind.

Ändern Sie die Version der Abhängigkeit com.azure.resourcemanager in Neueste, um das aktuelle Profil zu erhalten. Die Java-Pakete mit dem neuesten Profil bieten eine einheitliche Erfahrung in Azure. Die Pakete haben die gleiche Gruppen-ID wie Azure com.azure.resourcemanager. Artefakt-ID und Namespaces sind ebenfalls identisch mit denen von Azure weltweit. Dies ist beim Portieren Ihrer Azure-App in Azure Stack Hub hilfreich. Weitere Informationen zu den Endpunkten, die in Azure Stack Hub als Teil des Hybridprofils verwendet werden, finden Sie in der Zusammenfassung der API-Profile.

Das Profil wird in der Datei pom.xml im Maven-Projekt als Abhängigkeit angegeben. Das Profil lädt Module automatisch, wenn Sie die richtige Klasse aus der Dropdownliste auswählen (wie bei .NET).

Einrichten der Entwicklungsumgebung

Um Ihre Umgebung für die Ausführung des SDK vorzubereiten, können Sie eine IDE wie Eclipse oder Visual Studio Code verwenden. Sie müssen jedoch Git, das Java SDK und Apache Maven installiert haben. Details zu den Voraussetzungen für die Einrichtung Ihrer Entwicklungsumgebung finden Sie unter Verwenden des Azure SDK für Java.

Installieren Sie Git. Die offiziellen Anweisungen zum Installieren von Git finden Sie unter Erste Schritte – Installieren von Git.
Installieren Sie das Java SDK, und legen Sie Ihre Umgebungsvariable JAVA_HOME auf den Speicherort der Binärdateien für das Java Development Kit fest. Die Anweisungen für die herunterladbaren Installationsmedien für OpenJDK finden Sie hier. Installieren Sie mindestens Version 8 des Java Developer Kit.
Installieren Sie Apache Maven. Anweisungen hierzu finden Sie im Apache Maven-Projekt. Installieren Sie mindestens Apache Maven 3.0.

Java und API-Versionsprofile

Verwenden Sie das aktuelle Profil als Abhängigkeit, um die aktuellen Versionen aller Dienste zu nutzen.

Die Abhängigkeit zur Verwendung des aktuellen Profils ist com.microsoft.azure.
Um die neuesten unterstützten Dienste zu nutzen, die in Azure Stack Hub verfügbar sind, verwenden Sie das Profil com.microsoft.azure.profile_2019_03_01_hybrid.
- Das Profil wird in der Datei Pom.xml als Abhängigkeit angegeben, die Module automatisch lädt, wenn Sie in der Dropdownliste die richtige Klasse auswählen (wie dies auch bei .NET der Fall ist).

Abhängigkeiten sehen folgendermaßen aus:

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

Zum Verwenden von bestimmten API-Versionen für einen Ressourcentyp in einen bestimmten Ressourcenanbieter verwenden Sie die über IntelliSense definierten API-Versionen.

Sie können alle Optionen in derselben Anwendung kombinieren.

Installieren des Azure Java-SDK

Führen Sie diese Schritte aus, um das Java SDK zu installieren:

Befolgen Sie die offizielle Anleitung zur Installation von Git. Weitere Informationen finden Sie unter Erste Schritte – Installieren von Git.
Befolgen Sie die Anleitung zur Installation des Java SDK und von Maven. Die richtige Version ist Version 8 des Java Developer Kit. Die richtige Version von Apache Maven ist 3.0 oder höher. Damit Sie den Schnellstart durchführen können, muss die Umgebungsvariable JAVA_HOME auf den Installationsspeicherort des Java Development Kit festgelegt sein. Weitere Informationen finden Sie unter Erstellen der ersten Funktion mit Java und Maven.
Zum Installieren der richtigen Abhängigkeitspakete öffnen Sie die Datei Pom.xml in Ihrer Java-Anwendung. Fügen Sie eine Abhängigkeit wie im folgenden Code gezeigt hinzu:
```
<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>
```
Welche Paketsammlungen installiert werden müssen, hängt von der Profilversion ab, die Sie verwenden möchten. Die Paketnamen für die Profilversionen sind:
- com.microsoft.azure.profile_2019_03_01_hybrid
- com.microsoft.azure
  - Neueste

Profiles

Ersetzen Sie bei Profilen, die Datumsangaben enthalten, das Datum in com.microsoft.azure.profile<date>_hybrid, um ein anderes SDK-Profil oder eine andere SDK-Version zu verwenden. Für die Version 2008 lautet das Profil beispielsweise 2019_03_01, und die Zeichenfolge wird zu com.microsoft.azure.profile_2019_03_01_hybrid. Beachten Sie, dass das SDK-Team manchmal den Namen der Pakete ändert, sodass das einfache Ersetzen des Datums einer Zeichenfolge durch ein anderes Datum möglicherweise nicht funktioniert. Informationen zur Zuordnung zwischen Profilen und Azure Stack-Versionen finden Sie in der folgenden Tabelle.

Azure Stack-Version	Profil
2311	2020_09_01
2301	2020_09_01
2206	2020_09_01
2108	2020_09_01
2102	2020_09_01
2008	2019_03_01

Weitere Informationen zu Azure Stack Hub und API-Profilen finden Sie in der Zusammenfassung zu API-Profilen.

Subscription

Wenn Sie noch nicht über ein Abonnement verfügen, erstellen Sie ein Abonnement, und speichern Sie die Abonnement-ID zur späteren Verwendung. Weitere Informationen zum Erstellen eines Abonnements finden Sie in diesem Dokument.

Dienstprinzipal

Ein Dienstprinzipal und seine zugehörigen Umgebungsinformationen sollten erstellt und an einem Ort gespeichert werden. Ein Dienstprinzipal mit der Rolle owner wird empfohlen, aber je nach Beispiel kann eine contributor-Rolle ausreichen. Die erforderlichen Werte finden Sie in der Infodatei im Beispielrepository. Sie können diese Werte in jedem von der SDK-Sprache unterstützten Format lesen, z. B. aus einer JSON-Datei (die in unseren Beispielen verwendet wird). Je nachdem, wie das Beispiel ausgeführt wird, werden möglicherweise nicht alle diese Werte verwendet. Den aktualisierten Beispielcode bzw. weitere Informationen finden Sie im Beispielrepository.

Mandanten-ID

Folgen Sie den Anweisungen in diesem Artikel, um das Verzeichnis oder die Mandanten-ID für Ihre Azure Stack Hub-Instanz zu suchen.

Registrieren von Ressourcenanbietern

Registrieren Sie die erforderlichen Ressourcenanbieter, indem Sie dieses Dokument befolgen. Diese Ressourcenanbieter sind abhängig von den Beispielen, die Sie ausführen möchten, erforderlich. Wenn Sie beispielsweise ein VM-Beispiel ausführen möchten, ist die Registrierung des Ressourcenanbieters Microsoft.Compute erforderlich.

Azure Stack Resource Manager-Endpunkt

Azure Resource Manager (ARM) ist ein Verwaltungsframework, mit dem Administratoren Azure-Ressourcen bereitstellen, verwalten und überwachen können. Azure Resource Manager kann diese Aufgaben als Gruppe – anstatt einzeln – in einem gemeinsamen Vorgang verarbeiten. Sie können die Metadateninformationen vom Resource Manager-Endpunkt abrufen. Der Endpunkt gibt eine JSON-Datei mit den zum Ausführen des Codes erforderlichen Informationen zurück.

Der ResourceManagerEndpointUrl-Wert im Azure Stack Development Kit (ASDK) lautet: https://management.local.azurestack.external/.
Die ResourceManagerUrl in integrierten Systemen lautet https://management.region.<fqdn>/, wobei <fqdn> Ihr vollqualifizierter Domänenname ist.
Zum Abrufen der erforderlichen Metadaten: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0. Verfügbare API-Versionen finden Sie unter Azure REST-API-Spezifikationen. Beispielsweise können Sie in der Profilversion 2020-09-01 für den Ressourcenanbieter microsoft.resourcesapi-version in 2019-10-01 ändern.

JSON-Beispielcode:

{
   "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"]
      }
}

Einstufen des Zertifizierungsstellen-Stammzertifikats für Azure Stack Hub als vertrauenswürdig

Bei Verwendung des Azure Stack Development Kit (ASDK) müssen Sie das Zertifizierungsstellen-Stammzertifikat auf Ihrem Remotecomputer als vertrauenswürdig einstufen. Es ist nicht erforderlich, dass Sie das Zertifizierungsstellen-Stammzertifikat für die integrierten Azure Stack Hub-Systeme als vertrauenswürdig einstufen.

Windows

Exportieren Sie das selbstsignierte Azure Stack Hub-Zertifikat auf Ihren Desktop.
Navigieren Sie an der Eingabeaufforderung zum Verzeichnis %JAVA_HOME%\bin.

Führen Sie den folgenden Befehl aus:

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

Vorhandene API-Profile

com.microsoft.azure.profile_2019_03_01_hybrid: Aktuelles, für Azure Stack Hub erstelltes Profil. Verwenden Sie dieses Profil, um für Dienste die höchste Kompatibilität mit Azure Stack Hub zu erzielen, sofern Sie Version 1904 oder höher nutzen.
com.microsoft.azure.profile_2018_03_01_hybrid: Für Azure Stack Hub erstelltes Profil. Verwenden Sie dieses Profil für Dienste, um Kompatibilität mit Azure Stack Hub Version 1808 oder höher zu erzielen.
com.microsoft.azure: Profil, das aus den neuesten Versionen aller Dienste besteht. Verwenden Sie die neuesten Versionen aller Dienste.

Weitere Informationen zu Azure Stack Hub und API-Profilen finden Sie in der Zusammenfassung zu API-Profilen.

Verwendung des API-Profils aus dem Azure Java-SDK

Der folgende Code authentifiziert den Dienstprinzipal in Azure Stack Hub. Er erstellt anhand der Mandanten-ID und der Authentifizierungsbasis ein für Azure Stack Hub spezifisches Token:

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

Dieser Code ermöglicht Ihnen das Verwenden der API-Profilabhängigkeiten zum erfolgreichen Bereitstellen Ihrer App in Azure Stack Hub.

Definieren von Einstellungsfunktionen für die Azure Stack Hub-Umgebung

Verwenden Sie den folgenden Code, um die Azure Stack Hub-Cloud bei den richtigen Endpunkten zu registrieren:

// 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('.')));
                }
            });

Mit dem getActiveDirectorySettings-Aufruf im obigen Code werden die Endpunkte von den Metadaten-Endpunkten abgerufen. Er gibt die Umgebungsvariablen aus dem vorgenommenen Aufruf an:

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

Beispiel für Komponententestprojekt

Klonen Sie das Repository mit dem folgenden Befehl:

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

Erstellen Sie einen Azure-Dienstprinzipal, und weisen Sie eine Rolle zu, um auf das Abonnement zuzugreifen. Eine Anleitung zur Erstellung eines Dienstprinzipals finden Sie unter Bereitstellen des Anwendungszugriffs auf Azure Stack.
Rufen Sie die folgenden erforderlichen Umgebungsvariablen ab:
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_SUBSCRIPTION_ID
- ARM_ENDPOINT
- RESOURCE_LOCATION
Legen Sie die folgenden Umgebungsvariablen fest, und verwenden Sie dabei die Informationen, die Sie aus dem mithilfe der Eingabeaufforderung erstellten Dienstprinzipal abgerufen haben:
- 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}
Verwenden Sie unter Windows set anstelle von export.

Verwenden Sie die getActiveDirectorySettings-Funktion, um die Azure Resource Manager-Metadatenendpunkte abzurufen.

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

Fügen Sie in der Datei Pom.xml die folgende Abhängigkeit hinzu, um das Profil 2019-03-01-hybrid für Azure Stack Hub zu verwenden. Diese Abhängigkeit installiert die Module, die diesem Profil zugeordnet sind, für die Ressourcenanbieter Compute, Networking, Storage, KeyVault und App Services:
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
Geben Sie an der Eingabeaufforderung, die zum Festlegen der Umgebungsvariablen geöffnet wurde, den folgenden Befehl ein:
```
mvn clean compile exec:java
```

Beispiele

In diesem Beispielrepository finden Sie Beispielcode für update-to-date (Track 2). In diesem Beispielrepository finden Sie Beispielcode für Track 1. In der Stammdatei README.md sind allgemeine Anforderungen beschrieben, und jedes Unterverzeichnis enthält ein bestimmtes Beispiel mit einer eigenen Datei vom Typ README.md, die Informationen zum Ausführen dieses Beispiels enthält.

Hier finden Sie die Beispielanwendung für die Azure Stack-Version 2008 oder das Profil 2019-03-01 und niedriger.

Nächste Schritte

Weitere Informationen zu API-Profilen:

Freigeben über