Usar perfis de versão da API com Java no Azure Stack Hub

Artigo
04/08/2024

Importante

O SDK do Java foi atualizado da faixa 1 para a faixa 2. Recomendamos migrar para o SDK da faixa 2 assim que possível. Para obter instruções, consulte este guia de migração.

O SDK do Java para o Azure Stack Hub Resource Manager fornece ferramentas para ajudá-lo a criar e gerenciar sua infraestrutura. Os provedores de recursos no SDK incluem computação, rede, armazenamento, serviços de aplicativos e Key Vault do Azure. Você pode encontrar o repositório de Exemplos de Java Híbrido no GitHub. Este artigo ajudará você a configurar seu ambiente, obter as credenciais certas, pegar o repositório e criar um grupo de recursos no Azure Stack Hub.

O uso do SDK do Java permite uma verdadeira experiência de desenvolvedor de nuvem híbrida. Alternar as dependências de versão no POM.xml no SDK do Java permite o desenvolvimento de nuvem híbrida, ajudando você a alternar entre recursos globais do Azure para recursos no Azure Stack Hub.

Para usar a versão mais recente dos serviços, use o perfil mais recente como a dependência.

Você pode direcionar seu aplicativo para o recurso no Hub de aderência do Azure usando sua dependência com.azure.resourcemanager existente e alterar a versão de x.y.z para x.y.z-hybrid. Os pacotes híbridos, que dão suporte ao Azure Stack Hub, usam um -hybrid sufixo no final da versão, por exemplo, 1.0.0-hybrid. Isso apontará para uma coleção estática de pontos de extremidade associados à versão.

Para obter o perfil mais recente, use sua dependência com.azure.resourcemanager existente e altere a versão para a mais recente. Os pacotes Java de perfil mais recentes fornecem uma experiência consistente com o Azure. Os pacotes compartilham a mesma ID de grupo que o Azure com.azure.resourcemanager. A ID do artefato e os namespaces também são os mesmos que o Azure global. Isso ajuda a portar seu aplicativo do Azure para o Azure Stack Hub. Para saber mais sobre os pontos de extremidade usados no Azure Stack Hub como par do perfil híbrido, confira o Resumo dos perfis de API.

O perfil é especificado no pom.xml arquivo no projeto Maven como uma dependência. O perfil carregará módulos automaticamente se você escolher a classe certa na lista suspensa (como faria com o .NET).

Configurar seu ambiente de desenvolvimento

Para preparar seu ambiente para executar o SDK, você pode usar um IDE como Eclipse ou Visual Studio Code, mas precisará ter o Git, o SDK do Java e o Apache Maven instalados. Você pode encontrar detalhes sobre os pré-requisitos para a configuração do ambiente de desenvolvimento em Usar o SDK do Azure para Java

Instale o Git. Você pode encontrar as instruções oficiais para instalar o Git em Introdução – Instalando o Git.
Instale o SDK do Java e defina sua JAVA_HOME variável de ambiente como o local dos binários para o Java Development Kit. Você pode encontrar as instruções de mídia de instalação para download para o OpenJDK. Instale a versão 8 ou superior do Java Developer Kit.
Instale o Apache Maven. Você pode encontrar instruções no Projeto Apache Maven. Instalar o Apache Maven é 3.0 ou superior.

Perfis de versão do Java e da API

Para usar as versões mais recentes de todos os serviços, use o perfil mais recente como a dependência.

Para usar o perfil mais recente, a dependência é com.microsoft.azure.
Para usar os serviços com suporte mais recentes disponíveis no Azure Stack Hub, use o perfil com.microsoft.azure.profile_2019_03_01_hybrid .
- O perfil é especificado no arquivo Pom.xml como uma dependência, que carrega módulos automaticamente se você escolher a classe certa na lista suspensa (como faria com o .NET).

As dependências aparecem da seguinte maneira:

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

Para usar versões de API específicas para um tipo de recurso em um provedor de recursos específico, use as versões de API específicas definidas por meio do IntelliSense.

Você pode combinar todas as opções no mesmo aplicativo.

Instalar o SDK do Java do Azure

Siga estas etapas para instalar o SDK do Java:

Siga as instruções oficiais para instalar o Git. Consulte Introdução – Instalando o Git.
Siga as instruções para instalar o SDK do Java e o Maven. A versão correta é a versão 8 do Java Developer Kit. A versão correta do Apache Maven é 3.0 ou superior. Para concluir o início rápido, a JAVA_HOME variável de ambiente deve ser definida como o local de instalação do Java Development Kit. Para obter mais informações, consulte Criar sua primeira função com Java e Maven.
Para instalar os pacotes de dependência corretos, abra o arquivo Pom.xml em seu aplicativo Java. Adicione uma dependência, conforme mostrado no seguinte código:
```
<dependency>
<groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
<artifactId>azure</artifactId>
<version>1.0.0-beta-1</version>
</dependency>
```
O conjunto de pacotes que precisam ser instalados depende da versão do perfil que você deseja usar. Os nomes dos pacotes para as versões de perfil são:
- com.microsoft.azure.profile_2019_03_01_hybrid
- com.microsoft.azure
  - mais recente

Perfis

Para perfis que contêm datas, para usar um perfil ou versão diferente do SDK, substitua a data em com.microsoft.azure.profile<date>_hybrid. Por exemplo, para a versão 2008, o perfil é 2019_03_01e a cadeia de caracteres se torna com.microsoft.azure.profile_2019_03_01_hybrid. Observe que, às vezes, a equipe do SDK altera o nome dos pacotes, portanto, simplesmente substituir a data de uma cadeia de caracteres por uma data diferente pode não funcionar. Consulte a tabela a seguir para associação de perfis e versões do Azure Stack.

Versão do 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 obter mais informações sobre o Azure Stack Hub e perfis de API, consulte o Resumo dos perfis de API.

Subscription

Se você ainda não tiver uma assinatura, crie uma assinatura e salve a ID da assinatura a ser usada posteriormente. Para obter informações sobre como criar uma assinatura, consulte este documento.

Entidade de serviço

Uma entidade de serviço e suas informações de ambiente associadas devem ser criadas e salvas em algum lugar. A entidade de serviço com owner função é recomendada, mas dependendo do exemplo, uma contributor função pode ser suficiente. Consulte o LEIAME no repositório de exemplo para obter os valores necessários. Você pode ler esses valores em qualquer formato compatível com a linguagem SDK, como de um arquivo JSON (que nossos exemplos usam). Dependendo do exemplo que está sendo executado, nem todos esses valores podem ser usados. Consulte o repositório de exemplo para obter o código de exemplo atualizado ou mais informações.

ID do locatário

Para localizar a ID do diretório ou do locatário do Azure Stack Hub, siga as instruções neste artigo.

Registrar provedores de recursos

Registre os provedores de recursos necessários seguindo este documento. Esses provedores de recursos serão necessários dependendo dos exemplos que você deseja executar. Por exemplo, se você quiser executar um exemplo de VM, o registro do Microsoft.Compute provedor de recursos será necessário.

Ponto de extremidade do Azure Stack Resource Manager

O ARM (Azure Resource Manager) é uma estrutura de gerenciamento que permite aos administradores implantar, gerenciar e monitorar recursos do Azure. O Azure Resource Manager pode lidar com essas tarefas como um grupo, em vez de individualmente, em uma única operação. Você pode obter as informações de metadados do ponto de extremidade Resource Manager. O ponto de extremidade retorna um arquivo JSON com as informações necessárias para executar o código.

O ResourceManagerEndpointUrl no ASDK (Azure Stack Development Kit) é: https://management.local.azurestack.external/.
O ResourceManagerEndpointUrl em sistemas integrados é: https://management.region.<fqdn>/, em que <fqdn> é o nome de domínio totalmente qualificado.
Para recuperar os metadados necessários: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0. Para versões de API disponíveis, consulte Especificações da API rest do Azure. Por exemplo, na 2020-09-01 versão do perfil, você pode alterar o para para 2019-10-01 o api-version provedor de recursos microsoft.resources.

JSON de exemplo:

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

Confiar no certificado raiz de AC do Azure Stack Hub

Se você estiver usando o ASDK (Azure Stack Development Kit), deverá confiar no certificado raiz da AC em seu computador remoto. Você não precisa confiar no certificado raiz da AC com sistemas integrados do Azure Stack Hub.

Windows

Exporte o certificado autoassinado do Azure Stack Hub para sua área de trabalho.
Em um prompt de comando, altere o diretório para %JAVA_HOME%\bin.

Execute o comando a seguir:

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

Perfis de API existentes

com.microsoft.azure.profile_2019_03_01_hybrid: perfil mais recente criado para o Azure Stack Hub. Use esse perfil para que os serviços sejam mais compatíveis com o Azure Stack Hub, desde que você esteja em 1904 ou posterior.
com.microsoft.azure.profile_2018_03_01_hybrid: perfil criado para o Azure Stack Hub. Use esse perfil para que os serviços sejam compatíveis com as versões 1808 ou posteriores do Azure Stack Hub.
com.microsoft.azure: perfil que consiste nas versões mais recentes de todos os serviços. Use as versões mais recentes de todos os serviços.

Para obter mais informações sobre os perfis de API e do Azure Stack Hub, consulte Resumo dos perfis de API.

Uso do perfil da API do SDK do Java no Azure

O código a seguir autentica a entidade de serviço no Azure Stack Hub. Ele cria um token usando a ID do locatário e a base de autenticação, que é específica do 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());

Esse código permite que você use as dependências de perfil de API para implantar seu aplicativo com êxito no Azure Stack Hub.

Definir funções de configuração de ambiente do Azure Stack Hub

Para registrar a nuvem do Azure Stack Hub com os pontos de extremidade corretos, use o seguinte 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('.')));
                }
            });

A getActiveDirectorySettings chamada no código anterior recupera os pontos de extremidade dos pontos de extremidade de metadados. Ele declara as variáveis de ambiente da chamada feita:

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

Projeto de teste de unidade de exemplo

Clone o repositório usando o seguinte comando:

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

Crie uma entidade de serviço do Azure e atribua uma função para acessar a assinatura. Para obter instruções sobre como criar uma entidade de serviço, consulte Usar Azure PowerShell para criar uma entidade de serviço com um certificado.
Recupere as seguintes variáveis de ambiente necessárias:
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_SUBSCRIPTION_ID
- ARM_ENDPOINT
- RESOURCE_LOCATION
Defina as seguintes variáveis de ambiente usando as informações recuperadas da entidade de serviço que você criou usando o prompt de comando:
- 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}
No Windows, use set em vez de exportar.

Use a getActiveDirectorySettings função para recuperar os pontos de extremidade de metadados Resource Manager do Azure.

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

No arquivo Pom.xml , adicione a seguinte dependência para usar o perfil híbrido 2019-03-01 para o Azure Stack Hub. Essa dependência instala os módulos associados a esse perfil para os provedores de recursos Compute, Networking, Storage, Key Vault e App Services:
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
No prompt de comando que estava aberto para definir as variáveis de ambiente, insira o seguinte comando:
```
mvn clean compile exec:java
```

Exemplos

Consulte este repositório de exemplo para obter o código de exemplo atualizado (faixa 2). Consulte este repositório de exemplo para obter o código de exemplo da faixa 1. A raiz README.md descreve os requisitos gerais e cada subdiretório contém um exemplo específico com o próprio README.md sobre como executar esse exemplo.

Confira aqui o exemplo aplicável à versão 2008 ou perfil 2019-03-01 do Azure Stack e abaixo.

Próximas etapas

Saiba mais sobre perfis de API: