Use SDK V2.0 to initialize a client and make OpenAPI requests (Java SDK) - Alibaba Cloud SDK: Central de Documentação do Alibaba Cloud

Integre um SDK da Alibaba Cloud ao seu projeto para chamar operações da OpenAPI. A integração envolve três etapas: importar o SDK, definir credenciais de acesso e chamar a API.

Pré-requisitos

JDK 1.8 ou superior.

Importar o SDK

Faça login no SDK Center e selecione o product desejado, como o Short Message Service (SMS).
Na página Install, defina All Languages como Java. Em seguida, na aba Quick Start, localize o método de instalação do SDK do Short Message Service (SMS).

Definir credenciais de acesso

Chamar uma OpenAPI exige credenciais de acesso, como AccessKey e Security Token Service (STS) token. Armazene as credenciais como variáveis de ambiente para evitar vazamentos. As melhores práticas de segurança estão descritas em Securely use access credentials. O exemplo a seguir utiliza as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET:

Método de configuração no Linux e macOS

Os exemplos a seguir usam ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET como nomes de variáveis. Substitua-os pelos seus próprios nomes, se necessário, como OSS_ACCESS_KEY_ID e OSS_ACCESS_KEY_SECRET.

Execute os comandos export a seguir para definir as variáveis de ambiente:

Importante

As variáveis definidas com export são temporárias e válidas apenas para a sessão atual. Para persistência, adicione o comando export ao arquivo de inicialização do seu shell (como ~/.bashrc ou ~/.zshrc).

Defina o AccessKey ID:

# Replace yourAccessKeyID with your AccessKey ID.
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

Defina o AccessKey secret:

# Replace yourAccessKeySecret with your AccessKey secret.
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

Verifique a configuração.

Execute echo $ALIBABA_CLOUD_ACCESS_KEY_ID. Se o valor retornado estiver correto, a configuração foi bem-sucedida.

Método de configuração no Windows

Usar a interface gráfica do usuário (GUI)

Procedimento

As etapas a seguir descrevem como definir variáveis de ambiente pela GUI no Windows 10.

Na área de trabalho, clique em This PC e escolha Properties > Advanced system settings > Environment Variables > New em System variables ou User variables. Em seguida, conclua a configuração.

Variável	Valor de exemplo
AccessKey ID	Nome da variável: ALIBABA_CLOUD_ACCESS_KEY_ID Valor da variável: yourAccessKeyID
AccessKey secret	Nome da variável: ALIBABA_CLOUD_ACCESS_KEY_SECRET Valor da variável: yourAccessKeySecret

Testar a configuração

Clique em Start (ou use o atalho Win+R), clique em Run, insira 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 os comandos retornarem o AccessKey correto, a configuração foi bem-sucedida.

Usar o prompt de comando (CMD)

Procedimento

Abra o prompt de comando como administrador e execute os seguintes comandos para adicionar novas variáveis de ambiente ao sistema.
```
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
```
O parâmetro /M indica uma variável de ambiente do sistema. Omita esse parâmetro ao definir uma variável de ambiente de usuário.
Testar a configuração

Clique em Start (ou use o atalho Win+R), clique em Run, insira 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 os comandos retornarem o AccessKey correto, a configuração foi bem-sucedida.

Usar o Windows PowerShell

No PowerShell, defina novas variáveis de ambiente válidas para todas as novas sessões:

[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, são necessárias permissões administrativas:

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

Defina 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 os comandos retornarem o AccessKey correto, a configuração foi bem-sucedida.

Usar o SDK

O exemplo a seguir chama a API SendMessageToGlobe do Short Message Service (SMS). Referência da API SendMessageToGlobe: SendMessageToGlobe.

1. Inicializar o cliente de requisição

Todas as chamadas da OpenAPI partem de um cliente de requisição (Client). Este exemplo inicializa o cliente com um AccessKey. Outros métodos de inicialização estão descritos em gerencie access credentials.

Importante

As instâncias de Client são thread-safe e podem ser compartilhadas entre threads.
Evite criar objetos Client repetidamente com new. Utilize o padrão singleton para reutilizar um único cliente por conjunto de credenciais e endpoint.

public static com.aliyun.dysmsapi20180501.Client createClient() throws Exception {
    com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    // See https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = "dysmsapi.aliyuncs.com";
    return new com.aliyun.dysmsapi20180501.Client(config);
}

2. Criar um objeto de requisição

Passe parâmetros pelo objeto de requisição do SDK, nomeado no formato <OpenAPIName>Request (por exemplo, SendSmsRequest para SendSms). Detalhes dos parâmetros de requisição: SendMessageToGlobe.

Nota

Se uma API não tiver parâmetros de requisição, ignore o objeto de requisição (por exemplo, DescribeCdnSubList).

com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest sendMessageToGlobeRequest = new com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest()
                .setTo("8521245567****")
                .setMessage("Hello");

3. Enviar uma requisição

Chame a API usando um método no formato <apiName>WithOptions, onde <apiName> é o nome da API em camelCase. Esse método recebe o objeto de requisição e um parâmetro de runtime que controla timeout, proxy e outras configurações. As opções de runtime estão detalhadas em Advanced configuration.

Nota

Se uma API não tiver parâmetros de requisição, passe apenas o parâmetro de runtime (por exemplo, DescribeCdnSubList).

Os objetos de resposta seguem a convenção de nomenclatura <OpenAPIName>Response (por exemplo, SendSmsResponse).

com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
Client client = createClient();
// call  api
client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);

4. Tratar exceções

O SDK Java possui dois tipos de exceção: TeaUnretryableException e TeaException.

TeaUnretryableException: Lançada após esgotar todas as tentativas de nova tentativa, geralmente devido a problemas de rede.
TeaException: Lançada para erros de lógica de negócios.

Os padrões de tratamento de exceções estão detalhados em Exception handling.

Importante

Sempre trate as exceções adequadamente — propague, registre ou recupere — para manter a estabilidade do sistema.

Visualize o exemplo de código completo

Exemplo de chamada da API SendMessageToGlobe

import com.aliyun.dysmsapi20180501.Client;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // See https://api.alibabacloud.com/product/Dysmsapi.
        config.endpoint = "dysmsapi.aliyuncs.com";
        return new Client(config);
    }

    public static void main(String[] args_) {
        try {
            Client client = Sample.createClient();
            SendMessageToGlobeRequest sendMessageToGlobeRequest = new SendMessageToGlobeRequest()
                    .setTo("8521245567****")
                    .setMessage("Hello");
            RuntimeOptions runtime = new RuntimeOptions();

            SendMessageToGlobeResponse sendMessageToGlobeResponse = client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
            System.out.println(new Gson().toJson(sendMessageToGlobeResponse.body));
        } catch (TeaUnretryableException ue) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            ue.printStackTrace();
            // print error message
            System.out.println(ue.getMessage());
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            e.printStackTrace();
            // print error message
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            System.out.println(e.getData());
        } catch (Exception e) {
            // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
            e.printStackTrace();
        }
    }
}

Upload de arquivos com a interface Advance

Alguns products (por exemplo, Image Search, Visual Intelligence API) não suportam diretamente uploads de arquivos pela OpenAPI padrão. Use a interface Advance para passar um fluxo de arquivo. O product armazena temporariamente o arquivo enviado no Alibaba Cloud OSS (região padrão: cn-shanghai) e o lê a partir daí. O exemplo a seguir usa DetectBodyCount do Visual Intelligence API - Face and Body:

Nota

Arquivos temporários no OSS são limpos periodicamente.

Inicializar o cliente de requisição

Defina tanto regionId quanto endpoint. O regionId determina a região do OSS para armazenamento temporário de arquivos. Se regionId não for definido, a incompatibilidade de região entre o product e o OSS pode causar timeouts.

public static com.aliyun.facebody20191230.Client createClient() throws Exception {
     com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
             // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") gets the AccessKey ID from the environment variable.
             .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
             // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") gets the AccessKey secret from the environment variable.
             .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
     config.regionId = "cn-shanghai";
     config.endpoint = "facebody.cn-shanghai.aliyuncs.com";
     return new com.aliyun.facebody20191230.Client(config);
}

Criar um objeto de requisição

Crie um objeto <OpenAPIName>AdvanceRequest para passar o fluxo de arquivo. Verifique o arquivo source do <OpenAPIName>AdvanceRequest para obter nomes e tipos de parâmetros. Por exemplo, DetectBodyCountAdvanceRequest aceita imageURLObject do tipo InputStream.

com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
        .setImageURLObject(Files.newInputStream(Paths.get("<FILE_PATH>"))); // Replace <FILE_PATH> with the actual file path.

Iniciar uma requisição

Chame o método <apiName>Advance para enviar a requisição.

com.aliyun.facebody20191230.Client client = createClient();
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// Initiate the request.
com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);

Visualize o exemplo de código completo

/**
 * <dependency>
 *   <groupId>com.aliyun</groupId>
 *   <artifactId>facebody20191230</artifactId>
 *   <version>5.1.2</version>
 * </dependency>
 */

import com.aliyun.tea.*;
import com.google.gson.Gson;
import java.nio.file.Files;
import java.nio.file.Paths;

public class Sample {

    public static com.aliyun.facebody20191230.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") gets the AccessKey ID from the environment variable.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") gets the AccessKey secret from the environment variable.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        config.regionId = "cn-shanghai";
        config.endpoint = "facebody.cn-shanghai.aliyuncs.com";
        return new com.aliyun.facebody20191230.Client(config);
    }

    public static void main(String[] args_) {
        try {
            com.aliyun.facebody20191230.Client client = Sample.createClient();
            com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest detectBodyCountAdvance = new com.aliyun.facebody20191230.models.DetectBodyCountAdvanceRequest()
                    .setImageURLObject(Files.newInputStream(Paths.get("<FILE_PATH>")));  // Replace <FILE_PATH> with the actual file path.
            com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
            com.aliyun.facebody20191230.models.DetectBodyCountResponse resp = client.detectBodyCountAdvance(detectBodyCountAdvance, runtime);
            System.out.println(new Gson().toJson(resp.body));
        } catch (TeaUnretryableException ue) {
            ue.printStackTrace();
            // Print the error message.
            System.out.println(ue.getMessage());
            // Print the request record to query the request information when an error occurs.
            System.out.println(ue.getLastRequest());
        } catch (TeaException e) {
            e.printStackTrace();
            // Print the error code.
            System.out.println(e.getCode());
            // Print the error message, which includes the RequestId.
            System.out.println(e.getMessage());
            // Print the specific error content returned by the server.
            System.out.println(e.getData());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

FAQ

A mensagem de erro "You are not authorized to perform this operation." é retornada ao chamar uma OpenAPI.

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

Solução: Conceda as permissões necessárias ao usuário RAM. Grant permissions to a RAM user.

Por exemplo, para autorizar a API SendMessageToGlobe, crie a seguinte política personalizada:
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "dysms:SendMessageToGlobe",
      "Resource": "*"
    }
  ]
}
```
A mensagem de erro "The specified endpoint can't operate this region." é retornada ao chamar uma OpenAPI.

Causa: O endpoint especificado não suporta a região de destino.

Solução: Atualize o endpoint conforme descrito em Endpoint configuration e tente novamente.
A mensagem de erro "java.lang.NullPointerException..." é retornada ao chamar uma OpenAPI.

Causa: Seu AccessKey não foi passado corretamente.

Solução: Verifique se o AccessKey está sendo passado corretamente durante a inicialização do cliente. System.getenv("XXX") lê o valor de XXX das variáveis de ambiente.

Solução de problemas adicional: FAQ.