泛化调用
阿里云SDK支持一种通用的方式调用OpenAPI,此方式被称为泛化调用。本文将为您详细介绍如何使用泛化调用访问OpenAPI。
特点
轻量:仅需安装阿里云核心SDK,无需额外安装云产品SDK。
简单:只需构造通用的请求参数对象,然后利用通用请求客户端调用通用函数发起请求,调用结果也以通用格式返回。
更多介绍,请参见泛化调用与特化调用。
使用说明
使用泛化调用时,建议先查看OpenAPI元数据,获取OpenAPI的API风格、请求参数、资源路径等信息。
安装SDK
在Terminal中执行以下命令安装核心SDK,最新版本请参见AlibabaCloud.OpenApiClient。
dotnet add package AlibabaCloud.OpenApiClient --version 0.1.13
调用OpenAPI
初始化请求客户端
通过创建AlibabaCloud.OpenApiClient.Client
对象初始化请求客户端,并通过该Client发起OpenAPI调用。在初始化客户端时,也支持使用Credentials工具,关于Credentials工具的更多信息,请参见管理访问凭证。
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config =
new AlibabaCloud.OpenApiClient.Models.Config
{
// 必填,请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// 必填,请确保代码运行环境设置了环境变量 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);
}
// 使用Credentials工具
// public static AlibabaCloud.OpenApiClient.Client CreateClient()
// {
// // 使用AK初始化Credentials Client。
// Aliyun.Credentials.Models.Config credentialsConfig =
// new Aliyun.Credentials.Models.Config()
// {
// // 凭证类型。
// Type = "access_key",
// // 从环境变量中获取AccessKey ID值。
// AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// // 从环境变量中获取AccessKey Secret值。
// 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);
// }
配置OpenAPI信息
通过AlibabaCloud.OpenApiClient.Models.Params
配置OpenAPI的基本信息,比如OpenAPI的风格、API版本、请求方式等信息。以调用DescribeInstanceTypeFamilies接口为例:
AlibabaCloud.OpenApiClient.Models.Params params_ =
new AlibabaCloud.OpenApiClient.Models.Params
{
Action = "DescribeInstanceTypeFamilies", // API名称。
Version = "2014-05-26", // API版本号。
Protocol = "HTTPS", // 请求协议:HTTPS或HTTP,建议使用HTTPS。
Method = "POST", // 请求方法。
AuthType = "AK", // 认证类型,默认即可。当OpenAPI支持匿名请求时,您可以传入 Anonymous 发起匿名请求。
Style = "RPC", // PI风格:RPC或ROA。
Pathname = "/", // API资源路径,RPC接口默认"/",ROA接口从OpenAPI元数据中data.path获取资源路径。
ReqBodyType = "json", // 请求body的类型,支持json、formData。
BodyType = "json", // 返回数据格式,支持json。
};
配置请求参数
通过AlibabaCloud.OpenApiClient.Models.OpenApiRequest
配置请求参数,请求参数支持通过Query、Body或Stream传参,如何选择传参方式可根据元数据中的介绍选择,例如DescribeInstanceTypeFamilies
的请求参数RegionId在元数据中信息为{"name":"RegionId","in":"query",...}}
,其中"in":"query"
表示RegionId通过Query传递。
传参方式 | 描述 |
Query | 请求参数显示 |
Body | 请求参数显示 |
Stream | 在需要上传本地文件的场景,可通过Stream传递文件流。 |
// 场景一:设置查询参数(Query)
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),
};
// // 场景二:设置Body参数,reqBodyType的值为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),
// };
// // 场景三:设置Body参数,reqBodyType的值为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 };
// // 场景四:使用Stream参数传递文件流
// AlibabaCloud.OpenApiClient.Models.OpenApiRequest request =
// new AlibabaCloud.OpenApiClient.Models.OpenApiRequest
// {
// Stream = "<FILE_STREAM>",
// };
发起请求
通过AlibabaCloud.OpenApiClient.Client
调用CallApi
发起请求。同时,在请求过程中支持设置运行时参数,例如超时配置、代理配置等,更多信息请查看进阶配置。
AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
var response = client.CallApi(params_, request, runtime);
// 返回值实际为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP返回的状态码 statusCode。
Console.WriteLine(response["statusCode"]);
示例代码
示例:调用RPC风格的API
以调用ECS的DescribeInstanceTypeFamilies接口为例,展示如何使用泛化调用方式。
namespace AlibabaCloud.SDK.Sample
{
public class Sample
{
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
{
// 必填,请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// 必填,请确保代码运行环境设置了环境变量 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
{
// 接口名称
Action = "DescribeInstanceTypeFamilies",
// 接口版本
Version = "2014-05-26",
// 接口协议
Protocol = "HTTPS",
// 接口 HTTP 方法
Method = "POST",
AuthType = "AK",
Style = "RPC",
// 接口 PATH
Pathname = "/",
// 接口请求体内容格式
ReqBodyType = "json",
// 接口响应体内容格式
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),
};
// 复制代码运行请自行打印 API 的返回值
// 返回值实际为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
var response = client.CallApi(params_, request, runtime);
Console.WriteLine(response["statusCode"]);
}
}
}
示例:调用RESTful(ROA)风格的API
以调用容器服务查询集群列表信息为例,展示如何使用泛化调用。
namespace AlibabaCloud.SDK.Sample
{
public class Sample
{
public static AlibabaCloud.OpenApiClient.Client CreateClient()
{
AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
{
// 必填,请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID。
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// 必填,请确保代码运行环境设置了环境变量 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
{
// 接口名称
Action = "DescribeClustersV1",
// 接口版本
Version = "2015-12-15",
// 接口协议
Protocol = "HTTPS",
// 接口 HTTP 方法
Method = "GET",
AuthType = "AK",
Style = "ROA",
// 接口 PATH
Pathname = "/api/v1/clusters",
// 接口请求体内容格式
ReqBodyType = "json",
// 接口响应体内容格式
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();
// 复制代码运行请自行打印 API 的返回值
// 返回值实际为 Map 类型,可从 Map 中获得三类数据:响应体 body、响应头 headers、HTTP 返回的状态码 statusCode。
var response = client.CallApi(params_, request, runtime);
Console.WriteLine(response["statusCode"]);
}
}
}