快速使用新版SDK初始化客户端进行OpenAPI请求（.NET SDK）_阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

在调用OpenAPI时，建议采用在项目中集成SDK的方式。使用SDK可以简化开发流程，实现功能的快速集成，同时有效降低维护成本。集成阿里云SDK主要包括三个步骤：引入阿里云SDK、设置访问凭据以及编写调用代码。本文将详细介绍SDK集成的具体流程。

环境要求

.Net Framework >= 4.5 或 .Net Core >= 2.0

1. 引入SDK

登录SDK中心，选择将要使用产品，例如您将要调用短信服务 SMS（Short Message Service）的API。
在安装页面，SDK 代系选择V2.0，所有语言选择C#。在快速入门页签中，您可以获取短信服务 SMS（Short Message Service）的SDK安装方式。

说明

您也可以访问GitHub查看源码及相关安装指引。V2.0 SDK GitHub地址：GitHub - aliyun/alibabacloud-csharp-sdk。

2. 设置访问凭据

调用阿里云OpenAPI通常需要设置访问凭据，常见凭据类型为AccessKey（简称：AK）和临时安全令牌STS Token。为防止凭据泄露，常用的方案是将其存储到环境变量中，更多安全方案请参见访问凭据的安全使用方案。本文以设置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET为例：

Linux和macOS系统配置方法

Windows系统配置方法

通过export命令配置环境变量

重要

使用export命令配置的临时环境变量仅当前会话有效，当会话退出之后所设置的环境变量将会丢失。若需长期保留环境变量，可将export命令配置到对应操作系统的启动配置文件中。

配置AccessKey ID并按回车。

# 将<ACCESS_KEY_ID>替换为您自己的AccessKey ID。
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

配置AccessKey Secret并回车。

# 将<ACCESS_KEY_SECRET>替换为您自己的AccessKey Secret。
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

验证是否配置成功。
执行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令，如果返回正确的AccessKey ID，则说明配置成功。

通过图形用户界面GUI

通过命令行提示符CMD

通过Windows PowerShell

操作步骤
以下为Windows 10中通过图形用户界面设置环境变量的步骤。
在桌面右键单击此电脑，选择属性>高级系统设置>环境变量>系统变量/用户变量>新建，完成以下配置：
变量
示例值
AccessKey ID
变量名：ALIBABA_CLOUD_ACCESS_KEY_ID
变量值：LTAI****************
AccessKey Secret
变量名：ALIBABA_CLOUD_ACCESS_KEY_SECRET
变量值：yourAccessKeySecret
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。

操作步骤
以管理员身份打开命令提示符，并使用以下命令在系统中新增环境变量。
```
setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M
```
其中/M表示系统级环境变量，设置用户级环境变量时可以不携带该参数。
测试设置是否成功
单击开始（或快捷键：Win+R）> 运行（输入 cmd）> 确定（或按 Enter 键），打开命令提示符，执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey，则说明配置成功。

在PowerShell中，设置新的环境变量（对所有新会话都有效）：

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

为所有用户设置环境变量（需要管理员权限）：

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

设置临时的环境变量（仅当前会话有效）：

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

在PowerShell中，执行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey，则说明配置成功。

3. 编写调用代码

本文以调用短信服务 SMS（Short Message Service）的SendSms接口为例，关于SendSms接口的API文档，请参见SendSms。

3.1 初始化请求客户端

在SDK中，所有的OpenAPI均通过SDK提供的请求客户端（Client）发起调用。因此，在调用OpenAPI之前，需要先对请求客户端进行初始化。请求客户端支持多种方式初始化，本示例以使用AK进行初始化为例，更多初始化方式请参见管理访问凭证。

public static AlibabaCloud.SDK.Dysmsapi20170525.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 = "dysmsapi.aliyuncs.com";
            return new AlibabaCloud.SDK.Dysmsapi20170525.Client(config);
        }

说明

当调用Advance接口传递文件流时，在初始化请求客户端时必须使用regionId代替endpoint。以初始化视觉智能开放平台-人脸人体请求客户端为例：

public static AlibabaCloud.SDK.Facebody20191230.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.RegionId = "cn-shanghai";
    return new AlibabaCloud.SDK.Facebody20191230.Client(config);
}

3.2 创建请求对象

在调用OpenAPI进行参数传递时，需使用SDK提供的请求对象来实现参数的传递。OpenAPI请求对象的命名方式为：<OpenAPI名称>Request，例如SendSms该接口的请求对象为SendSmsRequest。有关请求参数的详细信息，请查阅相应的API文档，本示例API文档请参见SendSms。

说明

若OpenAPI不支持请求参数，则无需创建请求对象。例如，在调用DescribeCdnSubList时，该接口不支持请求参数。

// 创建请求对象并设置入参
AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsRequest sendSmsRequest = new AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsRequest
{
    // <PHONE_NUMBER>替换为接收短信的手机号码
    PhoneNumbers = "<PHONE_NUMBER>",
    // <SIGN_NAME>替换为短信签名名称
    SignName = "<SIGN_NAME>",
    // <TEMPLATE_CODE>替换为短信模板Code
    TemplateCode = "<TEMPLATE_CODE>",
    // <TEMPLATE_PARAM>替换为短信模板变量对应的实际值。支持传入多个参数。
    TemplateParam = "<TEMPLATE_PARAM>"
};

说明

针对部分需要上传文件的OpenAPI，可以通过创建<OpenAPI名称>AdvanceRequest请求对象传递文件流。以视觉智能开放平台-人脸人体的DetectBodyCount接口为例：

AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountAdvanceRequest detectBodyCountAdvanceRequest =
                new AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountAdvanceRequest
                {
                    ImageURLObject = File.OpenRead(@"<FILE_PATH>"), // <FILE_PATH>需替换文件路径
                };

3.3 发起请求

通过请求客户端调用OpenAPI时，建议使用的函数名称为<OpenAPI名称>WithOptions。该函数包含两个参数：一个为请求对象，另一个为运行时参数。请求对象为上一步创建的请求对象；运行时参数用于配置请求的行为，例如超时设置、代理配置等。更多信息，请参见进阶配置。

说明

若OpenAPI不支持请求参数，则在发起请求时无需传递请求对象。例如，在调用DescribeCdnSubList时，函数只需传入运行时参数。

OpenAPI返回对象的命名方式为：<OpenAPI名称>Response，例如SendSms该接口的返回对象为SendSmsResponse。

 // 创建运行时配置
 AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
 // 发起请求        
 AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsResponse sendSmsResponse = client.SendSmsWithOptions(sendSmsRequest, runtime);

说明

针对部分需要本地上传文件的OpenAPI，需调用函数<OpenAPI名称>Advance发起请求。以调用视觉智能开放平台-人脸人体的DetectBodyCount接口为例：

// 运行时配置
AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
// 发起请求
AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountResponse response = client.DetectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
Console.WriteLine(AlibabaCloud.TeaUtil.Common.ToJSONString(response));

3.4 异常处理

V2.0 .NET SDK将异常进行了细致的分类，主要划分为TeaUnretryableException和TeaException。

TeaUnretryableException：主要是因为网络问题造成，一般是网络问题达到最大重试次数后抛出。
TeaException：主要以业务报错为主的异常。

更多关于异常处理的介绍，请参见异常处理。

重要

建议采取合理的措施来处理异常，比如合理地传播异常、记录日志、尝试恢复等，以确保系统的健壮性和稳定性。

完整代码示例

通用接口调用示例

上传文件（Advance）接口调用示例

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static AlibabaCloud.SDK.Dysmsapi20170525.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 = "dysmsapi.aliyuncs.com";
            return new AlibabaCloud.SDK.Dysmsapi20170525.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dysmsapi20170525.Client client = CreateClient();
            // 创建请求对象并设置入参
            AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsRequest sendSmsRequest = new AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsRequest
                {
                    // <PHONE_NUMBER>替换为接收短信的手机号码
                    PhoneNumbers = "<PHONE_NUMBER>",
                    // <SIGN_NAME>替换为短信签名名称
                    SignName = "<SIGN_NAME>",
                    // <TEMPLATE_CODE>替换为短信模板Code
                    TemplateCode = "<TEMPLATE_CODE>",
                    // <TEMPLATE_PARAM>替换为短信模板变量对应的实际值。支持传入多个参数。
                    TemplateParam = "<TEMPLATE_PARAM>",
                };
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            try
            {
                // 发起请求
                AlibabaCloud.SDK.Dysmsapi20170525.Models.SendSmsResponse sendSmsResponse = client.SendSmsWithOptions(sendSmsRequest, runtime);
                Console.WriteLine(JsonConvert.SerializeObject(sendSmsResponse.Body, Formatting.None));
            }
            catch (TeaException error)
            {
                // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
                // 错误 message
                Console.WriteLine(error.Message);
                // 诊断地址
                Console.WriteLine(error.Data["Recommend"]);
                AlibabaCloud.TeaUtil.Common.AssertAsString(error.Message);
            }
            catch (Exception _error)
            {
                TeaException error = new TeaException(
                    new Dictionary<string, object> { { "message", _error.Message } }
                );
                // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
                // 错误 message
                Console.WriteLine(error.Message);
                // 诊断地址
                Console.WriteLine(error.Data["Recommend"]);
                AlibabaCloud.TeaUtil.Common.AssertAsString(error.Message);
            }
        }
    }
}

// dotnet add package AlibabaCloud.SDK.Facebody20191230 --version 4.1.2

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static AlibabaCloud.SDK.Facebody20191230.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.RegionId = "cn-shanghai";
            return new AlibabaCloud.SDK.Facebody20191230.Client(config);
        }

        public static void Main(string[] args)
        {
            try
            {
                AlibabaCloud.SDK.Facebody20191230.Client client = CreateClient();
                // <FILE_PATH>需替换文件路径
                using (FileStream fileStream = File.OpenRead(@"<FILE_PATH>"))
                {
                    AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountAdvanceRequest detectBodyCountAdvanceRequest =
                        new AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountAdvanceRequest
                        {
                            ImageURLObject = fileStream,
                        };
                    AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
                    AlibabaCloud.SDK.Facebody20191230.Models.DetectBodyCountResponse response =
                        client.DetectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
                    Console.WriteLine(AlibabaCloud.TeaUtil.Common.ToJSONString(response));
                }
            }
            catch (TeaException error)
            {
                // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
                Console.WriteLine(error.Message);
                AlibabaCloud.TeaUtil.Common.AssertAsString(error.Message);
            }
            catch (Exception _error)
            {
                TeaException error = new TeaException(
                    new Dictionary<string, object> { { "message", _error.Message } }
                );
                // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
                Console.WriteLine(error.Message);
                AlibabaCloud.TeaUtil.Common.AssertAsString(error.Message);
            }
        }
    }
}

常见问题

调用OpenAPI时报错，提示“You are not authorized to perform this operation”。
问题原因：您所使用的AccessKey对应的RAM用户没有权限调用该API。
解决方法：请为该RAM用户授予相应OpenAPI权限。关于如何为RAM用户进行授权，请参见为RAM用户授权。
例如，当您在调用SendSms时提示“You are not authorized to perform this operation”，您可以创建如下所示的自定义权限策略，并为该RAM用户授予相应的权限。
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "dysms:SendSms",
      "Resource": "*"
    }
  ]
}
```
调用OpenAPI时报错，提示 "System.UnretryableException: One or more errors occurred. "。
问题原因：您所调用的OpenAPI不支持在初始化请求客户端时填写的Endpoint。
解决方法：请查看Endpoint配置，修改为正确的Endpoint后重新调用OpenAPI。
调用OpenAPI时报错，提示ErrorCode":"InvalidAccessKeyId.NotFound","ErrorMessage":"Specified access key is not found.”。
问题原因：您的AccessKey未正确传递。
解决方法：在初始化请求客户端时，检查是否正确传递AccessKey。请注意Environment.GetEnvironmentVariable("XXX")表示从环境变量中获取XXX的值。

更多SDK使用过程中的报错问题解决方案，请参见常见问题。

变量	示例值
AccessKey ID	变量名：ALIBABA_CLOUD_ACCESS_KEY_ID 变量值：LTAI****************
AccessKey Secret	变量名：ALIBABA_CLOUD_ACCESS_KEY_SECRET 变量值：yourAccessKeySecret