Appels d'API génériques avec Alibaba Cloud SDK for Java - Alibaba Cloud SDK

Alibaba Cloud SDK for Java V2.0 prend en charge les appels d'API génériques. Cette fonctionnalité permet d'invoquer n'importe quelle opération OpenAPI sans installer de SDK spécifiques aux services.

Avantages

Légèreté : seule la bibliothèque principale du SDK est requise. Aucun SDK spécifique à un service n'est nécessaire.

Simplicité d'utilisation : construisez des paramètres de requête communs, appelez un client générique et recevez des réponses dans un format standard.

Pour plus d'informations, consultez Appels génériques et appels spécialisés.

Prérequis

Avant d'effectuer un appel générique, consultez les métadonnées de l'API pour obtenir son style, ses paramètres et son URL. Pour plus d'informations, reportez-vous à Métadonnées OpenAPI.

Installer la bibliothèque principale du SDK

Ajoutez la dépendance suivante à votre fichier pom.xml. Consultez le référentiel Maven pour obtenir la version la plus récente.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea-openapi</artifactId>
    <version>0.3.10</version>
</dependency>

Appeler une opération d'API

Initialiser un client de requête

Créez un objet com.aliyun.teaopenapi.Client pour initialiser un client de requête. Vous pouvez également utiliser l'outil Credentials pour l'authentification. Pour plus d'informations sur cet outil, consultez Gérer les identifiants.

Remarque

Le ramasse-miettes collecte automatiquement l'objet client. Il est inutile de le détruire manuellement.

        // 1. Initialize a request client
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Specify the endpoint of ASAPI.
        config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        // Optional. Configure a proxy by using the Config object when you initialize the client. 
        // Specify HTTPS as the protocol when you initialize the client.
        // config.setProtocol("HTTPS");
        // Specify the region ID.
        // config.setRegionId("<regionId>");
        // Configure a proxy when you initialize the client.
        // config.setHttpProxy("http://127.0.0.1:9898");
        // config.setHttpsProxy("http://user:password@127.0.0.1:8989");
        // config.setNoProxy("127.0.0.1,localhost");
        // Configure timeout periods when you initialize the SDK client.
        // The default timeout period for connection requests is 5,000 milliseconds. The value is calculated by using the formula: 5 × 1,000 = 5,000.
        // config.setConnectTimeout(5000);
        // The default timeout period for read requests is 10,000 milliseconds.
        // config.setReadTimeout(10000);
        com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);

//        //  Use the Credentials tool
//        com.aliyun.credentials.models.Config credentialConfig = new com.aliyun.credentials.models.Config();
//        credentialConfig.setType("access_key");
//        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
//        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
//        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
//        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//                .setCredential(credentialClient)
//                .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
//        com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);

Configurer les détails de l'opération d'API

Utilisez com.aliyun.teaopenapi.models.Params pour configurer le style de l'API, sa version et la méthode de requête. L'exemple suivant appelle DescribeInstanceTypeFamilies.

        com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
                .setStyle("RPC")  // The API style, such as remote procedure call (RPC) or resource-oriented architecture (ROA). 
                .setVersion("2014-05-26") // The API version. 
                .setMethod("POST") // The request method. 
                .setAction("DescribeInstanceTypeFamilies")  // The name of the API operation. 
                .setPathname("/") // The URL of the operation. The default path of an RPC-style operation is /. You can obtain the URL of an ROA-style operation from the data.path parameter in the API metadata. 
                .setProtocol("HTTPS") // The request protocol, such as HTTPS or HTTP. We recommend that you use HTTPS. 
                .setAuthType("AK") // The authentication type. Use the default type. If the operation supports anonymous requests, you can specify the Anonymous parameter to initiate an anonymous request. 
                .setReqBodyType("json") // The type of request body. Valid values: byte, json, and formData. 
                .setBodyType("json"); // The response format. JSON is supported.

Configurer les paramètres de la requête

Utilisez com.aliyun.teaopenapi.models.OpenApiRequest pour transmettre les paramètres de requête via une chaîne de requête, un corps ou un flux. Choisissez la méthode appropriée selon les métadonnées de l'API. Par exemple, RegionId dans DescribeInstanceTypeFamilies est défini comme {"name":"RegionId","in":"query",...}}, où "in":"query" indique qu'il est transmis en tant que paramètre de requête.

Mode de transmission du paramètre

Scénario

setQuery

Les métadonnées définissent "in":"query". Transmettez les paramètres dans setQuery.

setBody

Les métadonnées définissent "in":"body'' ou "in": "formData". Transmettez les paramètres dans setBody et définissez reqBodyType pour correspondre au format du corps.

setStream

Utilisez setStream pour transmettre des flux de fichiers lors des téléchargements.

        // Scenario 1: Configure a query string.
        java.util.Map<String, Object> queries = new java.util.HashMap<>();
        queries.put("RegionId", "cn-hangzhou");
        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
                .setQuery(com.aliyun.openapiutil.Client.query(queries));

//        // Method 2: Configure the body and set reqBodyType to json.
//        java.util.Map<String, Object> body = new java.util.HashMap<>();
//        body.put("param1", "value1");
//        body.put("param2", "value2");
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setBody(com.aliyun.openapiutil.Client.query(body));

//        // Method 3: Configure the body and set reqBodyType to formData.
//        java.util.Map<String, Object> formData = new java.util.HashMap<>();
//        formData.put("param1", "value1");
//        formData.put("param2", "value2");
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setBody(formData);

//        // Method 4: Configure the Stream parameter to pass file streams
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setStream("<FILE_STREAM>");  // Replace <FILE_STREAM> with the actual file stream.

Envoyer la requête

Appelez callApi sur l'objet com.aliyun.teaopenapi.Client. Vous pouvez spécifier des paramètres d'exécution tels que les délais d'attente et les proxys. Pour plus d'informations, consultez Paramètres avancés.

        // Configure runtime options.
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// Disable SSL certificate authentication.
//        runtime.ignoreSSL = true;
// Enable the automatic retry mechanism.
//        runtime.autoretry = true;
// Specify the number of automatic retries.
//        runtime.maxAttempts = 3;
// Specify the connection timeout period.
//        runtime.connectTimeout = 5000;
// Specify the timeout period of read requests.
//       runtime.readTimeout = 10000;
        // The response is of the MAP type, which contains the response body, response headers, and HTTP status code. 
        java.util.Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new com.google.gson.Gson().toJson(response));

Exemples

Exemple : appeler une opération d'API de style RPC

L'exemple suivant effectue un appel générique à l'opération ECS DescribeInstanceTypeFamilies.

import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

import java.util.HashMap;
import java.util.Map;

import static com.aliyun.openapiutil.Client.query;

public class Sample {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setEndpoint("ecs-cn-hangzhou.aliyuncs.com");
        Client client = new Client(config);
        Params params = new Params()
                .setStyle("RPC")  // The API style.
                .setVersion("2014-05-26") // The version number of the operation.
                .setMethod("POST") // The HTTP method of the operation.
                .setAction("DescribeInstanceTypeFamilies")  // The name of the API operation.
                .setPathname("/") 
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // Specify the query parameters.
        Map<String, Object> queries = new HashMap<>();
        queries.put("RegionId", "cn-hangzhou");
        // Create a runtime configuration object.
        RuntimeOptions runtime = new RuntimeOptions();
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        // The response is of the MAP type, which contains the response body, response headers, and HTTP status code. 
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}

Exemple : appeler une opération d'API de style RESTful (ROA)

L'exemple ci-dessous effectue un appel générique à l'opération ACK DescribeClustersV1.

import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

import java.util.HashMap;
import java.util.Map;

import static com.aliyun.openapiutil.Client.query;

public class Test3 {
    public static void main(String[] args_) throws Exception {
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setEndpoint("cs.cn-hangzhou.aliyuncs.com");
        Client client = new Client(config);
        Params params = new Params()
                .setStyle("ROA") // The API style.
                .setVersion("2015-12-15") // The API version.
                .setAction("DescribeClustersV1") // The operation that you want to call.
                .setPathname("/api/v1/clusters") // The API URI.
                .setMethod("GET") // The request method.
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // Specify the query parameters.
        Map<String, Object> queries = new HashMap<>();
        queries.put("name", "cluster-demo");
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        RuntimeOptions runtime = new RuntimeOptions();
        // The response is of the MAP type, which contains the response body, response headers, and HTTP status code. 
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}