Uso de los perfiles de la versión de API con Java en Azure Stack Hub

Artículo
10/30/2024

Importante

El SDK de Java se ha actualizado de la pista 1 a la pista 2. Se recomienda migrar al SDK de seguimiento 2 lo antes posible. Para obtener instrucciones, consulte esta guía de migración.

El SDK de Java para Resource Manager de Azure Stack Hub proporciona herramientas que facilitan la creación y administración de infraestructuras. Los proveedores de recursos del SDK incluyen los servicios Compute, Redes, Storage, App Services y Azure Key Vault. Puede encontrar el repositorio de ejemplos de Java híbrido en GitHub. Este artículo le ayudará a configurar el entorno, obtener las credenciales adecuadas, obtener el repositorio y crear un grupo de recursos en Azure Stack Hub.

El uso del SDK de Java permite una verdadera experiencia de desarrollador de nube híbrida. Cambiar las dependencias de las versiones en el archivo POM.xml del SDK de Java habilita el desarrollo en la nube híbrida ayudándole a alternar entre los recursos de Azure globales y los recursos de Azure Stack Hub.

Para usar la última versión de los servicios, use el perfil más reciente como dependencia.

Para dirigir la aplicación al recurso de Azure Stack Hub, tome la dependencia com.azure.resourcemanager y cambie la versión de x.y.z a x.y.z-hybrid. Los paquetes híbridos, que proporcionan compatibilidad con Azure Stack Hub, usan un sufijo -hybrid al final de la versión, por ejemplo, 1.0.0-hybrid. Este apuntará a una colección estática de puntos de conexión asociados a la versión.

Para obtener el perfil más reciente, tome la dependencia com.azure.resourcemanager existente y cambie la versión a la más reciente. Los paquetes de perfiles de Java más recientes proporcionan una experiencia coherente con Azure. Los paquetes comparten el mismo identificador de grupo que Azure com.azure.resourcemanager El identificador de artefacto y los espacios de nombres también son los mismos que los de Azure global. Esto ayuda a trasladar la aplicación de Azure a Azure Stack Hub. Para más información sobre los puntos de conexión usados en Azure Stack Hub como par del perfil híbrido, consulte Resumen de perfiles de API.

El perfil se especifica en el archivo pom.xml del proyecto de Maven como una dependencia. El perfil carga módulos automáticamente si elige la clase correcta en la lista desplegable (como lo haría con .NET).

Configurado su entorno de desarrollo

Para preparar el entorno para ejecutar el SDK, puede usar un IDE como Eclipse o Visual Studio Code, pero tendrá que tener Instalado Git, el SDK de Java y Apache Maven. Puede encontrar detalles sobre los requisitos previos para configurar el entorno de desarrollo en Uso de Azure SDK para Java.

Instale Git. Puede encontrar las instrucciones oficiales para instalar Git en Introducción: Instalación de Git.
Instale el SDK de Java y establezca la variable de entorno JAVA_HOME en la ubicación de los archivos binarios del kit de desarrollo de Java. Puede encontrar las instrucciones sobre soportes de instalación descargables de OpenJDK. Instale la versión 8 o posterior del kit para desarrolladores de Java.
Instale Apache Maven. Puede encontrar instrucciones en el proyecto Apache Maven. La versión de Apache Maven instalada es 3.0 o posterior.

Perfiles de la versión de API y Java

Para usar las últimas versiones de todos los servicios, use el perfil más reciente como la dependencia.

Para usar el perfil más reciente, la dependencia es com.microsoft.azure.
Para utilizar los servicios compatibles más recientes disponibles en Azure Stack Hub, utilice el perfil com.microsoft.azure.profile_2019_03_01_hybrid.
- El perfil se especifica en el archivo Pom.xml como una dependencia, que carga los módulos automáticamente si elige la clase correcta de la lista desplegable (como lo haría con .NET).

Las dependencias aparecerán como sigue:

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

Para utilizar versiones específicas de API para un tipo de recurso en un proveedor de recursos específico, utilice las versiones específicas de API definidas mediante Intellisense.

Puede combinar todas las opciones en la misma aplicación.

Instalación del SDK de Java de Azure

Para instalar el SDK de Java, siga estos pasos:

Siga las instrucciones oficiales para instalar Git. Consulte Introducción: Instalación de Git.
Siga las instrucciones para instalar el SDK de Java y Maven. La versión correcta es la versión 8 de Java Developer Kit. La versión correcta de Apache Maven es la versión 3.0 o posterior. La variable de entorno JAVA_HOME se debe establecer en la ubicación de instalación de Java Development Kit para completar este inicio rápido. Para obtener más información, consulte Creación de la primera función con Java y Maven.
Para instalar los paquetes de dependencias correctos, abra el archivo Pom.xml en la aplicación de Java. Agregue una dependencia como se muestra en el código siguiente:
```
<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>
```
El conjunto de paquetes que se deben instalar dependerán de la versión del perfil que desee utilizar. Los nombres de paquete para las versiones de perfiles son:
- com.microsoft.azure.profile_2019_03_01_hybrid
- com.microsoft.azure
  - más reciente

Profiles

En el caso de los perfiles que contienen fechas, para usar otro perfil o versión del SDK, sustituya la fecha en com.microsoft.azure.profile<date>_hybrid. Por ejemplo, para la versión 2008, el perfil es 2019_03_01 y la cadena se convierte en com.microsoft.azure.profile_2019_03_01_hybrid. Tenga en cuenta que a veces el equipo del SDK cambia el nombre de los paquetes, por lo que podría no funcionar simplemente reemplazar la fecha de una cadena por otra fecha. Consulte la tabla siguiente para ver la asociación de perfiles y versiones de Azure Stack.

Versión de Azure Stack	Perfil
2311	2020_09_01
2301	2020_09_01
2206	2020_09_01
2108	2020_09_01
2102	2020_09_01
2008	2019_03_01

Para más información sobre los perfiles de API y Azure Stack Hub, consulte Resumen de perfiles de API.

Subscription

Si aún no tiene una suscripción, cree una y guarde el ID. de suscripción para usarlo más adelante. Para más información sobre cómo crear una suscripción, vea este documento.

Entidad de servicio

Una entidad de servicio y su información de entorno asociada deben crearse y guardarse en algún lugar. Se recomienda la entidad de servicio con rol owner, pero en función del ejemplo, un rol contributor puede ser suficiente. Consulte el archivo LÉAME en el repositorio de ejemplo para conocer los valores necesarios. Puede leer estos valores en cualquier formato admitido por el lenguaje SDK, como desde un archivo JSON (que usan nuestros ejemplos). Dependiendo de la ejecución del ejemplo, no se pueden usar todos estos valores. Consulte el repositorio de ejemplo para obtener código de ejemplo actualizado o más información.

Id. de inquilino

Para buscar el directorio o el ID. de inquilino de Azure Stack Hub, siga las instrucciones de este artículo.

Registro de proveedores de recursos

Registre los proveedores de recursos necesarios siguiendo este documento. Estos proveedores de recursos serán necesarios en función de los ejemplos que quiera ejecutar. Por ejemplo, si quiere ejecutar un ejemplo de máquina virtual, se requiere el registro del proveedor de recursos Microsoft.Compute.

Punto de conexión del administrador de recursos de Azure Stack

Azure Resource Manager (ARM) es un marco de administración que permite a los administradores implementar, administrar y supervisar recursos de Azure. Azure Resource Manager puede controlar estas tareas como grupo, en vez de individualmente, en una sola operación. Puede obtener la información de metadatos en el punto de conexión de Resource Manager. El punto de conexión devuelve un archivo JSON con la información necesaria para ejecutar el código.

El valor de ResourceManagerEndpointUrl del Kit de desarrollo de Azure Stack (ASDK) es: https://management.local.azurestack.external/.
ResourceManagerEndpointUrl en un sistema integrado es: https://management.region.<fqdn>/, donde <fqdn> es el nombre de dominio completo.
Para recuperar los metadatos necesarios: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0. Para las versiones de API disponibles, consulte Especificaciones de la API de REST de Azure. Por ejemplo, en la versión 2020-09-01 del perfil, puede cambiar api-version por 2019-10-01 para el proveedor de recursos microsoft.resources.

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

Confianza en el certificado raíz de la entidad de certificación de Azure Stack Hub

Si usa el Kit de desarrollo de Azure Stack (ASDK), debe confiar en el certificado raíz de la entidad de certificación de la máquina remota. No es necesario que confíe en el certificado raíz de la entidad de certificación con los sistemas integrados de Azure Stack Hub.

Windows

Exporte el certificado autofirmado de Azure Stack Hub al escritorio.
En un símbolo del sistema, cambie el directorio a %JAVA_HOME%\bin.

Ejecute el siguiente comando:

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

Perfiles de API existentes

com.microsoft.azure.profile_2019_03_01_hybrid: es el perfil más reciente creado para Azure Stack Hub. Use este perfil para que los servicios sean lo más compatibles posible con Azure Stack Hub, siempre y cuando tenga la versión 1904, o cualquier versión posterior.
com.microsoft.azure.profile_2018_03_01_hybrid: es el perfil creado para Azure Stack Hub. Use este perfil para que los servicios sean compatibles con la versión 1808 de Azure Stack Hub, o cualquier versión posterior.
com.microsoft.azure: este perfil contiene las versiones más recientes de todos los servicios. Use las versiones más recientes de todos los servicios.

Para más información sobre los perfiles de API y Azure Stack Hub, consulte Resumen de perfiles de API.

Uso de perfil de API del SDK de Java de Azure

El código siguiente autentica la entidad de servicio en Azure Stack Hub. Crea un token mediante el identificador de inquilino y la base de autenticación, que es específica de 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());

Este código le permite usar las dependencias del perfil de API para implementar la aplicación correctamente en Azure Stack Hub.

Definición de las funciones de configuración del entorno de Azure Stack Hub

Para registrar la nube de Azure Stack Hub con los puntos de conexión correctos, utilice el siguiente código:

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

La llamada getActiveDirectorySettings en el código anterior recupera los puntos de conexión de los puntos de conexión de los metadatos. Indica las variables de entorno de la llamada que se realiza:

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

Proyecto de prueba unitaria de ejemplo

Clone el repositorio con el siguiente comando:

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

Cree una entidad de servicio de Azure y asigne un rol para acceder a la suscripción. Para obtener instrucciones sobre cómo crear una entidad de servicio, consulte Uso de Azure PowerShell para crear una entidad de servicio con un certificado.
Recupere las siguientes variables de entorno necesarias:
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_SUBSCRIPTION_ID
- ARM_ENDPOINT
- RESOURCE_LOCATION
Establezca las siguientes variables de entorno con la información que recuperó de la entidad de servicio que creó con el símbolo del sistema:
- 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}
En Windows, use set en lugar de export.

Use la función getActiveDirectorySettings para recuperar los puntos de conexión de metadatos de Azure Resource Manager.

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

En el archivo Pom.xml, agregue la dependencia siguiente para utilizar el perfil 2019-03-01-hybrid para Azure Stack Hub. Esta dependencia instala los módulos asociados a este perfil para los proveedores de recursos de los servicios Compute, Redes, Storage, Key Vault y App Services:
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
En el símbolo del sistema que estaba abierto para establecer las variables de entorno, escriba el siguiente comando:
```
mvn clean compile exec:java
```

Ejemplos

Consulte este repositorio de ejemplo para obtener código de ejemplo de actualización a fecha (seguimiento 2). Consulte este repositorio de ejemplo para realizar el seguimiento de un código de ejemplo. La raíz README.md describe los requisitos generales y cada subdirectorio contiene un ejemplo específico con su propio README.md modo de ejecutar ese ejemplo.

Consulte aquí el ejemplo aplicable a la versión 2008 o el perfil 2019-03-01 de Azure Stack y posteriores.

Pasos siguientes

Más información acerca de los perfiles de API:

Compartir a través de