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

Artigo
04/08/2024

Importante

O SDK Java foi atualizado da faixa 1 para a faixa 2. Recomendamos a migração para o SDK track 2 o mais rapidamente possível. Para obter instruções, veja este guia de migração.

O SDK Java para o Azure Stack Hub Resource Manager fornece ferramentas para o ajudar a criar e gerir a sua infraestrutura. Os fornecedores de recursos no SDK incluem computação, rede, armazenamento, serviços de aplicações e Key Vault do Azure. Pode encontrar o repositório De Exemplos De Java Híbrido no GitHub. Este artigo irá ajudá-lo a configurar o seu ambiente, a obter as credenciais certas, a obter o repositório e a criar um grupo de recursos no Azure Stack Hub.

A utilização do SDK Java permite uma verdadeira experiência de programador de cloud híbrida. Mudar as dependências de versão no POM.xml SDK Java permite o desenvolvimento de cloud híbrida, ajudando-o a alternar entre recursos globais do Azure para recursos no Azure Stack Hub.

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

Pode direcionar a sua aplicação para recurso no Hub de tack do Azure ao tomar a 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 fornecem suporte para o Azure Stack Hub, utilizam um -hybrid sufixo no final da versão, por exemplo, 1.0.0-hybrid. Isto irá apontar para uma coleção estática de pontos finais associados à versão.

Para obter o perfil mais recente, utilize a dependência com.azure.resourcemanager existente e altere a versão para a mais recente. Os pacotes Java de perfil mais recentes proporcionam uma experiência consistente com o Azure. Os pacotes partilham o mesmo ID de grupo que o Azure com.azure.resourcemanager. O ID do artefacto e os espaços de nomes também são os mesmos que o Azure global. Isto ajuda a migrar a sua aplicação do Azure para o Azure Stack Hub. Para saber mais sobre os pontos finais utilizados no Azure Stack Hub como par do perfil híbrido, veja Resumo dos perfis de API.

O perfil é especificado no pom.xml ficheiro no projeto Maven como uma dependência. O perfil carrega os módulos automaticamente se escolher a classe certa na lista pendente (como faria com o .NET).

Configurar o ambiente de desenvolvimento

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

Instale o Git. Pode encontrar as instruções oficiais para instalar o Git no Introdução – Instalar o Git.
Instale o SDK Java e defina a variável JAVA_HOME de ambiente para a localização dos binários do Java Development Kit. Pode encontrar as instruções de suporte de dados de instalação transferíveis para o OpenJDK. Instale a versão 8 ou superior do Java Developer Kit.
Instale o Apache Maven. Pode encontrar instruções no Projeto Apache Maven. Instalar o Apache Maven é 3.0 ou superior.

Perfis de versão de Java e API

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

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

As dependências são apresentadas da seguinte forma:

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

Para utilizar versões de API específicas para um tipo de recurso num fornecedor de recursos específico, utilize as versões específicas da API definidas através do Intellisense.

Pode combinar todas as opções na mesma aplicação.

Instalar o SDK Java do Azure

Siga estes passos para instalar o SDK Java:

Siga as instruções oficiais para instalar o Git. Veja Introdução - Instalar o Git.
Siga as instruções para instalar o SDK 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 variável de JAVA_HOME ambiente tem de ser definida para a localização de instalação do Java Development Kit. Para obter mais informações, consulte Criar a sua primeira função com Java e Maven.
Para instalar os pacotes de dependência corretos, abra o ficheiro Pom.xml na sua aplicação 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 de ser instalados depende da versão de perfil que pretende utilizar. 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 contenham datas, para utilizar um perfil ou versão do SDK diferente, substitua a data em com.microsoft.azure.profile<date>_hybrid. Por exemplo, para a versão de 2008, o perfil é 2019_03_01, e a cadeia torna-se com.microsoft.azure.profile_2019_03_01_hybrid. Tenha em atenção que, por vezes, a equipa do SDK altera o nome dos pacotes, pelo que substituir simplesmente a data de uma cadeia por uma data diferente pode não funcionar. Veja a tabela seguinte 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, veja o Resumo dos perfis de API.

Subscrição

Se ainda não tiver uma subscrição, crie uma subscrição e guarde o ID da subscrição para ser utilizado mais tarde. Para obter informações sobre como criar uma subscrição, veja este documento.

Service principal (Principal de serviço)

Um principal de serviço e as respetivas informações de ambiente associadas devem ser criadas e guardadas algures. O principal de serviço com owner função é recomendado, mas dependendo do exemplo, uma contributor função pode ser suficiente. Veja o README no repositório de exemplo para obter os valores necessários. Pode ler estes valores em qualquer formato suportado pela linguagem SDK, como a partir de um ficheiro JSON (que os nossos exemplos utilizam). Consoante o exemplo que está a ser executado, nem todos estes valores podem ser utilizados. Veja o repositório de exemplo para obter código de exemplo atualizado ou mais informações.

ID do inquilino

Para localizar o diretório ou ID de inquilino do Azure Stack Hub, siga as instruções neste artigo.

Registar fornecedores de recursos

Registe os fornecedores de recursos necessários ao seguir este documento. Estes fornecedores de recursos serão necessários consoante os exemplos que pretende executar. Por exemplo, se quiser executar um exemplo de VM, é necessário o registo do Microsoft.Compute fornecedor de recursos.

Ponto final do Azure Stack Resource Manager

O Azure Resource Manager (ARM) é uma arquitetura de gestão que permite aos administradores implementar, gerir e monitorizar recursos do Azure. O Azure Resource Manager pode processar estas tarefas como um grupo, em vez de individualmente, numa única operação. Pode obter as informações de metadados do ponto final Resource Manager. O ponto final devolve um ficheiro JSON com as informações necessárias para executar o código.

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

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 de raiz da AC do Azure Stack Hub

Se estiver a utilizar o Azure Stack Development Kit (ASDK), tem de confiar no certificado de raiz da AC no seu computador remoto. Não precisa de confiar no certificado de raiz da AC com sistemas integrados do Azure Stack Hub.

Windows

Exporte o certificado autoassinado do Azure Stack Hub para o seu ambiente de trabalho.
Numa linha de comandos, altere o diretório para %JAVA_HOME%\bin.

Execute o seguinte comando:

.\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: o perfil mais recente criado para o Azure Stack Hub. Utilize este perfil para que os serviços sejam mais compatíveis com o Azure Stack Hub, desde que esteja na versão 1904 ou posterior.
com.microsoft.azure.profile_2018_03_01_hybrid: Perfil criado para o Azure Stack Hub. Utilize este 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. Utilize as versões mais recentes de todos os serviços.

Para obter mais informações sobre o Azure Stack Hub e perfis de API, veja o Resumo dos perfis de API.

Utilização do perfil da API do SDK Java do Azure

O código seguinte autentica o principal de serviço no Azure Stack Hub. Cria um token com o ID do inquilino 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());

Este código permite-lhe utilizar as dependências do perfil de API para implementar a sua aplicação com êxito no Azure Stack Hub.

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

Para registar a cloud do Azure Stack Hub com os pontos finais corretos, utilize 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 obtém os pontos finais dos pontos finais de metadados. Indica as variáveis de ambiente da chamada efetuada:

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 com o seguinte comando:

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

Crie um principal de serviço do Azure e atribua uma função para aceder à subscrição. Para obter instruções sobre como criar um principal de serviço, veja Utilizar Azure PowerShell para criar um principal de serviço com um certificado.
Obtenha 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 com as informações obtidas do principal de serviço que criou com a linha de comandos:
- 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, utilize o conjunto em vez de exportar.

Utilize a getActiveDirectorySettings função para obter os pontos finais de metadados do Azure Resource Manager.

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

No ficheiro Pom.xml , adicione a seguinte dependência para utilizar o perfil híbrido 2019-03-01 para o Azure Stack Hub. Esta dependência instala os módulos associados a este perfil para os fornecedores de recursos Computação, Rede, Armazenamento, Key Vault e Serviços de Aplicações:
```
<dependency>
  <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
  <artifactId>azure</artifactId>
  <version>1.0.0-beta-1</version>
</dependency>
```
Na linha de comandos que estava aberta para definir as variáveis de ambiente, introduza o seguinte comando:
```
mvn clean compile exec:java
```

Amostras

Veja este repositório de exemplo para obter o código de exemplo de atualização até à data (faixa 2). Veja este repositório de exemplo para controlar 1 código de exemplo. A raiz README.md descreve os requisitos gerais e cada subdiretório contém uma amostra específica com a sua própria README.md forma de executar esse exemplo.

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

Passos seguintes

Saiba mais sobre perfis de API: