Todos os produtos
Search

Este produto

    Cloud Control API:SDK de integração Java

    Central de documentação

    Cloud Control API:SDK de integração Java

    Última atualização: Jun 28, 2026

    O SDK Java da Cloud Control API oferece interfaces padronizadas para gerenciar todo o ciclo de vida dos seus recursos Alibaba Cloud, incluindo criação, consulta, atualização e exclusão. O SDK simplifica o desenvolvimento para que você possa se concentrar na lógica de negócios em vez dos detalhes de baixo nível da API.

    Pré-requisitos

    • Para chamar a Cloud Control API, é necessário um par de AccessKey. Como o par de AccessKey da sua conta Alibaba Cloud possui permissões totais, recomendamos criar um usuário RAM e utilizar o par de AccessKey desse usuário. Para mais informações, consulte Criar um usuário RAM e Criar um AccessKey.

    • Configure credenciais de acesso para chamar a Cloud Control API. Um tipo comum de credencial é AccessKey (AK). Para evitar vazamentos, armazene as credenciais como variáveis de ambiente.

      Nota

      Este tópico utiliza as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET como exemplos.

      Definir credenciais de acesso como variáveis de ambiente do sistema

      Linux e macOS

      Usar o comando export

      Importante

      As variáveis de ambiente definidas com o comando export são temporárias e válidas apenas para a sessão atual. Para torná-las persistentes, adicione o comando ao arquivo de inicialização do seu sistema operacional.

      • Configure o AccessKey ID e pressione Enter.

        # Replace <ACCESS_KEY_ID> with your AccessKey ID.
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

      • Configure o AccessKey Secret e pressione Enter.

        # Replace <ACCESS_KEY_SECRET> with your AccessKey Secret.
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

      • Verifique a configuração.

        Execute o comando echo $ALIBABA_CLOUD_ACCESS_KEY_ID. Se o sistema retornar o AccessKey ID correto, a configuração foi bem-sucedida.

      Windows

      GUI

      • Passos

        Na área de trabalho, clique com o botão direito em This PC e selecione Properties > Advanced system settings > Environment Variables > System variables/User variables > New. Configure os seguintes parâmetros:

        Parameter

        Example value

        AccessKey ID

        • Variable name: ALIBABA_CLOUD_ACCESS_KEY_ID

        • Variable value: LTAI

        AccessKey Secret

        • Variable name: ALIBABA_CLOUD_ACCESS_KEY_SECRET

        • Variable value: yourAccessKeySecret

      • Verifique a configuração.

        Clique em Start (ou use o atalho Win+R), selecione Run, digite cmd e clique em OK (ou pressione Enter) para abrir o Prompt de Comando. Execute os comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% e echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.

      CMD

      • Passos

        Abra o Prompt de Comando como administrador e utilize os comandos abaixo para adicionar variáveis de ambiente do sistema.

        setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M

        A flag /M define uma variável de ambiente no nível do sistema. Omita essa flag para definir uma variável de ambiente no nível do usuário.

      • Verifique a configuração.

        Clique em Start (ou use o atalho Win+R), selecione Run, digite cmd e clique em OK (ou pressione Enter) para abrir o Prompt de Comando. Execute os comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% e echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.

      PowerShell

      Para definir novas variáveis de ambiente persistentes em todas as novas sessões, execute os seguintes comandos no PowerShell:

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)

      Para definir variáveis de ambiente para todos os usuários (requer privilégios de administrador):

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)

      Para definir variáveis de ambiente temporárias (válidas apenas para a sessão atual):

      $env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"

      No PowerShell, execute os comandos Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID e Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.

    • Antes de chamar a Cloud Control API, certifique-se de que o usuário RAM possui as permissões necessárias para os recursos de destino. Para mais informações, consulte Gerenciar permissões para um usuário RAM.

    • Para um controle mais granular, crie uma política de permissão personalizada. Para obter instruções, consulte Criar uma política personalizada.

      Nota

      Este tópico usa a listagem de recursos VPC como exemplo.

      • Autorização rápida: Conceda a política AliyunCloudControlAPIFullAccess, que fornece permissões totais para todas as operações da Cloud Control API.

      • Autorização granular: Crie uma política de permissão personalizada que conceda apenas as permissões necessárias, como listar recursos VPC.

        Política de permissão personalizada para listar recursos VPC

        {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudcontrol:List*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "vpc:DescribeVpcs",
      "Resource": "*"
    }
  ]
}

    Requisitos

    JDK versão 1,8 ou posterior.

    Adicionar dependência do SDK

    1. Faça login no SDK Center e selecione o produto Cloud Control API (por exemplo, se desejar chamar uma API para listar recursos).

    2. Na página Installation, selecione Java na lista suspensa All Languages. O método de instalação do SDK da Cloud Control API está disponível na guia Quick Start.

      <dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>cloudcontrol20220830</artifactId>
  <version>1.1.1</version>
</dependency>

    Chamar a API

    Esta seção demonstra como chamar a API GetResources para listar recursos VPC.

    Inicializar o cliente

    Todas as chamadas à Cloud Control API no SDK passam por um cliente. Para inicializar o cliente, especifique o endpoint de serviço da sua região. Você encontra o endpoint na seção Service Region do Portal da Cloud Control API. Para mais informações sobre endpoints de serviço, consulte Regiões suportadas. Este exemplo inicializa o cliente com um par de AccessKey. Para outros métodos de inicialização, consulte Gerenciar credenciais de acesso para o SDK Java.

    // Initialize the client.
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// System.getenv() retrieves the AccessKey from environment variables.
    .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
    .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
// Service endpoint
config.endpoint = "cloudcontrol.aliyuncs.com";
com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);
//        Initialize the client by using the default credentials provider chain.
//        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
//        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//                .setCredential(credentialClient);
//        config.endpoint = "cloudcontrol.aliyuncs.com";
//        com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);
    Nota

    • A função getenv() lê uma variável de ambiente. Se você definiu variáveis de ambiente chamadas ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET na sua máquina, getenv() recupera seus valores.

    • Ao inicializar o cliente de credenciais sem parâmetros, a ferramenta Credentials utiliza a cadeia de provedores de credenciais padrão. Para entender a lógica de recuperação das credenciais padrão, consulte cadeia de provedores de credenciais padrão.

    Definir o caminho da requisição

    // Request path
String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";
    Nota

    O formato do caminho da requisição é /api/v1/providers/{provider}/products/{product}/resources/{resourceTypeCode}.

    • A tabela a seguir descreve as variáveis no caminho da requisição.

      Campo

      Descrição

      Valor de exemplo

      {provider}

      Nome do provedor de nuvem. Apenas Aliyun é suportado.

      Aliyun

      {product}

      Código do produto. Obtido chamando a operação ListProducts.

      VPC

      {resourceTypeCode}

      Código do recurso. Obtido chamando a operação ListProducts.

      VPC

    • Verifique se um recurso possui um recurso pai analisando o formato do seu resourceType:

      Formato ResourceType

      Descrição

      Valor de exemplo

      ****

      Se o valor não contiver /, o recurso não possui pai.

      VPC

      ****/****

      A presença de / no tipo de recurso indica que ele possui um pai. Por exemplo, o ApsaraDB for Redis tem recursos para instâncias Redis (DBInstance) e contas de banco de dados (DBInstance/Account). O tipo de recurso de uma conta de banco de dados é "DBInstance/Account", onde "DBInstance" é o tipo de recurso do seu pai, a instância Redis.

      DBInstance/Account

      Para mais informações, consulte Recursos pais e filhos.

    Criar um objeto de requisição

    Objetos de requisição são instâncias de classes nomeadas <OperationName>Request. Defina os parâmetros da API usando as propriedades do objeto de requisição.

    // Filter conditions (optional)
// java.util.Map < String, Object > filter = TeaConverter.buildMap(
//    new TeaPair("IsDefault", true), // Specifies whether the VPC is the default VPC.
//    new TeaPair("ResourceGroupId", "<YOUR_RESOURCEGROUPID>"), // The resource group ID.
//    new TeaPair("DhcpOptionsSetId", "<YOUR_DHCPOPTIONSSETID>"), // The ID of the DHCP options set.
//    new TeaPair("VpcId", "<YOUR_VPCID>"), // The VPC ID.
//    new TeaPair("VpcName", "<YOUR_VPCNAME>") // The VPC name.
// );
// Create a request object.
com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
    .setRegionId("cn-hangzhou") // The region ID.
//    .setFilter(filter) // The query filter conditions.
//    .setNextToken("") // The token for the next page of results.
    .setMaxResults(2); // The number of results per page for paginated queries.

    Enviar a requisição

    As chamadas de API utilizam métodos do cliente nomeados <operationName>WithOptions, onde <operationName> é o nome da operação da API em camelCase. Este método aceita quatro argumentos: o caminho da requisição, o objeto de requisição, parâmetros de cabeçalho e opções de runtime. As opções de runtime configuram o comportamento da requisição, como timeouts e configurações de proxy.

    // Define runtime options.
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
//        // Ignore SSL certificate verification.
//        runtime.ignoreSSL = true;
//        // Proxy configuration.
//        runtime.httpProxy = "http://127.0.0.1:9898";
//        runtime.httpsProxy = "http://user:password@127.0.0.1:8989";
//        runtime.noProxy = "127.0.0.1,localhost";
//        // Connection timeout.
//        runtime.connectTimeout = 5000;
//        // Read timeout.
//        runtime.readTimeout = 10000;
//        // Enable the automatic retry mechanism.
//        runtime.autoretry = true;
//        // Set the maximum number of retries.
//        runtime.maxAttempts = 3;
// Use headers to customize request headers, which can override defaults or add extra information.
java.util.Map < String, String > headers = new java.util.HashMap<>();
//        headers.put("x-acs-action", "GetResources"); // Set the API operation name.
// Send the request.
GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);

    Tratar exceções

    O SDK Java V2.0 classifica as exceções em dois tipos: TeaUnretryableException e TeaException.

    • TeaUnretryableException: Lançada após atingir o número máximo de tentativas, geralmente causada por problemas de rede.

    • TeaException: Exceção que indica erros de serviço.

    Importante

    Implemente um tratamento robusto de exceções para registrar erros, gerenciar recuperação e garantir a estabilidade do sistema.

    Exemplo de código

    package com.aliyun.sample;
import com.aliyun.cloudcontrol20220830.models.*;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.google.gson.Gson;
public class Sample {
    public static com.aliyun.cloudcontrol20220830.Client createClient() throws Exception {
        // Initialize the client by using the default credentials provider chain. This is a more secure, keyless approach.
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            .setCredential(credential);
        config.endpoint = "cloudcontrol.aliyuncs.com";
        return new com.aliyun.cloudcontrol20220830.Client(config);
    }
    public static void main(String[] args_) throws Exception {
        com.aliyun.cloudcontrol20220830.Client client = Sample.createClient();
        // Request path
        String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";
        // Request object
        com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
            .setRegionId("cn-hangzhou");
        // Runtime options
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        // Custom request headers
        java.util.Map < String, String > headers = new java.util.HashMap < > ();
        try {
            // Send the request.
            GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);
            // Print the result.
            System.out.println(new Gson().toJson(getResourcesResponse.getBody()));
            // Get the request ID.
            System.out.println(getResourcesResponse.body.requestId);
        } catch (TeaException error) {
            // Error message
            System.out.println(error.getMessage());
            // Diagnostic URL
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (TeaUnretryableException ue) {
            ue.printStackTrace();
            // Print the error information.
            System.out.println(ue.getMessage());
            // Print the request record to locate the request information when the error occurred.
            System.out.println(ue.getLastRequest());
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Error message
            System.out.println(error.getMessage());
            // Diagnostic URL
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
    }
}

    Perguntas frequentes

    • Ao chamar uma API, recebo o erro "You are not authorized to perform this operation".

      Causa: O usuário RAM associado ao par de AccessKey não possui as permissões necessárias.

      Solução: Conceda ao usuário RAM as permissões de API necessárias. Para obter instruções, consulte Gerenciar permissões para um usuário RAM.

      Por exemplo, se você receber o erro "You are not authorized to perform this operation" ao chamar a API GetResources, crie uma política de permissão personalizada e conceda as permissões correspondentes ao usuário RAM.

      {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudcontrol:List*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "vpc:DescribeVpcs",
      "Resource": "*"
    }
  ]
}

    • Ao chamar uma API, recebo o erro "Cannot invoke "com.aliyun.credentials.Client.getCredential()" because "this._credential" is null".

      Causa: As variáveis de ambiente AccessKey não estão configuradas corretamente.

      Solução:

      Definir credenciais de acesso como variáveis de ambiente do sistema

      Linux e macOS

      Usar o comando export

      Importante

      As variáveis de ambiente definidas com o comando export são temporárias e válidas apenas para a sessão atual. Para torná-las persistentes, adicione o comando ao arquivo de inicialização do seu sistema operacional.

      • Configure o AccessKey ID e pressione Enter.

        # Replace <ACCESS_KEY_ID> with your AccessKey ID.
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

      • Configure o AccessKey Secret e pressione Enter.

        # Replace <ACCESS_KEY_SECRET> with your AccessKey Secret.
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

      • Verifique a configuração.

        Execute o comando echo $ALIBABA_CLOUD_ACCESS_KEY_ID. Se o sistema retornar o AccessKey ID correto, a configuração foi bem-sucedida.

      Windows

      GUI

      • Passos

        Na área de trabalho, clique com o botão direito em This PC e selecione Properties > Advanced system settings > Environment Variables > System variables/User variables > New. Configure os seguintes parâmetros:

        Parameter

        Example value

        AccessKey ID

        • Variable name: ALIBABA_CLOUD_ACCESS_KEY_ID

        • Variable value: LTAI

        AccessKey Secret

        • Variable name: ALIBABA_CLOUD_ACCESS_KEY_SECRET

        • Variable value: yourAccessKeySecret

      • Verifique a configuração.

        Clique em Start (ou use o atalho Win+R), selecione Run, digite cmd e clique em OK (ou pressione Enter) para abrir o Prompt de Comando. Execute os comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% e echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.

      CMD

      • Passos

        Abra o Prompt de Comando como administrador e utilize os comandos abaixo para adicionar variáveis de ambiente do sistema.

        setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M

        A flag /M define uma variável de ambiente no nível do sistema. Omita essa flag para definir uma variável de ambiente no nível do usuário.

      • Verifique a configuração.

        Clique em Start (ou use o atalho Win+R), selecione Run, digite cmd e clique em OK (ou pressione Enter) para abrir o Prompt de Comando. Execute os comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% e echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.

      PowerShell

      Para definir novas variáveis de ambiente persistentes em todas as novas sessões, execute os seguintes comandos no PowerShell:

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)

      Para definir variáveis de ambiente para todos os usuários (requer privilégios de administrador):

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)

      Para definir variáveis de ambiente temporárias (válidas apenas para a sessão atual):

      $env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"

      No PowerShell, execute os comandos Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID e Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET. Se o sistema retornar os valores corretos do AccessKey, a configuração foi bem-sucedida.