全部產品
Search
文件中心

Alibaba Cloud SDK:整合SDK

更新時間:Dec 04, 2025

在調用OpenAPI時,建議採用在專案中整合SDK的方式。使用SDK可以簡化開發流程,實現功能的快速整合,同時有效降低維護成本。整合阿里雲SDK主要包括三個步驟:引入阿里雲SDK、設定訪問憑據以及使用SDK。本文將詳細介紹SDK整合的具體流程。

環境要求

  • .Net Framework >= 4.5 或 .Net Standard >= 2.0

  • C# 5.0及以上版本

引入SDK

  1. 登入SDK Center,選擇將要使用產品,例如您將要調用Short Message Service (SMS)的API。

  2. 安裝頁面,所有語言選擇C#。在快速入門頁簽中,您可以擷取Short Message Service (SMS)的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為例:

Linux和macOS系統配置方法

通過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

本文以調用Short Message Service (SMS)SendMessageToGlobe介面為例,關於SendMessageToGlobe介面的API文檔,請參見SendMessageToGlobe

1. 初始化請求用戶端

在SDK中,所有的OpenAPI均通過SDK提供的請求用戶端(Client)發起調用。因此,在調用OpenAPI之前,需要先對請求用戶端進行初始化。請求用戶端支援多種方式初始化,本樣本以使用AK進行初始化為例,更多初始化方式請參見管理訪問憑證

重要
  • 用戶端對象(如Dysmsapi Client執行個體)是安全執行緒的,能夠在多線程環境中安全使用,無需為每個線程單獨建立執行個體。

  • 在實際開發中,不建議頻繁通過 new 關鍵字建立用戶端對象,這會導致資源浪費和效能下降。推薦採用單例模式封裝用戶端,確保在整個應用程式生命週期中針對相同的訪問憑據和Endpoint僅初始化一個用戶端對象。

 public static AlibabaCloud.SDK.Dysmsapi20180501.Client CreateClient(){
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
            };
            config.Endpoint = "dysmsapi.aliyuncs.com";
            return new AlibabaCloud.SDK.Dysmsapi20180501.Client(config);
        }

2. 建立請求對象

在調用OpenAPI進行參數傳遞時,需使用SDK提供的請求對象來實現參數的傳遞。OpenAPI請求對象的命名方式為:<OpenAPI名稱>Request,例如SendMessageToGlobe該介面的請求對象為SendMessageToGlobeRequest。有關請求參數的詳細資料,請查閱相應的API文檔,本樣本API文檔請參見SendMessageToGlobe

說明

若OpenAPI不支援要求參數,則無需建立請求對象。例如,在調用DescribeCdnSubList時,該介面不支援要求參數。

// Create request object and set required input parameters
AlibabaCloud.SDK.Dysmsapi20180501.Models.SendMessageToGlobeRequest sendMessageToGlobeRequest = new AlibabaCloud.SDK.Dysmsapi20180501.Models.SendMessageToGlobeRequest
            {   
                // Please replace with the actual recipient number.
                To = "<PHONE_NUMBER>",
                // Please replace with the actual SMS content.
                Message = "<YOUR_MESSAGE>",
            };

3. 發起請求

通過請求用戶端調用OpenAPI時,建議使用的函數名稱為<OpenAPI名稱>WithOptions。該函數包含兩個參數:一個為請求對象,另一個為運行時參數。請求對象為上一步建立的請求對象;運行時參數用於配置請求的行為,例如逾時設定、代理配置等。更多資訊,請參見進階配置

說明

若OpenAPI不支援要求參數,則在發起請求時無需傳遞請求對象。例如,在調用DescribeCdnSubList時,函數只需傳入運行時參數。

OpenAPI返回對象的命名方式為:<OpenAPI名稱>Response,例如SendMessageToGlobe該介面的返回對象為SendMessageToGlobeResponse

 // Create runtime parameters.
 AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
 AlibabaCloud.SDK.Dysmsapi20180501.Client client = CreateClient();
 // Send a request.
 AlibabaCloud.SDK.Dysmsapi20180501.Models.SendMessageToGlobeResponse response = client.SendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);

4. 異常處理

V2.0 .NET SDK將異常進行了細緻的分類,主要劃分為TeaUnretryableException和TeaException。

  • TeaUnretryableException:主要是因為網路問題造成,一般是網路問題達到最大重試次數後拋出。

  • TeaException:主要以業務報錯為主的異常。

更多關於異常處理的介紹,請參見異常處理

重要

建議採取合理的措施來處理異常,比如合理地傳播異常、記錄日誌、嘗試恢複等,以確保系統的健壯性和穩定性。

點擊查看完整程式碼範例

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.Dysmsapi20180501.Client CreateClient()
        {
    
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
            };
          
            config.Endpoint = "dysmsapi.aliyuncs.com";
            return new AlibabaCloud.SDK.Dysmsapi20180501.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dysmsapi20180501.Client client = CreateClient();
            // Create request object and set required input parameters
            AlibabaCloud.SDK.Dysmsapi20180501.Models.SendMessageToGlobeRequest sendMessageToGlobeRequest = new AlibabaCloud.SDK.Dysmsapi20180501.Models.SendMessageToGlobeRequest
            {   
                // Please replace with the actual recipient number.
                To = "<PHONE_NUMBER>",
                // Please replace with the actual SMS content.
                Message = "<YOUR_MESSAGE>",
            };
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            try
            {
                // Copy the code to run, please print the return value of the API by yourself.
                client.SendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
            }
            catch (TeaException error)
            {
                // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
                // print error message
                Console.WriteLine(error.Message);
                // Please click on the link below for diagnosis.
                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 }
                });
                // Only a printing example. Please be careful about exception handling and do not ignore exceptions directly in engineering projects.
                // print error message
                Console.WriteLine(error.Message);
                // Please click on the link below for diagnosis.
                Console.WriteLine(error.Data["Recommend"]);
                AlibabaCloud.TeaUtil.Common.AssertAsString(error.Message);
            }
        }


    }
}

特殊情境:檔案上傳Advance介面配置

在使用Image Search、視覺智能開放平台等雲產品處理本地圖片或上傳圖片時,官方文檔中提供的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使用者授權

    例如,當您在調用SendMessageToGlobe時提示“You are not authorized to perform this operation”,您可以建立如下所示的自訂權限原則,並為該RAM使用者授予相應的許可權。

    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "dysms:SendMessageToGlobe",
          "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使用過程中的報錯問題解決方案,請參見常見問題