集成SDK

更新时间:

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

环境要求

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

引入SDK

  1. 登录SDK中心,选择将要使用产品,例如您将要调用短信服务 SMS(Short Message Service)API。

  2. 安装页面SDK 代系选择V2.0所有语言选择C#。在快速入门页签中,您可以获取短信服务 SMS(Short Message Service)SDK安装方式。image

说明

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

设置访问凭据

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

LinuxmacOS系统配置方法

通过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,则说明配置成功。

Windows系统配置方法

通过图形用户界面GUI

  • 操作步骤

    以下为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,则说明配置成功。

通过命令行提示符CMD

  • 操作步骤

    以管理员身份打开命令提示符,并使用以下命令在系统中新增环境变量。

    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,则说明配置成功。

通过Windows PowerShell

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_IDGet-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey,则说明配置成功。

使用SDK

本文以调用短信服务 SMS(Short Message Service)SendSms接口为例,关于SendSms接口的API文档,请参见SendSms

1. 初始化请求客户端

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

重要
  • 客户端对象(如Dysmsapi Client实例)是线程安全的,能够在多线程环境中安全使用,无需为每个线程单独创建实例。

  • 在实际开发中,不建议频繁通过 new 关键字创建客户端对象,这会导致资源浪费和性能下降。推荐采用单例模式封装客户端,确保在整个应用程序生命周期中针对相同的访问凭据和Endpoint仅初始化一个客户端对象。

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

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

3. 发起请求

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

说明

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

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

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

4. 异常处理

V2.0 .NET SDK将异常进行了细致的分类,主要划分为TeaUnretryableExceptionTeaException。

  • TeaUnretryableException:主要是因为网络问题造成,一般是网络问题达到最大重试次数后抛出。

  • TeaException:主要以业务报错为主的异常。

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

重要

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

点击查看完整代码示例

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

特殊场景:文件上传Advance接口配置

在使用图像搜索、视觉智能开放平台等云产品处理本地图片或上传图片时,官方文档中提供的OpenAPI接口不支持直接上传文件。若需上传文件,可以使用云产品提供的Advance接口,该接口支持传递文件流对象。其底层实现机制为:云产品会将上传的文件临时存储于阿里云OSS上,默认存储地域为cn-shanghai,并通过读取该OSS中的临时文件来实现相关功能。以阿里云提供的视觉智能开放平台-人脸人体的DetectBodyCount接口为例:

说明

存储在阿里云OSS的临时文件会被定时清理。

  1. 初始化请求客户端

    请注意需同时设置RegionId和云产品的Endpoint。其中,RegionId表示临时文件在OSS中所存储的地域。如果未设置RegionId,可能会由于云产品与OSS所在地域不同,导致在调用OpenAPI时出现超时等问题。

    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";
        config.Endpoint = "facebody.cn-shanghai.aliyuncs.com";
        return new AlibabaCloud.SDK.Facebody20191230.Client(config);
    }
  2. 创建请求对象

    通过创建<OpenAPI名称>AdvanceRequest请求对象传递文件流,参数名固定为ImageURLObject

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

    调用函数<OpenAPI名称>Advance发起请求。

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

点击查看完整代码示例

// 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";
            config.Endpoint = "facebody.cn-shanghai.aliyuncs.com";
            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使用过程中的报错问题解决方案,请参见常见问题