Alibaba Cloud SDK for Java V2.0 supports generic API calls. This topic describes how to make generic calls by using Alibaba Cloud SDK for Java V2.0.
Characteristic
Lightweight: You can use Alibaba Cloud SDK V2.0 for .Net to call API operations by installing only the core library of Alibaba Cloud SDK, without the need to install the SDK of each service.
Easy to use: You only need to create common request parameters and use a common client to initiate requests. The responses are returned in common formats.
For more information, see Generic calls and specialized calls.
Usage notes
Before you make a generic call, we recommend that you view the metadata of the API operation to obtain the API style, request parameters, and URL.
Install the SDK
Run the following command in the terminal to install the core library of Alibaba Cloud SDK V2.0 for .NET. For more information about the latest version of the core library, see AlibabaCloud.OpenApiClient.
dotnet add package AlibabaCloud.OpenApiClient --version 0.1.13Call an API operation
Initialize a request client
Create the AlibabaCloud.OpenApiClient.Client object to initialize a request client, and use the client to call the API operation. When you initialize a client, you can also use the Credentials tool. For more information about the Credentials tool, see Manage access credentials.
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config =
new AlibabaCloud.OpenApiClient.Models.Config
{
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_ID.
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_SECRET.
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
};
config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
return new AlibabaCloud.OpenApiClient.Client(config);
}
// Use the Credentials tool.
// public static AlibabaCloud.OpenApiClient.Client CreateClient()
// {
// // Use an AccessKey pair to initialize the Credentials client.
// Aliyun.Credentials.Models.Config credentialsConfig =
// new Aliyun.Credentials.Models.Config()
// {
// // The credential type.
// Type = "access_key",
// // Obtain the AccessKey ID from the environment variable.
// AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// // Obtain the AccessKey secret from the environment variable.
// AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
// };
// Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);
// AlibabaCloud.OpenApiClient.Models.Config config =
// new AlibabaCloud.OpenApiClient.Models.Config
// {
// Credential = credentialClient,
// Endpoint = "ecs-cn-hangzhou.aliyuncs.com",
// };
// return new AlibabaCloud.OpenApiClient.Client(config);
// }Configure the information about the API operation
Use AlibabaCloud.OpenApiClient.Models.Params to configure the basic information about the API operation, such as the API style, API version, and request method. In the following example, the DescribeInstanceTypeFamilies operation is called.
AlibabaCloud.OpenApiClient.Models.Params params_ =
new AlibabaCloud.OpenApiClient.Models.Params
{
Action = "DescribeInstanceTypeFamilies", // The API operation.
Version = "2014-05-26", // The version number of the API operation.
Protocol = "HTTPS", // The request protocol. Valid values: HTTP and HTTPS. We recommend that you use HTTPS.
Method = "POST", // The request method.
AuthType = "AK", // The authentication type. Use the default type. If the API operation supports anonymous requests, you can specify the Anonymous parameter to initiate an anonymous request.
Style = "RPC", // The API style, such as remote procedure call (RPC) and resource-oriented architecture (ROA).
Pathname = "/", // The URL of the API 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.
ReqBodyType = "json", // The type of request body. Valid values: json and formData.
BodyType = "json", // The response format. Valid value: json.
};Configure request parameters
Use AlibabaCloud.OpenApiClient.Models.OpenApiRequest to configure the request parameters. You can pass the request parameters in a query string, a body, or a stream. Select a method to pass request parameters based on the metadata of the API operation. For example, the RegionId request parameter of the DescribeInstanceTypeFamilies API operation is defined as {"name":"RegionId","in":"query",...}} in the metadata. "in":"query" indicates that the RegionId parameter is passed in a query string.
Method | Description |
Query | If the metadata defines |
Body | If the metadata defines |
Stream | If you need to upload files, you can pass file streams by configuring the Stream parameter. |
// Method 1: Configure a query string.
Dictionary<string, object> queries = new Dictionary<string, object>() { };
queries["RegionId"] = "cn-hangzhou";
AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
{
Query = AlibabaCloud.OpenApiUtil.Client.Query(queries),
};
// // Method 2: Configure the body and set reqBodyType to json.
// Dictionary<string, object> body = new Dictionary<string, object>()
// {
// { "param1", "value1" },
// { "param2", "value2" },
// };
// AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
// new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
// {
// Body = AlibabaCloud.OpenApiUtil.Client.Query(body),
// };
// // Method 3: Configure the body and set reqBodyType to formData.
// Dictionary<string, object> formData = new Dictionary<string, object>()
// {
// { "param1", "value1" },
// { "param2", "value2" },
// };
// AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
// new AlibabaCloud.OpenApiClient.Models.OpenApiRequest { Body = formData };
// // Method 4: Configure the Stream parameter to pass file streams
// AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
// new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
// {
// Stream = "<FILE_STREAM>",
// };Initiate a request
Use AlibabaCloud.OpenApiClient.Client to to initiate a request by calling the CallApi method. In addition, configure the runtime parameters, such as timeout and proxy settings. For more information, see Advanced configuration.
AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
var response = client.CallApi(params_, request, runtime);
// The response is of the MAP type, which contains the response body, response headers, and HTTP status code.
Console.WriteLine(response["statusCode"]);Sample code
Example: Call an RPC-style API operation
In this example, the DescribeInstanceTypeFamilies operation of Elastic Compute Service (ECS) is called to show how to make a generic call of an operation.
namespace AlibabaCloud.SDK.Sample
{
public class Sample
{
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
{
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_ID.
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_SECRET.
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
};
config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
return new AlibabaCloud.OpenApiClient.Client(config);
}
public static AlibabaCloud.OpenApiClient.Models.Params CreateApiInfo()
{
AlibabaCloud.OpenApiClient.Models.Params params_ = new AlibabaCloud.OpenApiClient.Models.Params
{
// The name of the API operation.
Action = "DescribeInstanceTypeFamilies",
// The version number of the API operation.
Version = "2014-05-26",
// The protocol of the API operation.
Protocol = "HTTPS",
// The HTTP method of the API operation.
Method = "POST",
AuthType = "AK",
Style = "RPC",
// The path of the API operation.
Pathname = "/",
// The format of the request body.
ReqBodyType = "json",
// The format of the response body.
BodyType = "json",
};
return params_;
}
public static void Main(string[] args)
{
AlibabaCloud.OpenApiClient.Client client = CreateClient();
AlibabaCloud.OpenApiClient.Models.Params params_ = CreateApiInfo();
// query params
Dictionary<string, object> queries = new Dictionary<string, object>(){};
queries["RegionId"] = "cn-hangzhou";
// runtime options
AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
AlibabaCloud.OpenApiClient.Models.OpenApiRequest request = new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
{
Query = AlibabaCloud.OpenApiUtil.Client.Query(queries),
};
// If you copy and run the sample code, write your code to display the response of the operation.
// The response is of the MAP type, which contains the response body, response headers, and HTTP status code.
var response = client.CallApi(params_, request, runtime);
Console.WriteLine(response["statusCode"]);
}
}
}Example: Call a RESTful-style (ROA-style) API operation
In this example, the DescribeClustersV1 operation of Container Service for Kubernetes (ACK) is called to show how to make a generic call of an operation.
namespace AlibabaCloud.SDK.Sample
{
public class Sample
{
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
{
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_ID.
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// Required. Make sure that the following environment variable is set in the code runtime environment: ALIBABA_CLOUD_ACCESS_KEY_SECRET.
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
};
config.Endpoint = "cs.cn-hangzhou.aliyuncs.com";
return new AlibabaCloud.OpenApiClient.Client(config);
}
public static AlibabaCloud.OpenApiClient.Models.Params CreateApiInfo()
{
AlibabaCloud.OpenApiClient.Models.Params params_ = new AlibabaCloud.OpenApiClient.Models.Params
{
// The name of the API operation.
Action = "DescribeClustersV1",
// The version number of the API operation.
Version = "2015-12-15",
// The protocol of the API operation.
Protocol = "HTTPS",
// The HTTP method of the API operation.
Method = "GET",
AuthType = "AK",
Style = "ROA",
// The path of the API operation.
Pathname = "/api/v1/clusters",
// The format of the request body.
ReqBodyType = "json",
// The format of the response body.
BodyType = "json",
};
return params_;
}
public static void Main(string[] args)
{
AlibabaCloud.OpenApiClient.Client client = CreateClient();
AlibabaCloud.OpenApiClient.Models.Params params_ = CreateApiInfo();
// runtime options
AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
AlibabaCloud.OpenApiClient.Models.OpenApiRequest request = new AlibabaCloud.OpenApiClient.Models.OpenApiRequest();
// Write your code to display the response of the operation if necessary.
// The response is of the MAP type, which contains the response body, response headers, and HTTP status code.
var response = client.CallApi(params_, request, runtime);
Console.WriteLine(response["statusCode"]);
}
}
}