本文由簡體中文內容自動轉碼而成。阿里雲不保證此自動轉碼的準確性、完整性及時效性。本文内容請以簡體中文版本為準。

整合SDK

更新時間:2025-03-27 19:28

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

環境要求

Node.js >= 8.x

1. 引入SDK

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

  2. 安裝頁面,所有語言選擇TypeScript。然後在快速入門頁簽中,您可以擷取Short Message Service (SMS)的SDK安裝方式。image

2. 設定訪問憑據

調用阿里雲OpenAPI通常需要設定訪問憑據,常見憑據類型為AccessKey(簡稱:AK)臨時安全性權杖STS Token。為防止憑據泄露,常用的方案是將其儲存到環境變數中,更多安全方案請參見訪問憑據的安全使用方式情節。本文以設定環境變數ALIBABA_CLOUD_ACCESS_KEY_IDALIBABA_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

    • 變數值:yourAccessKeyID

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

3. 編寫調用代碼

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

3.1 初始化請求用戶端

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

TypeScript樣本
JavaScript樣本
import Dysmsapi20180501, * as $Dysmsapi20180501 from '@alicloud/dysmsapi20180501';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {

  static createClient(): Dysmsapi20180501 {
    let config = new $OpenApi.Config({
      // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    // See https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20180501(config);
  }
}
const Dysmsapi20180501 = require('@alicloud/dysmsapi20180501');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Tea = require('@alicloud/tea-typescript');

class Client {

  static createClient() {
    let config = new OpenApi.Config({
      // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID is set.
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // Required, please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_SECRET is set.
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    // See https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20180501.default(config);
  }
}

3.2 建立請求對象

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

說明

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

TypeScript樣本
JavaScript樣本
 // Create request object and set required input parameters
 let sendMessageToGlobeRequest = new $Dysmsapi20180501.SendMessageToGlobeRequest({
      // Please replace with the actual recipient number.
      to: "<YOUR_VALUE>",
      // Please replace with the actual SMS content.
      message: "<YOUR_VALUE>",
    });
// Create request object and set required input parameters
let sendMessageToGlobeRequest = new Dysmsapi20180501.SendMessageToGlobeRequest({
    // Please replace with the actual recipient number.
    to: '<YOUR_VALUE>',
    // Please replace with the actual SMS content.
    message: '<YOUR_VALUE>',
});
說明

針對部分需要上傳檔案的OpenAPI,可以通過建立<OpenAPI名稱>AdvanceRequest請求對象傳遞檔案流。以視覺智能開放平台-人臉人體的DetectBodyCount介面為例:

TypeScript樣本
JavaScript樣本
    // 讀取檔案為fileStream流形式
    const filePath = '<FILE_PATH>';  //需替換檔案路徑
    // 檢查檔案
    if (!fs.existsSync(filePath)) {
        console.error('檔案不存在:', filePath);
        return;
    }
    // 建立流並監聽流錯誤
    const fileStream = fs.createReadStream(filePath).on('error', (err) => {
        console.error('檔案流錯誤:', err);
        process.exit(1);
    });

    let detectBodyCountAdvanceRequest = new $facebody20191230.DetectBodyCountAdvanceRequest({
      imageURLObject: fileStream,
    });
    // 讀取檔案為fileStream流形式
    const filePath = '<FILE_PATH>';  //需替換檔案路徑
    // 檢查檔案
    if (!fs.existsSync(filePath)) {
        console.error('檔案不存在:', filePath);
        return;
    }
    // 建立流並監聽流錯誤
    const fileStream = fs.createReadStream(filePath).on('error', (err) => {
        console.error('檔案流錯誤:', err);
        process.exit(1);
    });

    // 配置請求參數
    let detectBodyCountAdvanceRequest = new facebody20191230.DetectBodyCountAdvanceRequest({
        imageURLObject: fileStream,
    });

3.3 發起請求

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

說明

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

TypeScript樣本
JavaScript樣本
// Create runtime parameters.
let runtime = new $Util.RuntimeOptions({ });
// Send a request.
await client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
// Create runtime parameters.
let runtime = new Util.RuntimeOptions({ });
// Send a request.
await client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
說明

針對部分需要本地上傳檔案的OpenAPI,需調用函數<介面名稱>Advance發起請求,其中<介面名稱>為OpenAPI名稱的首字母小寫格式以調用視覺智能開放平台-人臉人體的DetectBodyCount介面為例:

TypeScript樣本
JavaScript樣本
// 配置運行時參數
let runtime = new $Util.RuntimeOptions({ });
// 發起請求   
await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
 // 配置運行時參數
 let runtime = new Util.RuntimeOptions({ });
 // 發起請求   
 await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);  

3.4 異常處理

V2.0 Node.js SDK將異常進行了細緻的分類,主要劃分為UnretryableError和ResponseError。

  • UnretryableError:主要是由於網路問題導致在達到最大重試次數後拋出異常,可以通過err.data.lastRequest來查詢錯誤發生時的請求資訊。

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

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

重要

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

完整程式碼範例

通用介面調用樣本
上傳檔案介面調用樣本
TypeScript樣本
JavaScript樣本
import Dysmsapi20180501, * as $Dysmsapi20180501 from '@alicloud/dysmsapi20180501';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {

  static createClient(): Dysmsapi20180501 {
    let config = new $OpenApi.Config({
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    // Endpoint 請參考 https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20180501(config);
  }

  static async main(): Promise<void> {
    let client = Client.createClient();
    // 建立請求對象並設定入參
    let sendMessageToGlobeRequest = new $Dysmsapi20180501.SendMessageToGlobeRequest({
      to: "<YOUR_VALUE>",
      from: "<YOUR_VALUE>",
      message: "<YOUR_VALUE>",
    });
    let runtime = new $Util.RuntimeOptions({ });
    try {
      // 發起請求  
      await client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
    } catch (error) {
      // 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
      // 錯誤 message
      console.log(error.message);
      // 診斷地址
      console.log(error.data["Recommend"]);
    }    
  }
}

Client.main();
const Dysmsapi20180501 = require('@alicloud/dysmsapi20180501');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');

class Client {

  static createClient() {
    let config = new OpenApi.Config({
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    // Endpoint 請參考 https://api.alibabacloud.com/product/Dysmsapi.
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20180501.default(config);
  }

  static async main() {
    // 建立請求對象並設定入參
    let client = Client.createClient();
    let sendMessageToGlobeRequest = new Dysmsapi20180501.SendMessageToGlobeRequest({
      to: '<YOUR_VALUE>',
      from: '<YOUR_VALUE>',
      message: '<YOUR_VALUE>',
    });
    let runtime = new Util.RuntimeOptions({ });
    try {
      // 發起請求
      await client.sendMessageToGlobeWithOptions(sendMessageToGlobeRequest, runtime);
    } catch (error) {
      // 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
      // 錯誤 message
      console.log(error.message);
      // 診斷地址
      console.log(error.data["Recommend"]);
      Util.default.assertAsString(error.message);
    }    
  }
}

exports.Client = Client;
Client.main();
TypeScript樣本
JavaScript樣本
import { default as facebody20191230 } from '@alicloud/facebody20191230'; 
import * as $facebody20191230 from '@alicloud/facebody20191230';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import * as $tea from '@alicloud/tea-typescript';
import * as fs from "fs"; 

export default class Client {

  static createClient(): facebody20191230 {
    let config = new $OpenApi.Config({
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });
    config.endpoint = `facebody.cn-shanghai.aliyuncs.com`;
    return new facebody20191230(config);
  }

  static async main(args: string[]): Promise<void> {
    let client = Client.createClient();

    // 讀取檔案為fileStream流形式
    const filePath = '<FILE_PATH>';  //需替換檔案路徑
    // 檢查檔案
    if (!fs.existsSync(filePath)) {
        console.error('檔案不存在:', filePath);
        return;
    }
    // 建立流並監聽流錯誤
    const fileStream = fs.createReadStream(filePath).on('error', (err) => {
        console.error('檔案流錯誤:', err);
        process.exit(1);
    });

    let detectBodyCountAdvanceRequest = new $facebody20191230.DetectBodyCountAdvanceRequest({
      imageURLObject: fileStream,
    });
    let runtime = new $Util.RuntimeOptions({ });
    try {
      // 發起請求
      const res = await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
      console.log(res);
    } catch (error) {
      if (error instanceof Error) {
        console.error('錯誤訊息:', error.message);
        const data = (error as any)?.data?.Recommend;
        if (typeof data === 'string') {
          console.log('診斷建議:', data);
        }
      } 
    }    
  }

}

Client.main(process.argv.slice(2));
'use strict';
const facebody20191230 = require('@alicloud/facebody20191230');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Tea = require('@alicloud/tea-typescript');
const fs = require('fs'); 


class Client {

  static createClient() {
    let config = new OpenApi.Config({
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
      accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      // 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
      accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    });

    config.endpoint = `facebody.cn-shanghai.aliyuncs.com`;
    return new facebody20191230.default(config);
  }

  static async main(args) {
    let client = Client.createClient();
    // 讀取檔案為fileStream流形式
    const filePath = '<FILE_PATH>';  //需替換檔案路徑
    // 檢查檔案
    if (!fs.existsSync(filePath)) {
        console.error('檔案不存在:', filePath);
        return;
    }
    // 建立流並監聽流錯誤
    const fileStream = fs.createReadStream(filePath).on('error', (err) => {
        console.error('檔案流錯誤:', err);
        process.exit(1);
    });
    // 配置請求參數
    let detectBodyCountAdvanceRequest = new facebody20191230.DetectBodyCountAdvanceRequest({
        imageURLObject: fileStream,
    });
    let runtime = new Util.RuntimeOptions({ });
    try {
      // 發起請求
      const res = await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
      console.log(res);
    } catch (error) {
      // 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
      // 錯誤 message
      console.log(error.message);
      // 診斷地址
      console.log(error.data["Recommend"]);
      Util.default.assertAsString(error.message);
    }    
  }

}

exports.Client = Client;
Client.main(process.argv.slice(2));

常見問題

  1. 調用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": "*"
        }
      ]
    }
  2. 調用OpenAPI時報錯,提示 "triggerUncaughtException Error: getaddrinfo ENOTFOUND",該錯誤與 'Endpoint' 相關。

    問題原因及解決方案

    問題原因:您所調用的OpenAPI不支援在初始化請求用戶端時填寫的Endpoint。

    解決方案:請查看Endpoint配置,修改Endpoint後重新調用OpenAPI。

  3. 調用OpenAPI時報錯,提示:“Cannot read properties of undefined (reading 'getCredential')”或“InvalidAccessKeyId.NotFound: code: 404”,該錯誤與'AccessKey'相關。

    問題原因及解決方案

    問題原因:您的AccessKey未正確傳遞。

    解決方案:在初始化請求用戶端時,檢查是否正確傳遞AccessKey。請注意process.env("XXX")表示從環境變數中擷取XXX的值。

更多SDK使用過程中的報錯問題解決方案,請參見常見問題

  • 本頁導讀 (1, M)
  • 環境要求
  • 1. 引入SDK
  • 2. 設定訪問憑據
  • 3. 編寫調用代碼
  • 3.1 初始化請求用戶端
  • 3.2 建立請求對象
  • 3.3 發起請求
  • 3.4 異常處理
  • 完整程式碼範例
  • 常見問題
文檔反饋
phone 聯絡我們

立即和Alibaba Cloud在線服務人員進行交談,獲取您想了解的產品信息以及最新折扣。

alicare alicarealicarealicare