集成SDK
在调用OpenAPI时,建议采用在项目中集成SDK的方式。使用SDK可以简化开发流程,实现功能的快速集成,同时有效降低维护成本。集成阿里云SDK主要包括三个步骤:引入阿里云SDK、设置访问凭据以及使用SDK。本文将详细介绍SDK集成的具体流程。
环境要求
Node.js >= 8.x
引入SDK
登录SDK中心,选择将要使用产品,例如您将要调用短信服务 SMS(Short Message Service)的API。
在安装页面,SDK 代系选择V2.0,所有语言选择TypeScript。然后在快速入门页签中,您可以获取短信服务 SMS(Short Message Service)的SDK安装方式。
设置访问凭据
调用阿里云OpenAPI通常需要设置访问凭据,常见凭据类型为AccessKey(简称:AK)
和临时安全令牌STS Token
。为防止凭据泄露,常用的方案是将其存储到环境变量中,更多安全方案请参见访问凭据的安全使用方案。本文以设置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID
和ALIBABA_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_ID
、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET
命令。若返回正确的AccessKey,则说明配置成功。
使用SDK
本文以调用短信服务 SMS(Short Message Service)的SendSms接口为例,关于SendSms接口的API文档,请参见SendSms。
1. 初始化请求客户端
在SDK中,所有的OpenAPI均通过SDK提供的请求客户端(Client)发起调用。因此,在调用OpenAPI之前,需要先对请求客户端进行初始化。请求客户端支持多种方式初始化,本示例以使用AK进行初始化为例,更多初始化方式请参见管理访问凭证。
客户端对象(如 Dysmsapi20170525实例)是线程安全的,能够在多线程环境中安全使用,无需为每个线程单独创建实例。
在实际开发中,不建议频繁通过 new 关键字创建客户端对象,这会导致资源浪费和性能下降。推荐采用单例模式封装客户端,确保在整个应用程序生命周期中针对相同的访问凭据和Endpoint仅初始化一个客户端对象实例。
TypeScript示例
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);
}
}
Node.js示例
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);
}
}
2. 创建请求对象
在调用OpenAPI进行参数传递时,需使用SDK提供的请求对象来实现参数的传递。OpenAPI请求对象的命名方式为:<OpenAPI名称>Request
,例如SendSms该接口的请求对象为SendSmsRequest。有关请求参数的详细信息,请查阅相应的API文档,本示例API文档请参见SendSms。
若OpenAPI不支持请求参数,则无需创建请求对象。例如,在调用DescribeCdnSubList时,该接口不支持请求参数。
TypeScript示例
// 创建请求对象并设置入参
let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({
// 需要替换成为您接收短信的手机号码
phoneNumbers: "<YOUR_VALUE>",
// 需要替换成为您的短信签名
signName: "<YOUR_VALUE>",
// 需要替换成为您的短信模板code
templateCode: "<YOUR_VALUE>",
});
Node.js示例
// 创建请求对象并设置入参
let sendSmsRequest = new Dysmsapi20170525.SendSmsRequest({
// 需要替换成为您接收短信的手机号码
phoneNumbers: "<YOUR_VALUE>",
// 需要替换成为您的短信签名
signName: "<YOUR_VALUE>",
// 需要替换成为您的短信模板code
templateCode: "<YOUR_VALUE>",
});
3. 发起请求
通过请求客户端调用OpenAPI时,建议使用的函数名称为<接口名称>WithOptions
,其中<接口名称>
为OpenAPI名称的首字母小写格式。该函数包含两个参数:一个为请求对象,另一个为运行时参数。请求对象为上一步创建的请求对象;运行时参数用于配置请求的行为,例如超时设置、代理配置等。更多信息,请参见进阶配置。
若OpenAPI不支持请求参数,则在发起请求时无需传递请求对象。例如,在调用DescribeCdnSubList时,该接口只需传入运行时参数。
TypeScript示例
// 创建运行时参数
let runtime = new $Util.RuntimeOptions({ });
let client = Client.createClient();
// 发起请求
await client.sendSmsWithOptions(sendSmsRequest, runtime);
Node.js示例
// 创建运行时参数
let runtime = new Util.RuntimeOptions({ });
let client = Client.createClient();
// 发起请求
await client.sendSmsWithOptions(sendSmsRequest, runtime);
4. 异常处理
V2.0 Node.js SDK将异常进行了细致的分类,主要划分为UnretryableError和ResponseError。
UnretryableError:主要是由于网络问题导致在达到最大重试次数后抛出异常,可以通过
err.data.lastRequest
来查询错误发生时的请求信息。ResponseError:主要以业务报错为主的异常。
更多关于异常处理的介绍,请参见异常处理。
建议采取合理的措施来处理异常,比如合理地传播异常、记录日志、尝试恢复等,以确保系统的健壮性和稳定性。
点击查看完整代码示例
特殊场景:文件上传 Advance 接口配置
在使用图像搜索、视觉智能开放平台等云产品处理本地图片或上传图片时,官方文档中提供的OpenAPI接口不支持直接上传文件。若需上传文件,可以使用云产品提供的Advance
接口,该接口支持传递文件流对象。其底层实现机制为:云产品会将上传的文件临时存储于阿里云OSS上,默认存储地域为cn-shanghai
,并通过读取该OSS中的临时文件来实现相关功能。以阿里云提供的视觉智能开放平台-人脸人体的DetectBodyCount
接口为例:
存储在阿里云 OSS 的临时文件会被定时清理。
初始化请求客户端
请注意需同时设置
regionId
和云产品的endpoint
。其中,regionId
表示临时文件在OSS中所存储的地域。如果未设置regionId
,可能会由于云产品与OSS所在地域不同,导致在调用OpenAPI时出现超时等问题。TypeScript示例
function 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'], }); // endpoint 和 regionId 需设置为同一地域 config.regionId = 'cn-shanghai'; config.endpoint = 'facebody.cn-shanghai.aliyuncs.com'; return new facebody20191230(config); }
Node.js示例
function 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 和 regionId 需设置为同一地域 config.regionId = 'cn-shanghai'; config.endpoint = 'facebody.cn-shanghai.aliyuncs.com'; return new facebody20191230.default(config); }
创建请求对象
通过创建
<OpenAPI名称>AdvanceRequest
请求对象传递文件流,参数名固定为ImageURLObject
。TypeScript示例
// 读取文件为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, });
Node.js示例
// 读取文件为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, });
发起请求
需调用函数
<接口名称>Advance
发起请求。TypeScript示例
// 配置运行时参数 let runtime = new $Util.RuntimeOptions({ }); let client = Client.createClient(); // 发起请求 await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
Node.js示例
// 配置运行时参数 let runtime = new Util.RuntimeOptions({ }); let client = Client.createClient(); // 发起请求 await client.detectBodyCountAdvance(detectBodyCountAdvanceRequest, runtime);
常见问题
调用OpenAPI时报错,提示“You are not authorized to perform this operation”。
调用OpenAPI时报错,提示 "triggerUncaughtException Error: getaddrinfo ENOTFOUND",该错误与 'Endpoint' 相关。
调用OpenAPI时报错,提示:“Cannot read properties of undefined (reading 'getCredential')”或“InvalidAccessKeyId.NotFound: code: 404”,该错误与'AccessKey'相关。
更多SDK使用过程中的报错问题解决方案,请参见常见问题。