Use SDK V2.0 to initialize a client and make OpenAPI requests (Java SDK) - Alibaba Cloud SDK

Integre un SDK de Alibaba Cloud en su proyecto para llamar a las operaciones de OpenAPI. La integración consta de tres pasos: importar el SDK, establecer las credenciales de acceso y llamar a la API.

Requisitos previos

JDK 1.8 o posterior.

Importar el SDK

Inicie sesión en SDK Center y seleccione el producto que desea usar, por ejemplo, Short Message Service (SMS).
En la página Install, establezca All Languages en Java. A continuación, en la pestaña Quick Start, busque el método de instalación del SDK de Short Message Service (SMS).

Establecer las credenciales de acceso

Llamar a una OpenAPI requiere credenciales de acceso como AccessKey y Security Token Service (STS) token. Almacene las credenciales como variables de entorno para evitar filtraciones. Las mejores prácticas de seguridad se describen en Securely use access credentials. En el siguiente ejemplo se usan las variables de entorno ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET:

Método de configuración en Linux y macOS

En los siguientes ejemplos se utilizan ALIBABA_CLOUD_ACCESS_KEY_ID y ALIBABA_CLOUD_ACCESS_KEY_SECRET como nombres de variable. Si es necesario, reemplácelos con sus propios nombres, como OSS_ACCESS_KEY_ID y OSS_ACCESS_KEY_SECRET.

Ejecute los siguientes comandos export para establecer las variables de entorno:

Importante

Las variables establecidas con export son temporales y solo son válidas para la sesión actual. Para que sean persistentes, agregue el comando export a su archivo de inicio de shell (como ~/.bashrc o ~/.zshrc).

Establezca el AccessKey ID:

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

Establezca el secreto de AccessKey:

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

Compruebe la configuración.

Ejecute echo $ALIBABA_CLOUD_ACCESS_KEY_ID. Si se devuelve el valor correcto, la configuración fue exitosa.

Método de configuración en Windows

Usar la interfaz gráfica de usuario (GUI)

Procedimiento

A continuación se describe cómo establecer variables de entorno mediante la GUI en Windows 10.

En el escritorio, haga clic derecho en This PC y elija Properties > Advanced system settings > Environment Variables > New en System variables o User variables. Luego, complete la configuración.

Variable	Valor de ejemplo
AccessKey ID	Nombre de la variable: ALIBABA_CLOUD_ACCESS_KEY_ID Valor de la variable: yourAccessKeyID
Secreto de AccessKey	Nombre de la variable: ALIBABA_CLOUD_ACCESS_KEY_SECRET Valor de la variable: yourAccessKeySecret

Pruebe la configuración

Haga clic en Start (o use el atajo de teclado Win+R), haga clic en Run, introduzca cmd y luego haga clic en OK (o presione Enter) para abrir el símbolo del sistema. Ejecute los comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% y echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Si los comandos devuelven el AccessKey correcto, la configuración fue exitosa.

Usar el símbolo del sistema (CMD)

Procedimiento

Abra el símbolo del sistema como administrador y ejecute los siguientes comandos para agregar nuevas variables de entorno al sistema.
```
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
```
El parámetro /M indica una variable de entorno del sistema. Puede omitir este parámetro cuando establezca una variable de entorno de usuario.
Pruebe la configuración

Haga clic en Start (o use el atajo de teclado Win+R), haga clic en Run, introduzca cmd y luego haga clic en OK (o presione Enter) para abrir el símbolo del sistema. Ejecute los comandos echo %ALIBABA_CLOUD_ACCESS_KEY_ID% y echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%. Si los comandos devuelven el AccessKey correcto, la configuración fue exitosa.

Usar Windows PowerShell

En PowerShell, puede establecer nuevas variables de entorno válidas para todas las sesiones nuevas:

[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 establecer variables de entorno para todos los usuarios, debe tener permisos 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)

Puede establecer variables de entorno temporales que solo sean válidas para la sesión actual:

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

En PowerShell, ejecute los comandos Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID y Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET. Si los comandos devuelven el AccessKey correcto, la configuración fue exitosa.

Usar el SDK

En el siguiente ejemplo se llama a la API SendMessageToGlobe de Short Message Service (SMS). Referencia de la API SendMessageToGlobe: SendMessageToGlobe.

1. Inicializar el cliente de solicitud

Todas las llamadas a OpenAPI se originan desde un cliente de solicitud (Client). En este ejemplo se inicializa el cliente con un AccessKey. Otros métodos de inicialización se describen en Manage access credentials.

Importante

Las instancias de Client son seguras para hilos y se pueden compartir entre varios hilos.
Evite crear objetos Client de forma repetida con new. Use el patrón singleton para reutilizar un cliente por cada conjunto de credenciales y 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. Crear un objeto de solicitud

Pase los parámetros mediante el objeto de solicitud del SDK, nombrado con el formato <OpenAPIName>Request (por ejemplo, SendSmsRequest para SendSms). Detalles de los parámetros de solicitud: SendMessageToGlobe.

Nota

Si una API no tiene parámetros de solicitud, omita el objeto de solicitud (por ejemplo, DescribeCdnSubList).

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

3. Enviar una solicitud

Llame a la API mediante un método con el formato <apiName>WithOptions, donde <apiName> es el nombre de la API en formato camelCase. Este método recibe el objeto de solicitud y un parámetro de ejecución que controla el tiempo de espera, el proxy y otras configuraciones. Las opciones de ejecución se detallan en Advanced configuration.

Nota

Si una API no tiene parámetros de solicitud, pase únicamente el parámetro de ejecución (por ejemplo, DescribeCdnSubList).

Los objetos de respuesta siguen la convención de nomenclatura <OpenAPIName>Response (por ejemplo, SendSmsResponse).

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

4. Gestionar excepciones

El SDK de Java tiene dos tipos de excepciones: TeaUnretryableException y TeaException.

TeaUnretryableException: se lanza después de agotar todos los reintentos, generalmente debido a problemas de red.
TeaException: se lanza por errores de lógica de negocio.

Los patrones de gestión de excepciones se detallan en Exception handling.

Importante

Gestione siempre las excepciones de manera adecuada (propáguelas, regístrelas o recupérese de ellas) para mantener la estabilidad del sistema.

Consulte el ejemplo de código completo

Ejemplo de llamada a la 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();
        }
    }
}

Carga de archivos con la interfaz Advance

Algunos productos (por ejemplo, Image Search y Visual Intelligence API) no admiten directamente la carga de archivos a través de su OpenAPI estándar. Use la interfaz Advance para pasar un flujo de archivo. El producto en la nube almacena temporalmente el archivo cargado en Alibaba Cloud OSS (región predeterminada: cn-shanghai) y lo lee desde ahí. En el siguiente ejemplo se usa DetectBodyCount de Visual Intelligence API - Face and Body:

Nota

Los archivos temporales en OSS se eliminan periódicamente.

Inicialice el cliente de solicitud

Establezca tanto regionId como endpoint. El valor de regionId determina la región de OSS para el almacenamiento temporal de archivos. Si no se establece regionId, la discrepancia de región entre el producto y OSS puede provocar tiempos de espera agotados.

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

Cree un objeto de solicitud

Cree un objeto <OpenAPIName>AdvanceRequest para pasar el flujo de archivo. Consulte el archivo fuente de <OpenAPIName>AdvanceRequest para conocer los nombres y tipos de los parámetros. Por ejemplo, DetectBodyCountAdvanceRequest acepta imageURLObject de 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.
```

Envíe una solicitud

Llame al método <apiName>Advance para enviar la solicitud.

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

Consulte el ejemplo 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();
        }
    }
}

Preguntas frecuentes

Se devuelve el mensaje de error "You are not authorized to perform this operation." al llamar a una OpenAPI.

Causa: el usuario de RAM asociado a su AccessKey carece de los permisos obligatorios de la API.

Solución: otorgue los permisos necesarios al usuario de RAM. Grant permissions to a RAM user.

Por ejemplo, para autorizar la API SendMessageToGlobe, cree la siguiente política personalizada:
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "dysms:SendMessageToGlobe",
      "Resource": "*"
    }
  ]
}
```
Se devuelve el mensaje de error "The specified endpoint can't operate this region." al llamar a una OpenAPI.

Causa: el endpoint especificado no es compatible con la región de destino.

Solución: actualice el endpoint como se describe en Endpoint configuration y vuelva a intentarlo.
Se devuelve el mensaje de error "java.lang.NullPointerException..." al llamar a una OpenAPI.

Causa: su AccessKey no se pasó correctamente.

Solución: compruebe que el AccessKey se pasa correctamente durante la inicialización del cliente. System.getenv("XXX") lee el valor de XXX de las variables de entorno.

Resolución de problemas adicional: FAQ.