Use perfis de versão API com Java no Azure Stack HubUse API version profiles with Java in Azure Stack Hub

O Java SDK para o Azure Stack Hub Resource Manager fornece ferramentas para o ajudar a construir e gerir a sua infraestrutura.The Java SDK for the Azure Stack Hub Resource Manager provides tools to help you build and manage your infrastructure. Os fornecedores de recursos no SDK incluem Compute, Networking, Storage, App Services e Key Vault.Resource providers in the SDK include Compute, Networking, Storage, App Services, and Key Vault.

O Java SDK incorpora perfis API, incluindo dependências no ficheiro Pom.xml que carrega os módulos corretos no ficheiro .java.The Java SDK incorporates API profiles by including dependencies in the Pom.xml file that loads the correct modules in the .java file. No entanto, pode adicionar vários perfis como dependências, como o 2019-03-01-híbrido, ou o mais recente, como o perfil Azure.However, you can add multiple profiles as dependencies, such as the 2019-03-01-hybrid, or latest, as the Azure profile. A utilização destas dependências carrega o módulo correto para que, quando criar o seu tipo de recurso, possa selecionar qual a versão API a partir dos perfis que pretende utilizar.Using these dependencies loads the correct module so that when you create your resource type, you can select which API version from those profiles you want to use. Isto permite-lhe utilizar as versões mais recentes em Azure, ao mesmo tempo que se desenvolve contra as versões API mais atuais para o Azure Stack Hub.This enables you to use the latest versions in Azure, while developing against the most current API versions for Azure Stack Hub.

A utilização do SDK Java permite uma verdadeira experiência híbrida de desenvolvimento em nuvem.Using the Java SDK enables a true hybrid cloud developer experience. Os perfis da API no Java SDK permitem o desenvolvimento de nuvem híbrida ajudando-o a alternar entre recursos e recursos globais do Azure Stack Hub.API profiles in the Java SDK enable hybrid cloud development by helping you switch between global Azure resources and resources in Azure Stack Hub.

Perfis de versão Java e APIJava and API version profiles

Um perfil API é uma combinação de fornecedores de recursos e versões API.An API profile is a combination of resource providers and API versions. Utilize um perfil API para obter a versão mais recente e estável de cada tipo de recurso num pacote de fornecedor de recursos.Use an API profile to get the latest, most stable version of each resource type in a resource provider package.

  • Para utilizar as versões mais recentes de todos os serviços, utilize o perfil mais recente como dependência.To use the latest versions of all the services, use the latest profile as the dependency.

    • Para utilizar o perfil mais recente, a dependência é com.microsoft.azure.To use the latest profile, the dependency is com.microsoft.azure.

    • Para utilizar os mais recentes serviços suportados disponíveis no Azure Stack Hub, utilize o perfil híbrido com.microsoft.azure.profile _ 2019 _ _ 03 01. _To use the latest supported services available in Azure Stack Hub, use the com.microsoft.azure.profile_2019_03_01_hybrid profile.

      • O perfil é especificado no ficheiro Pom.xml como uma dependência, que carrega automaticamente os módulos se escolher a classe certa da lista de dropdown (como faria com .NET).The profile is specified in the Pom.xml file as a dependency, which loads modules automatically if you choose the right class from the dropdown list (as you would with .NET).
    • As dependências aparecem da seguinte forma:Dependencies appear as follows:

      <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 API específicas para um tipo de recurso num fornecedor de recursos específico, utilize as versões API específicas definidas através do Intellisense.To use specific API versions for a resource type in a specific resource provider, use the specific API versions defined through Intellisense.

Pode combinar todas as opções na mesma aplicação.You can combine all of the options in the same app.

Instale o Azure Java SDKInstall the Azure Java SDK

Siga estes passos para instalar o Java SDK:Follow these steps to install the Java SDK:

  1. Siga as instruções oficiais para instalar o Git.Follow the official instructions to install Git. Ver Começar - Instalar Git.See Getting Started - Installing Git.

  2. Siga as instruções para instalar o Java SDK e o Maven.Follow the instructions to install the Java SDK and Maven. A versão correta é a versão 8 do Java Developer Kit.The correct version is version 8 of the Java Developer Kit. A versão correta de Apache Maven é 3.0 ou superior.The correct version of Apache Maven is 3.0 or above. Para completar o arranque rápido, a JAVA_HOME variável ambiente deve ser definida para a localização de instalação do Kit de Desenvolvimento de Java.To complete the quickstart, the JAVA_HOME environment variable must be set to the install location of the Java Development Kit. Para mais informações, consulte Criar a sua primeira função com Java e Maven.For more info, see Create your first function with Java and Maven.

  3. Para instalar os pacotes de dependência corretos, abra o ficheiro Pom.xml na sua aplicação Java.To install the correct dependency packages, open the Pom.xml file in your Java app. Adicione uma dependência, como mostra o seguinte código:Add a dependency, as shown in the following code:

    <dependency>
    <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
    <artifactId>azure</artifactId>
    <version>1.0.0-beta-1</version>
    </dependency>
    
  4. O conjunto de pacotes que precisam de ser instalados depende da versão de perfil que pretende utilizar.The set of packages that need to be installed depends on the profile version you want to use. Os nomes dos pacotes para as versões de perfil são:The package names for the profile versions are:

    • com.microsoft.azure.profile _ 2019 _ 03 _ 01 _ híbridocom.microsoft.azure.profile_2019_03_01_hybrid
    • com.microsoft.azurecom.microsoft.azure
      • mais recentelatest
  5. Se não estiver disponível, crie uma subscrição e guarde o ID de subscrição para utilização posterior.If not available, create a subscription and save the subscription ID for later use. Para obter instruções sobre como criar uma subscrição, consulte Criar subscrições para ofertas no Azure Stack Hub.For instructions on how to create a subscription, see Create subscriptions to offers in Azure Stack Hub.

  6. Crie um diretor de serviço e guarde a identificação do cliente e o segredo do cliente.Create a service principal and save the client ID and the client secret. Para obter instruções sobre como criar um principal de serviço para o Azure Stack Hub, consulte fornecer acesso às aplicações ao Azure Stack Hub.For instructions on how to create a service principal for Azure Stack Hub, see Provide applications access to Azure Stack Hub. O ID do cliente também é conhecido como o ID da aplicação ao criar um principal de serviço.The client ID is also known as the application ID when creating a service principal.

  7. Certifique-se de que o seu titular de serviço tem a função de contribuinte/proprietário na sua subscrição.Make sure your service principal has the contributor/owner role on your subscription. Para obter instruções sobre como atribuir uma função ao principal de serviço, consulte fornecer acesso às aplicações ao Azure Stack Hub.For instructions on how to assign a role to service principal, see Provide applications access to Azure Stack Hub.

Pré-requisitosPrerequisites

Para utilizar o Azure Java SDK com Azure Stack Hub, deve fornecer os seguintes valores e, em seguida, definir valores com variáveis ambientais.To use the Azure Java SDK with Azure Stack Hub, you must supply the following values, and then set values with environment variables. Para definir as variáveis ambientais, consulte as instruções que seguem a tabela para o seu sistema operativo.To set the environmental variables, see the instructions following the table for your operating system.

ValorValue Variáveis de ambienteEnvironment variables DescriçãoDescription
ID do inquilinoTenant ID AZURE_TENANT_ID Sua identificação de inquilinoAzure Stack Hub.Your Azure Stack Hub tenant ID.
ID de ClienteClient ID AZURE_CLIENT_ID O ID principal da aplicação de serviço salvou-se quando o diretor de serviço foi criado na secção anterior.The service principal application ID saved when the service principal was created in the previous section.
ID da subscriçãoSubscription ID AZURE_SUBSCRIPTION_ID Utiliza o ID de subscrição para aceder a ofertas no Azure Stack Hub.You use the subscription ID to access offers in Azure Stack Hub.
Segredo do ClienteClient Secret AZURE_CLIENT_SECRET O segredo da aplicação principal do serviço salvou-se quando o diretor do serviço foi criado.The service principal application secret saved when the service principal was created.
Ponto final do Gestor de RecursosResource Manager Endpoint ARM_ENDPOINT Consulte o artigo de ponto final do Azure Stack Hub Resource Manager.See the Azure Stack Hub Resource Manager endpoint article.
LocalizaçãoLocation RESOURCE_LOCATION Local para Azure Stack Hub.Local for Azure Stack Hub.

Para encontrar a identificação do inquilino para o seu Azure Stack Hub, consulte as instruções aqui.To find the tenant ID for your Azure Stack Hub, see the instructions here. Para definir as variáveis ambientais, utilize os procedimentos nas seguintes secções:To set your environment variables, use the procedures in the following sections:

Microsoft WindowsMicrosoft Windows

Para definir as variáveis ambientais numa solicitação de comando do Windows, utilize o seguinte formato:To set the environment variables in a Windows command prompt, use the following format:

Set AZURE_TENANT_ID=<Your_Tenant_ID>

Sistemas baseados em MacOS, Linux e UnixMacOS, Linux, and Unix-based systems

Nos sistemas baseados na Unix, utilize o seguinte comando:In Unix-based systems, use the following command:

Export AZURE_TENANT_ID=<Your_Tenant_ID>

Confie no certificado raiz Azure Stack Hub CATrust the Azure Stack Hub CA root certificate

Se estiver a utilizar o Kit de Desenvolvimento da Pilha de Azure (ASDK), deve confiar no certificado raiz ca na sua máquina remota.If you are using the Azure Stack Development Kit (ASDK), you must trust the CA root certificate on your remote machine. Não precisa confiar o certificado de raiz da AC com sistemas integrados Azure Stack Hub.You do not need to trust the CA root certificate with Azure Stack Hub integrated systems.

WindowsWindows

  1. Exporte o certificado auto-assinado do Azure Stack Hub para o seu ambiente de trabalho.Export the Azure Stack Hub self-signed certificate to your desktop.

  2. Em um pedido de comando, mude o diretório para %JAVA_HOME%\bin .In a command prompt, change the directory to %JAVA_HOME%\bin.

  3. Execute o seguinte comando:Run the following command:

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

O ponto final do Gestor de Recursos do Hub Azure StackThe Azure Stack Hub Resource Manager endpoint

O Azure Resource Manager é um quadro de gestão que permite aos administradores implantar, gerir e monitorizar os recursos do Azure.Azure Resource Manager is a management framework that allows admins to deploy, manage, and monitor Azure resources. O Azure Resource Manager pode lidar com estas tarefas como um grupo, em vez de individualmente, numa única operação.Azure Resource Manager can handle these tasks as a group, rather than individually, in a single operation.

Pode obter a informação de metadados do ponto final do Gestor de Recursos.You can get the metadata info from the Resource Manager endpoint. O ponto final devolve um ficheiro JSON com a informação necessária para executar o seu código.The endpoint returns a JSON file with the info required to run your code.

Note as seguintes considerações:Note the following considerations:

  • O ResourceManagerUrl na ASDK é: https://management.local.azurestack.external/ .The ResourceManagerUrl in the ASDK is: https://management.local.azurestack.external/.

  • O ResourceManagerUrl em sistemas integrados é: https://management.region.<fqdn>/ , onde está o seu nome de domínio totalmente <fqdn> qualificado.The ResourceManagerUrl in integrated systems is: https://management.region.<fqdn>/, where <fqdn> is your fully qualified domain name.

Para recuperar os metadados necessários: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0 .To retrieve the metadata required: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0.

Ficheiro JSON da amostra:Sample JSON file:

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

Perfis de API existentesExisting API profiles

  • com.microsoft.azure.profile _ 2019 _ 03 _ 01 _ híbrido: Último perfil construído para O Azure Stack Hub.com.microsoft.azure.profile_2019_03_01_hybrid: Latest profile built for Azure Stack Hub. Utilize este perfil para que os serviços sejam mais compatíveis com o Azure Stack Hub, desde que esteja em 1904 ou mais tarde.Use this profile for services to be most compatible with Azure Stack Hub, as long as you're on 1904 or later.

  • com.microsoft.azure.profile _ 2018 _ 03 _ 01 _ híbrido: Perfil construído para Azure Stack Hub.com.microsoft.azure.profile_2018_03_01_hybrid: Profile built for Azure Stack Hub. Utilize este perfil para que os serviços sejam compatíveis com as versões Azure Stack Hub 1808 ou posterior.Use this profile for services to be compatible with Azure Stack Hub versions 1808 or later.

  • com.microsoft.azure: Perfil constituído pelas versões mais recentes de todos os serviços.com.microsoft.azure: Profile consisting of the latest versions of all services. Use as versões mais recentes de todos os serviços.Use the latest versions of all the services.

Para obter mais informações sobre os perfis Azure Stack Hub e API, consulte o Resumo dos perfis da API.For more information about Azure Stack Hub and API profiles, see the Summary of API profiles.

Utilização do perfil Azure Java SDK APIAzure Java SDK API profile usage

O código a seguir autentica o principal de serviço no Azure Stack Hub.The following code authenticates the service principal on Azure Stack Hub. Cria um símbolo usando o ID do inquilino e a base de autenticação, que é específica do Azure Stack Hub:It creates a token using the tenant ID and the authentication base, which is specific to 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 de perfis API para implementar a sua aplicação com sucesso no Azure Stack Hub.This code enables you to use the API profile dependencies to deploy your app successfully to Azure Stack Hub.

Defina funções de definição de ambiente do Azure Stack HubDefine Azure Stack Hub environment setting functions

Para registar a nuvem Azure Stack Hub com os pontos finais corretos, utilize o seguinte código:To register the Azure Stack Hub cloud with the correct endpoints, use the following code:

// 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 finais dos pontos finais dos metadados.The getActiveDirectorySettings call in the previous code retrieves the endpoints from the metadata endpoints. Diz as variáveis ambientais da chamada que é feita:It states the environment variables from the call that's made:

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

Amostras usando perfis de APISamples using API profiles

Utilize as seguintes amostras do GitHub como referências para a criação de soluções com perfis API .NET e Azure Stack Hub:Use the following GitHub samples as references for creating solutions with .NET and Azure Stack Hub API profiles:

Projeto de teste da unidade de amostraSample unit test project

  1. Clone o repositório utilizando o seguinte comando:Clone the repository using the following command:

    git clone https://github.com/Azure-Samples/Hybrid-resources-java-manage-resource-group.git`
    
  2. Crie um diretor de serviço Azure e atribua uma função para aceder à subscrição.Create an Azure service principal and assign a role to access the subscription. Para obter instruções sobre a criação de um principal de serviço, consulte Use Azure PowerShell para criar um principal de serviço com um certificado.For instructions on creating a service principal, see Use Azure PowerShell to create a service principal with a certificate.

  3. Recuperar as seguintes variáveis ambientais necessárias:Retrieve the following required environment variables:

    • AZURE_TENANT_ID
    • AZURE_CLIENT_ID
    • AZURE_CLIENT_SECRET
    • AZURE_SUBSCRIPTION_ID
    • ARM_ENDPOINT
    • RESOURCE_LOCATION
  4. Desaprova as seguintes variáveis ambientais utilizando as informações obtidas do principal serviço que criou utilizando a solicitação de comando:Set the following environment variables using the info retrieved from the service principal you created using the command prompt:

    • 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.In Windows, use set instead of export.

  5. Utilize a getActiveDirectorySettings função para recuperar os pontos finais dos metadados do Azure Resource Manager.Use the getActiveDirectorySettings function to retrieve the Azure Resource Manager metadata endpoints.

    // Get Azure Stack Hub cloud endpoints
    final HashMap<String, String> settings = getActiveDirectorySettings(armEndpoint);
    
  6. No ficheiro Pom.xml, adicione a seguinte dependência para usar o perfil híbrido 2019-03-01 para o Azure Stack Hub.In the Pom.xml file, add the following dependency to use the 2019-03-01-hybrid profile for Azure Stack Hub. Esta dependência instala os módulos associados a este perfil para os fornecedores de recursos de Computação, Rede, Armazenamento, Cofre-Chave e Serviços de Aplicações:This dependency installs the modules associated with this profile for the Compute, Networking, Storage, Key Vault, and App Services resource providers:

    <dependency>
      <groupId>com.microsoft.azure.profile_2019_03_01_hybrid</groupId>
      <artifactId>azure</artifactId>
      <version>1.0.0-beta-1</version>
    </dependency>
    
  7. Na pronta de comando que estava aberta para definir as variáveis ambientais, insira o seguinte comando:In the command prompt that was open to set the environment variables, enter the following command:

    mvn clean compile exec:java
    

Passos seguintesNext steps

Para obter mais informações sobre perfis de API, consulte:For more information about API profiles, see: