文档

集成SDK

更新时间:
一键部署

集成阿里云SDK主要有三步:引入阿里云SDK、设置访问凭据、编写调用代码。本文将以Node.js语言调用短信服务 SMS(Short Message Service)的发送短信接口为例,讲解完整的集成步骤。

环境要求

Node.js >= 8.x

1. 引入SDK

阿里云SDK支持泛化与特化两种方式调用OpenAPI,详情参见泛化调用与特化调用,不同的调用方式需要引入的SDK也不同。

获取特化调用SDK安装方式

V2.0 SDK中包含了参数处理、请求组装以及返回值处理等OpenAPI请求的主要逻辑。开发者只需安装相关产品的SDK包依赖,即可调用阿里云OpenAPI。

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

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

获取泛化调用SDK安装方式

泛化调用方式不依赖任何一个产品的SDK,只依赖核心包@alicloud/openapi-client,即可调用阿里云API。Node.js语言安装配置文件如下,最新版本请参见alicloud/openapi-client

npm i @alicloud/openapi-client

2. 设置访问凭据

调用阿里云OpenAPI通常需要设置访问凭据(AccessKey),详情请参见凭据。为了避免凭据泄露,常见的方案是将其写入到环境变量中,更多安全方案请参见凭据的安全使用方案。以设置环境变量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=<ACCESS_KEY_ID>
  • 配置AccessKey Secret并回车。

    # 将<ACCESS_KEY_SECRET>替换为您自己的AccessKey Secret。
    export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ACCESS_KEY_SECRET>
  • 验证是否配置成功。

    执行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令,如果返回正确的AccessKey ID,则说明配置成功。

Windows系统配置方法

通过图形用户界面GUI

  • 操作步骤

    以下为Windows 10中通过图形用户界面设置环境变量的步骤。

    在桌面右键单击此电脑,选择属性>高级系统设置>环境变量>系统变量/用户变量>新建,完成以下配置:

    变量

    示例值

    AccessKey ID

    • 变量名:ALIBABA_CLOUD_ACCESS_KEY_ID

    • 变量值:LTAI4GDty8ab9W4Y1D****

    AccessKey Secret

    • 变量名:ALIBABA_CLOUD_ACCESS_KEY_SECRET

    • 变量值:IrVTNZNy5yQelTETg0cZML3TQn****

  • 测试设置是否成功

    单击开始(或快捷键:Win+R)> 运行(输入 cmd)> 确定(或按 Enter 键),打开命令提示符,执行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正确的AccessKey,则说明配置成功。

通过命令行提示符CMD

  • 操作步骤

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

    setx ALIBABA_CLOUD_ACCESS_KEY_ID LTAI4GDty8ab9W4Y1D**** /M
    setx ALIBABA_CLOUD_ACCESS_KEY_SECRET IrVTNZNy5yQelTETg0cZML3TQn**** /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', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::User)

为所有用户设置环境变量(需要管理员权限):

[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::Machine)

设置临时的环境变量(仅当前会话有效):

$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "LTAI4GDty8ab9W4Y1D****"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "IrVTNZNy5yQelTETg0cZML3TQn****"

在PowerShell中,执行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_IDGet-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正确的AccessKey,则说明配置成功。

3. 调用OpenAPI

这里以特化调用为例,为您讲解调用过程。如果您选择泛化调用方式,请参见泛化调用

3.1 初始化请求客户端

初始化请求客户端有多种方式,这里以使用AK初始化为例,更多初始化方式,请参见管理访问凭证

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

JavaScript示例

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 创建请求对象&运行时配置

通常您需要根据业务的实际需要传入参数,您也可自定义运行时配置。

// 创建请求对象并设置入参
let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({
    phoneNumbers: "<YOUR_VALUE>",
    signName: "<YOUR_VALUE>",
    templateCode: "<YOUR_VALUE>",
});
// 创建运行时配置对象
let runtime = new $Util.RuntimeOptions({});

3.3 发起请求

在V2.0 SDK中,每个产品的客户端包含了该产品所提供的所有OpenAPI。此外,对于每一个OpenAPI,SDK提供了三种接口定义方式。这样的设计旨在提升开发灵活性与效率,确保开发者能够以最符合自身项目需求的方式调用API。

说明

接口名称为OpenAPI名称首字母小写。

  • <接口名称>:使用默认的运行时配置发起接口调用,可以不用传入运行参数的请求方法。

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

    JavaScript示例

    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>',
        });
        try {
          // 发起请求
          await client.sendSms(sendSmsRequest);
        } catch (error) {
          // 此处仅做打印展示,请谨慎对待异常处理,在工程项目中切勿直接忽略异常。
          // 错误 message
          console.log(error.message);
          // 诊断地址
          console.log(error.data["Recommend"]);
          Util.default.assertAsString(error.message);
        }    
      }
    }
    
    exports.Client = Client;
    Client.main();
    
  • <接口名称>WithOptions:可配置自定义运行时参数发起接口调用,更多运行时参数配置请参见进阶配置

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

    JavaScript示例

    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();
    
  • <接口名称>Advance:专门用于应对直接上传Object 的场景,该方法默认需要传入运行时参数。下述示例以视觉智能开放平台人体人脸产品为例介绍SDK如何使用本地文件上传调用 API。

    // 人体人脸依赖信息
    npm install @alicloud/facebody20191230@4.0.8

    TypeScript示例

    import Facebody20191230, * as $Facebody20191230 from '@alicloud/facebody20191230';
    import * as $OpenApi from '@alicloud/openapi-client';
    import * as $Util from '@alicloud/tea-util';
    import {createReadStream} from 'fs';
    import Credential from '@alicloud/credentials';
    
    export default class Client {
      static async main(): Promise<void> {
        // 使用默认凭证初始化Credentials Client
        const credentialClient = new Credential();
        const facebodyConfig = new $OpenApi.Config({
          // 使用Credentials配置凭证
          credential: credentialClient,
          // 访问的区域,facebody目前仅开通上海地域
          regionId: 'cn-shanghai',
        });
        const facebodyClient = new Facebody20191230(facebodyConfig);
        const request = new $Facebody20191230.DetectBodyCountAdvanceRequest({
          imageURLObject: createReadStream('<YOUR-FILE-PATH>'),
        });
        // 创建RuntimeObject实例并设置运行参数。
        const runtime = new $Util.RuntimeOptions({});
        const resp = await facebodyClient.DetectBodyCountAdvance(request, runtime);
        console.log(resp.headers);
        console.log(resp.body);
      }
    }
    

    JavaScript示例

    const { default: Facebody20191230, DetectBodyCountAdvanceRequest } = require('@alicloud/facebody20191230');
    const { Config } = require('@alicloud/openapi-client');
    const { RuntimeOptions } = require('@alicloud/tea-util');
    const { createReadStream } = require('fs');
    const { default: Credential } = require('@alicloud/credentials')
    
    async function main() {
      const facebodyConfig = new Config({
        credential: new Credential(),
        // 访问的区域,facebody目前仅开通上海地域
        regionId: 'cn-shanghai'
      });
      const facebodyClient = new Facebody20191230(facebodyConfig);
      const request = new DetectBodyCountAdvanceRequest({
        imageURLObject: createReadStream('<YOUR-FILE-PATH>'),
      });
      // 创建RuntimeObject实例并设置运行参数。
      const runtime = new RuntimeOptions({});
      const resp = await facebodyClient.detectBodyCountAdvance(request, runtime);
      console.log(resp.headers);
      console.log(resp.body);
    }
    main();