Utiliser des profils de version d’API avec Java dans Azure Stack Hub

Article
10/30/2024

Important

Le Kit de développement logiciel (SDK) Java a été mis à jour de la piste 1 à la piste 2. Nous vous recommandons de migrer vers le Kit de développement logiciel (SDK) track 2 dès que possible. Pour obtenir des instructions, consultez ce guide de migration.

Le Kit de développement logiciel (SDK) Java pour Azure Stack Hub Resource Manager fournit des outils conçus pour vous aider à créer et gérer votre infrastructure. Les fournisseurs de ressources du SDK incluent le calcul, le réseau, le stockage, les services d’application et Azure Key Vault. Vous pouvez trouver le dépôt d’exemples Java hybride sur GitHub. Cet article vous aidera à configurer votre environnement, à obtenir les informations d’identification appropriées, à récupérer le dépôt et à créer un groupe de ressources dans Azure Stack Hub.

Le Kit de développement logiciel (SDK) Java favorise une véritable expérience de développement cloud hybride. Le basculement des dépendances de version dans le POM.xml dans le SDK Java permet un développement cloud hybride en vous aidant à basculer entre des ressources Azure globales et des ressources dans Azure Stack Hub.

Pour utiliser la version la plus récente des services, utilisez le profil latest comme dépendance.

Vous pouvez cibler votre application sur une ressource dans Azure Stack Hub en utilisant votre dépendance com.azure.resourcemanager existante et remplacer la version x.y.z par x.y.z-hybrid. Les packages hybrides, qui assurent la prise en charge d’Azure Stack Hub, utilisent un suffixe -hybrid à la fin de la version, par exemple 1.0.0-hybrid. Cela pointera vers une collection statique de points de terminaison associés à la version.

Pour obtenir le profil latest, prenez votre dépendance com.azure.resourcemanager existante et remplacez la version par latest. Les packages Java avec le profil latest fournissent une expérience cohérente avec Azure. Les packages partagent le même ID de groupe qu’Azure com.azure.resourcemanager. L’ID d’artefact et les espaces de noms sont également identiques à ceux d’Azure international. Cela permet de porter votre application Azure vers Azure Stack Hub. Pour en savoir plus sur les points de terminaison utilisés dans Azure Stack Hub dans le cadre du profil hybride, consultez le résumé des profils d’API.

Le profil est spécifié dans le fichier pom.xml du projet Maven en tant que dépendance. Le profil charge automatiquement les modules si vous choisissez la classe appropriée dans la liste déroulante (comme vous le feriez avec .NET).

Configurer votre environnement de développement

Pour préparer votre environnement à l’exécution du KIT de développement logiciel (SDK), vous pouvez utiliser un IDE tel qu’Eclipse ou Visual Studio Code, mais vous devez avoir installé Git, le Kit de développement logiciel (SDK) Java et Apache Maven. Vous trouverez plus d’informations sur les prérequis à la configuration de votre environnement de développement dans Utiliser le SDK Azure pour Java

Installez Git. Vous trouverez les instructions officielles pour installer Git dans Démarrage rapide - Installation de Git.
Installez le kit SDK Java et définissez votre variable d’environnement JAVA_HOME sur l’emplacement des fichiers binaires du Java Development Kit. Vous trouverez les instructions du support d’installation à télécharger pour OpenJDK. Installez la version 8 ou une version ultérieure du JDK (Java Developer Kit).
Installez Apache Maven. Vous trouverez des instructions sur le site du projet Apache Maven. Installez Apache Maven, version 3.0 ou ultérieure.

Java et les profils de version d’API

Pour recourir à la dernière version de chacun des services, utilisez le profil latest en tant que dépendance.

Pour l’utilisation du profil latest, la dépendance est com.microsoft.azure.
Pour utiliser les derniers services pris en charge disponibles dans Azure Stack Hub, utilisez le profil com.microsoft.azure.profile_2019_03_01_hybrid.
- Le profil est spécifié dans le fichier Pom.xml en tant que dépendance, ce qui charge automatiquement les modules si vous choisissez la classe appropriée dans la liste déroulante (comme vous le feriez avec .NET).

Les dépendances apparaissent comme suit :

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

Pour utiliser des versions d’API spécifiques pour un type de ressource dans un fournisseur de ressources donné, utilisez les versions d’API spécifiques définies par le biais d’IntelliSense.

Vous pouvez combiner toutes les options dans la même application.

Installer le Kit de développement logiciel (SDK) Java Azure

Pour installer le SDK Java, effectuez les étapes suivantes :

Suivez les instructions officielles pour installer Git. Consultez Bien démarrer - Installation de Git.
Suivez les instructions pour installer le Kit de développement logiciel (SDK) Java et Maven. La version correcte du Kit de développement Java est la version 8. La version correcte d’Apache Maven est la version 3.0 ou ultérieure. Pour suivre le guide de démarrage rapide, la variable d’environnement JAVA_HOME doit être définie sur l’emplacement d’installation du Kit de développement Java. Pour plus d’informations, consultez l’article Créer votre première fonction dans Azure avec Java et Maven.
Pour installer les packages de dépendances corrects, ouvrez le fichier Pom.xml dans votre application Java. Ajoutez une dépendance, comme indiqué dans le code suivant :
```
<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>
```
L’ensemble de packages à installer dépend de la version de profil que vous souhaitez utiliser. Les noms de package pour les versions de profil sont les suivants :
- com.microsoft.azure.profile_2019_03_01_hybrid
- com.microsoft.azure
  - le plus récent

Profils

Pour les profils qui contiennent des dates, pour utiliser un autre profil ou une autre version du SDK, remplacez la date dans com.microsoft.azure.profile<date>_hybrid. Par exemple, pour la version 2008, le profil est 2019_03_01 et la chaîne devient com.microsoft.azure.profile_2019_03_01_hybrid. Notez que, parfois, l’équipe du kit de développement modifie le nom des packages. Il est donc possible que le remplacement de la date d’une chaîne par une autre date ne fonctionne pas. Consultez le tableau suivant pour l’association des profils et des versions de Azure Stack.

Version d’Azure Stack	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

Pour plus d’informations sur Azure Stack Hub et les profils d’API, voir Résumé des profils d’API.

Abonnement

Si vous n’avez pas encore d’abonnement, créez un abonnement et enregistrez l’ID d’abonnement à utiliser ultérieurement. Pour plus d’informations sur la manière de créer un abonnement, consultez ce document.

Principal du service

Le principal de service et ses informations d’environnement associées doivent être créés et enregistrés quelque part. Le principal de service avec rôle owner est recommandé, mais en fonction de l’exemple, un rôle contributor peut suffire. Reportez-vous au fichier README dans l’exemple de référentiel pour connaître les valeurs requises. Vous pouvez lire ces valeurs dans tout format pris en charge par le langage du SDK, par exemple à partir d’un fichier JSON (que nos exemples utilisent). Selon l’exemple en cours d’exécution, toutes ces valeurs peuvent ne pas être utilisées. Consultez l’exemple de référentiel pour obtenir des exemples de code à jour ou des informations supplémentaires.

ID client

Pour rechercher le répertoire ou l’ID de locataire de votre environnement Azure Stack Hub, suivez les instructions fournies dans cet article.

Inscrire des fournisseurs de ressources

Inscrivez les fournisseurs de ressources requis en suivant ce document. Ces fournisseurs de ressources seront nécessaires en fonction des exemples que vous souhaitez exécuter. Par exemple, si vous souhaitez exécuter un exemple de machine virtuelle, l’inscription du fournisseur de ressources Microsoft.Compute est requise.

Point de terminaison Azure Stack Resource Manager

Azure Resource Manager (ARM) est un framework de gestion qui permet aux administrateurs de déployer, gérer et superviser les ressources Azure. Azure Resource Manager peut gérer ces tâches en groupe, plutôt qu’individuellement, dans une seule opération. Vous pouvez obtenir les informations de métadonnées du point de terminaison du Gestionnaire des ressources. Le point de terminaison retourne un fichier JSON avec les informations requises pour exécuter votre code.

Le ResourceManagerEndpointUrl dans le kit de développement Azure Stack (ASDK) est : https://management.local.azurestack.external/.
Le ResourceManagerEndpointUrl dans les systèmes intégrés est : https://management.region.<fqdn>/, où <fqdn> est votre nom de domaine complet.
Pour récupérer les métadonnées requises : <ResourceManagerUrl>/metadata/endpoints?api-version=1.0. Pour obtenir les versions d’API disponibles, consultez les spécifications de l’API REST Azure. Par exemple, dans la version de profil 2020-09-01, vous pouvez modifier le api-version en 2019-10-01 pour le fournisseur de ressources microsoft.resources.

Exemple de code 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"]
      }
}

Approuver le certificat d'autorité de certification racine Azure Stack Hub

Si vous utilisez le Kit de développement Azure Stack (ASDK), vous devez approuver le certificat racine de l’autorité de certification sur votre machine distante. Vous n’avez pas besoin d’approuver le certificat d’autorité de certification racine avec des systèmes intégrés Azure Stack Hub.

Windows

Exportez le certificat auto-signé Azure Stack Hub vers votre bureau.
Dans une invite de commandes, remplacez le répertoire par %JAVA_HOME%\bin.

Exécutez la commande suivante :

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

Profils d’API existants

com.microsoft.azure.profile_2019_03_01_hybrid : Dernier profil créé pour Azure Stack Hub. Utilisez ce profil pour que les services soient les plus compatibles possibles avec Azure Stack Hub, à condition de disposer de la version 1904 ou ultérieure.
com.microsoft.azure.profile_2018_03_01_hybrid : Profil créé pour Azure Stack Hub. Utilisez ce profil pour que les services soient compatibles avec les versions 1808 ou ultérieures d’Azure Stack Hub.
com.microsoft.azure : profil constitué des dernières versions de l’ensemble des services. Utilisez les dernières versions de tous les services.

Pour plus d’informations sur Azure Stack Hub et les profils d’API, voir Résumé des profils d’API.

Utilisation du profil d’API du Kit de développement logiciel (SDK) Java Azure

Le code ci-après authentifie le principal de service sur Azure Stack Hub. Il crée un jeton spécifique d’Azure Stack Hub en utilisant l’ID de locataire et la base d’authentification :

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

Ce code vous permet d’utiliser les dépendances du profil d’API pour déployer correctement votre application sur Azure Stack Hub.

Définir des fonctions de définition d’environnement Azure Stack Hub

Pour inscrire le cloud Azure Stack Hub auprès des points de terminaison appropriés, utilisez le code suivant :

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

L’appel de getActiveDirectorySettings dans le code précédent récupère les points de terminaison à partir des points de terminaison de métadonnées. Il indique les variables d’environnement à partir de l’appel qui est effectué :

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

Exemple de projet de test unitaire

Clonez le référentiel à l’aide de la commande suivante :

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

Créez un principal de service Azure et assignez un rôle pour accéder à l’abonnement. Pour obtenir des instructions sur la création d’un principal de service, consultez Fournir l’accès des applications à Azure Stack.
Récupérez les variables d’environnement nécessaires suivantes :
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_SUBSCRIPTION_ID
- ARM_ENDPOINT
- RESOURCE_LOCATION
Définissez les variables d’environnement ci-après en utilisant les informations que vous avez récupérées à partir du principal de service que vous avez créé à l’aide de l’invite de commandes :
- 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}
Sous Windows, utilisez set et non export.
Utilisez la fonction getActiveDirectorySettings pour récupérer les points de terminaison de métadonnées Azure Resource Manager.
```
// Get Azure Stack Hub cloud endpoints
final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);
```
Dans le fichier Pom.xml, ajoutez la dépendance suivante afin d’utiliser le profil 2019-03-01-hybrid pour Azure Stack Hub. Cette dépendance installe les modules associés à ce profil pour les fournisseurs de ressources Compute, Mise en réseau, Stockage, KeyVault et App Services :
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
Dans l’invite de commandes qui était ouverte pour la définition des variables d’environnement, entrez la commande suivante :
```
mvn clean compile exec:java
```

exemples

Consultez cet exemple de référentiel pour obtenir l’exemple de code de mise à jour à date (piste 2). Consultez cet exemple de référentiel pour suivre 1 exemple de code. La racine README.md décrit les exigences générales, et chaque sous-répertoire contient un exemple spécifique avec son propre README.md sur la façon d’exécuter cet exemple.

Découvrez ici l’exemple applicable à la version Azure Stack 2008 ou au profil 2019-03-01 et versions antérieures.

Étapes suivantes

Découvrez-en plus sur les profils d’API :

Partage via