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

O SDK do Java para o Azure Stack Hub Resource Manager fornece ferramentas para ajudá-lo a criar e gerenciar sua infraestrutura.The Java SDK for the Azure Stack Hub Resource Manager provides tools to help you build and manage your infrastructure. Os provedores de recursos no SDK incluem computação, rede, armazenamento, serviços de aplicativos e Key Vault.Resource providers in the SDK include Compute, Networking, Storage, App Services, and Key Vault.

O SDK do Java incorpora perfis de API, incluindo dependências no arquivo de Pom.xml que carrega os módulos corretos no arquivo . 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, você pode adicionar vários perfis como dependências, como 2019-03-01-híbridoou mais recente, como o perfil do Azure.However, you can add multiple profiles as dependencies, such as the 2019-03-01-hybrid, or latest, as the Azure profile. O uso dessas dependências carrega o módulo correto para que, ao criar o tipo de recurso, você possa selecionar qual versão de API desses perfis você deseja usar.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. Isso permite que você use as versões mais recentes no Azure, ao desenvolver com base nas versões de API mais atuais para 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.

O uso do SDK do Java permite uma verdadeira experiência de desenvolvedor de nuvem híbrida.Using the Java SDK enables a true hybrid cloud developer experience. Os perfis de API no SDK do Java habilitam o desenvolvimento de nuvem híbrida, ajudando você a alternar entre recursos globais e recursos do Azure no Hub Azure Stack.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 de API é uma combinação de provedores de recursos e versões de API.An API profile is a combination of resource providers and API versions. Use um perfil de API para obter a versão mais recente e mais estável de cada tipo de recurso em um pacote de provedor de recursos.Use an API profile to get the latest, most stable version of each resource type in a resource provider package.

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

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

    • Para usar os serviços mais recentes com suporte disponíveis no Hub Azure Stack, use 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 arquivo de Pom.xml como uma dependência, que carrega módulos automaticamente se você escolher a classe correta na lista suspensa (como faria com o .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 maneira: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 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.To use specific API versions for a resource type in a specific resource provider, use the specific API versions defined through Intellisense.

Você pode combinar todas as opções no mesmo aplicativo.You can combine all of the options in the same app.

Instalar o SDK do Java do AzureInstall the Azure Java SDK

Siga estas etapas para instalar o SDK do Java: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. Consulte introdução-instalando o Git.See Getting Started - Installing Git.

  2. Siga as instruções para instalar o SDK do Java 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 do Apache Maven é a 3,0 ou superior.The correct version of Apache Maven is 3.0 or above. 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.To complete the quickstart, the JAVA_HOME environment variable must be set to the install location of the Java Development Kit. Para obter mais informações, consulte criar 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 arquivo Pom.xml em seu aplicativo Java.To install the correct dependency packages, open the Pom.xml file in your Java app. Adicione uma dependência, conforme mostrado no código a seguir: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 ser instalados depende da versão do perfil que você deseja usar.The set of packages that need to be installed depends on the profile version you want to use. Os nomes de pacote 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 assinatura e salve a ID da assinatura para uso posterior.If not available, create a subscription and save the subscription ID for later use. Para obter instruções sobre como criar uma assinatura, consulte criar assinaturas para ofertas no Hub Azure Stack.For instructions on how to create a subscription, see Create subscriptions to offers in Azure Stack Hub.

  6. Crie uma entidade de serviço e salve a ID 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 uma entidade de serviço para Azure Stack Hub, consulte fornecer acesso de aplicativos ao hub Azure Stack.For instructions on how to create a service principal for Azure Stack Hub, see Provide applications access to Azure Stack Hub. A ID do cliente também é conhecida como a ID do aplicativo ao criar uma entidade de serviço.The client ID is also known as the application ID when creating a service principal.

  7. Verifique se a entidade de serviço tem a função colaborador/proprietário em sua assinatura.Make sure your service principal has the contributor/owner role on your subscription. Para obter instruções sobre como atribuir uma função à entidade de serviço, consulte fornecer acesso de aplicativos 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 usar o SDK do Java do Azure com o Hub Azure Stack, você deve fornecer os valores a seguir e, em seguida, definir valores com variáveis de ambiente.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 após a tabela do seu sistema operacional.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 locatárioTenant ID AZURE_TENANT_ID Sua ID de locatáriodo Hub de Azure Stack.Your Azure Stack Hub tenant ID.
ID do ClienteClient ID AZURE_CLIENT_ID A ID do aplicativo da entidade de serviço salva quando a entidade de serviço foi criada na seção anterior.The service principal application ID saved when the service principal was created in the previous section.
ID da assinaturaSubscription ID AZURE_SUBSCRIPTION_ID Você usa a ID da assinatura para acessar ofertas no Hub Azure Stack.You use the subscription ID to access offers in Azure Stack Hub.
Segredo do clienteClient Secret AZURE_CLIENT_SECRET O segredo do aplicativo da entidade de serviço salvo quando a entidade de serviço foi criada.The service principal application secret saved when the service principal was created.
Ponto de extremidade do Resource ManagerResource Manager Endpoint ARM_ENDPOINT Consulte o artigo Azure Stack ponto de extremidade do Gerenciador de recursos do Hub .See the Azure Stack Hub Resource Manager endpoint article.
LocationLocation RESOURCE_LOCATION Local para Azure Stack Hub.Local for Azure Stack Hub.

Para localizar a ID de locatário para seu hub de Azure Stack, consulte as instruções aqui.To find the tenant ID for your Azure Stack Hub, see the instructions here. Para definir suas variáveis de ambiente, use os procedimentos nas seções a seguir:To set your environment variables, use the procedures in the following sections:

Microsoft WindowsMicrosoft Windows

Para definir as variáveis de ambiente em um prompt de comando do Windows, use 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

Em sistemas baseados em UNIX, use o seguinte comando:In Unix-based systems, use the following command:

Export AZURE_TENANT_ID=<Your_Tenant_ID>

Confiar no certificado raiz da AC do hub de Azure StackTrust the Azure Stack Hub CA root certificate

Se você estiver usando o Kit de Desenvolvimento do Azure Stack (ASDK), deverá confiar no certificado raiz da autoridade de certificação em seu computador remoto.If you are using the Azure Stack Development Kit (ASDK), you must trust the CA root certificate on your remote machine. Você não precisa confiar no certificado raiz da autoridade de certificação com sistemas integrados de Hub Azure Stack.You do not need to trust the CA root certificate with Azure Stack Hub integrated systems.

WindowsWindows

  1. Exporte o certificado autoassinado do hub de Azure Stack para sua área de trabalho.Export the Azure Stack Hub self-signed certificate to your desktop.

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

  3. Execute o comando a seguir: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 de extremidade do Gerenciador de recursos do Hub Azure StackThe Azure Stack Hub Resource Manager endpoint

Azure Resource Manager é uma estrutura de gerenciamento que permite que os administradores implantem, gerenciem e monitorem recursos do Azure.Azure Resource Manager is a management framework that allows admins to deploy, manage, and monitor Azure resources. Azure Resource Manager pode lidar com essas tarefas como um grupo, em vez de individualmente, em uma única operação.Azure Resource Manager can handle these tasks as a group, rather than individually, in a single operation.

Você pode obter as informações de metadados do ponto de extremidade do Resource Manager.You can get the metadata info from the Resource Manager endpoint. O ponto de extremidade retorna um arquivo JSON com as informações necessárias para executar seu código.The endpoint returns a JSON file with the info required to run your code.

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

  • O ResourceManagerUrl no 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 <fqdn> é seu nome de domínio totalmente 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.

Arquivo JSON de exemplo: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: perfil mais recente criado para Azure Stack Hub.com.microsoft.azure.profile_2019_03_01_hybrid: Latest profile built for Azure Stack Hub. Use esse perfil para que os serviços sejam mais compatíveis com Azure Stack Hub, desde que você esteja no 1904 ou posterior.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 criado para Azure Stack Hub.com.microsoft.azure.profile_2018_03_01_hybrid: Profile built for Azure Stack Hub. Use este perfil para que os serviços sejam compatíveis com o Azure Stack Hub versões 1808 ou posteriores.Use this profile for services to be compatible with Azure Stack Hub versions 1808 or later.

  • com. Microsoft. Azure: perfil que consiste nas 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 Azure Stack perfis de Hub e API, consulte o Resumo dos perfis de API.For more information about Azure Stack Hub and API profiles, see the Summary of API profiles.

Uso do perfil da API do SDK do Java do AzureAzure Java SDK API profile usage

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

Esse código permite que você use as dependências do perfil de API para implantar seu aplicativo com êxito para Azure Stack Hub.This code enables you to use the API profile dependencies to deploy your app successfully to Azure Stack Hub.

Definir funções de configuração de ambiente de Hub de Azure StackDefine Azure Stack Hub environment setting functions

Para registrar a nuvem do hub de Azure Stack com os pontos de extremidade corretos, use 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 de extremidade dos pontos de extremidade de metadados.The getActiveDirectorySettings call in the previous code retrieves the endpoints from the metadata endpoints. Ele informa as variáveis de ambiente da chamada 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;
}

Exemplos usando perfis de APISamples using API profiles

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

Projeto de teste de unidade de exemploSample unit test project

  1. Clone o repositório usando 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 uma entidade de serviço do Azure e atribua uma função para acessar a assinatura.Create an Azure service principal and assign a role to access the subscription. 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.For instructions on creating a service principal, see Use Azure PowerShell to create a service principal with a certificate.

  3. Recupere as seguintes variáveis de ambiente 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. 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: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, use definir em vez de Exportar.In Windows, use set instead of export.

  5. Use a getActiveDirectorySettings função para recuperar os pontos de extremidade de metadados de 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 arquivo Pom.xml , adicione a seguinte dependência para usar o perfil 2019-03-01-híbrido para Azure Stack Hub.In the Pom.xml file, add the following dependency to use the 2019-03-01-hybrid profile for Azure Stack Hub. Essa dependência instala os módulos associados a esse perfil para os provedores de recursos de computação, rede, armazenamento, Key Vault e serviços de aplicativos: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. No prompt de comando que estava aberto para definir as variáveis de ambiente, digite o seguinte comando:In the command prompt that was open to set the environment variables, enter the following command:

    mvn clean compile exec:java
    

Próximas etapasNext steps

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