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

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

环境要求

Node.js >= 8.x

1. 引入SDK

登录SDK中心，选择将要使用产品，例如您将要调用短信服务 SMS（Short Message Service）的API。
在安装页面，SDK 代系选择V2.0，所有语言选择TypeScript。然后在快速入门页签中，您可以获取短信服务 SMS（Short Message Service）的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进行初始化为例，更多初始化方式请参见管理访问凭证。

TypeScript示例

JavaScript示例

import Dysmsapi20170525, * as $Dysmsapi20170525 from '@alicloud/dysmsapi20170525';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {

  static createClient(): Dysmsapi20170525 {
    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.aliyun.com/product/Dysmsapi
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20170525(config);
  }
}

const Dysmsapi20170525 = require('@alicloud/dysmsapi20170525');
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.aliyun.com/product/Dysmsapi
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20170525.default(config);
  }
}

3.2 创建请求对象

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

说明

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

TypeScript示例

JavaScript示例

// 创建请求对象并设置入参
let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({
    // 需要替换成为您接收短信的手机号码 
    phoneNumbers: "<YOUR_VALUE>",
    // 需要替换成为您的短信签名
    signName: "<YOUR_VALUE>",
    // 需要替换成为您的短信模板code
    templateCode: "<YOUR_VALUE>",
});

// 创建请求对象并设置入参
let sendSmsRequest = new Dysmsapi20170525.SendSmsRequest({
    // 需要替换成为您接收短信的手机号码 
    phoneNumbers: "<YOUR_VALUE>",
    // 需要替换成为您的短信签名
    signName: "<YOUR_VALUE>",
    // 需要替换成为您的短信模板code
    templateCode: "<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示例

// 创建运行时参数
let runtime = new $Util.RuntimeOptions({ });
// 发起请求
await client.sendSmsWithOptions(sendSmsRequest, runtime);

// 创建运行时参数
let runtime = new Util.RuntimeOptions({ });
// 发起请求   
await client.sendSmsWithOptions(sendSmsRequest, 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 Dysmsapi20170525, * as $Dysmsapi20170525 from '@alicloud/dysmsapi20170525';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {

  static createClient(): Dysmsapi20170525 {
    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.aliyun.com/product/Dysmsapi
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20170525(config);
  }

  static async main(): Promise<void> {
    let client = Client.createClient();
    // 创建请求对象并设置入参
    let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({
      phoneNumbers: "<YOUR_VALUE>",
      signName: "<YOUR_VALUE>",
      templateCode: "<YOUR_VALUE>",
    });
    let runtime = new $Util.RuntimeOptions({ });
    try {
      // 发起请求  
       await client.sendSmsWithOptions(sendSmsRequest, runtime);
    } catch (error) {
      // 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。
      // 错误 message
      console.log(error.message);
      // 诊断地址
      console.log(error.data["Recommend"]);
    }    
  }
}

Client.main();

const Dysmsapi20170525 = require('@alicloud/dysmsapi20170525');
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.aliyun.com/product/Dysmsapi
    config.endpoint = `dysmsapi.aliyuncs.com`;
    return new Dysmsapi20170525.default(config);
  }

  static async main() {
    let client = Client.createClient();
    // 创建请求对象并设置入参
    let sendSmsRequest = new Dysmsapi20170525.SendSmsRequest({
      phoneNumbers: '<YOUR_VALUE>',
      signName: '<YOUR_VALUE>',
      templateCode: '<YOUR_VALUE>',
    });
    let runtime = new Util.RuntimeOptions({ });
    try {
      // 发起请求
       await client.sendSmsWithOptions(sendSmsRequest, 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));

常见问题

调用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时报错，提示 "triggerUncaughtException Error: getaddrinfo ENOTFOUND"，该错误与 'Endpoint' 相关。

问题原因及解决方法

问题原因：您所调用的OpenAPI不支持在初始化请求客户端时填写的Endpoint。
解决方法：请查看Endpoint 配置，修改Endpoint后重新调用OpenAPI。
调用OpenAPI时报错，提示：“Cannot read properties of undefined (reading 'getCredential')”或“InvalidAccessKeyId.NotFound: code: 404”，该错误与'AccessKey'相关。

问题原因及解决方法

问题原因：您的AccessKey未正确传递。
解决方法：在初始化请求客户端时，检查是否正确传递AccessKey。请注意process.env("XXX")表示从环境变量中获取XXX的值。

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

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