集成SDK
集成阿里云SDK主要有三步:引入阿里云SDK、設(shè)置訪問憑據(jù)、編寫調(diào)用代碼。本文將以Node.js
語(yǔ)言調(diào)用短信服務(wù) SMS(Short Message Service)的發(fā)送短信接口為例,講解完整的集成步驟。
環(huán)境要求
Node.js >= 8.x
1. 引入SDK
阿里云SDK支持泛化與特化兩種方式調(diào)用OpenAPI,詳情參見泛化調(diào)用與特化調(diào)用,不同的調(diào)用方式需要引入的SDK也不同。
獲取特化調(diào)用SDK安裝方式
V2.0 SDK中包含了參數(shù)處理、請(qǐng)求組裝以及返回值處理等OpenAPI請(qǐng)求的主要邏輯。開發(fā)者只需安裝相關(guān)產(chǎn)品的SDK包依賴,即可調(diào)用阿里云OpenAPI。
登錄SDK中心,選擇將要使用產(chǎn)品,例如您將要調(diào)用短信服務(wù) SMS(Short Message Service)的API。
在安裝頁(yè)面,SDK 代系選擇V2.0,所有語(yǔ)言選擇TypeScript。然后在快速入門頁(yè)簽中,您可以獲取短信服務(wù) SMS(Short Message Service)的SDK安裝方式。
獲取泛化調(diào)用SDK安裝方式
泛化調(diào)用方式不依賴任何一個(gè)產(chǎn)品的SDK,只依賴核心包@alicloud/openapi-client
,即可調(diào)用阿里云API。Node.js語(yǔ)言安裝配置文件如下,最新版本請(qǐng)參見alicloud/openapi-client:
npm i @alicloud/openapi-client
2. 設(shè)置訪問憑據(jù)
調(diào)用阿里云OpenAPI通常需要設(shè)置訪問憑據(jù)(AccessKey),詳情請(qǐng)參見憑據(jù)。為了避免憑據(jù)泄露,常見的方案是將其寫入到環(huán)境變量中,更多安全方案請(qǐng)參見憑據(jù)的安全使用方案。以設(shè)置環(huán)境變量ALIBABA_CLOUD_ACCESS_KEY_ID
和ALIBABA_CLOUD_ACCESS_KEY_SECRET
為例:
Linux和macOS系統(tǒng)配置方法
通過export命令配置環(huán)境變量
使用export命令配置的臨時(shí)環(huán)境變量?jī)H當(dāng)前會(huì)話有效,當(dāng)會(huì)話退出之后所設(shè)置的環(huán)境變量將會(huì)丟失。若需長(zhǎng)期保留環(huán)境變量,可將export命令配置到對(duì)應(yīng)操作系統(tǒng)的啟動(dòng)配置文件中。
配置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>
驗(yàn)證是否配置成功。
執(zhí)行
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
命令,如果返回正確的AccessKey ID,則說明配置成功。
Windows系統(tǒng)配置方法
通過圖形用戶界面GUI
操作步驟
以下為Windows 10中通過圖形用戶界面設(shè)置環(huán)境變量的步驟。
在桌面右鍵單擊此電腦,選擇屬性>高級(jí)系統(tǒng)設(shè)置>環(huán)境變量>系統(tǒng)變量/用戶變量>新建,完成以下配置:
變量
示例值
AccessKey ID
變量名:ALIBABA_CLOUD_ACCESS_KEY_ID
變量值:LTAI4GDty8ab9W4Y1D****
AccessKey Secret
變量名:ALIBABA_CLOUD_ACCESS_KEY_SECRET
變量值:IrVTNZNy5yQelTETg0cZML3TQn****
測(cè)試設(shè)置是否成功
單擊開始(或快捷鍵:Win+R)> 運(yùn)行(輸入 cmd)> 確定(或按 Enter 鍵),打開命令提示符,執(zhí)行
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
命令。若返回正確的AccessKey,則說明配置成功。
通過命令行提示符CMD
操作步驟
以管理員身份打開命令提示符,并使用以下命令在系統(tǒng)中新增環(huán)境變量。
setx ALIBABA_CLOUD_ACCESS_KEY_ID LTAI4GDty8ab9W4Y1D**** /M setx ALIBABA_CLOUD_ACCESS_KEY_SECRET IrVTNZNy5yQelTETg0cZML3TQn**** /M
其中
/M
表示系統(tǒng)級(jí)環(huán)境變量,設(shè)置用戶級(jí)環(huán)境變量時(shí)可以不攜帶該參數(shù)。測(cè)試設(shè)置是否成功
單擊開始(或快捷鍵:Win+R)> 運(yùn)行(輸入 cmd)> 確定(或按 Enter 鍵),打開命令提示符,執(zhí)行
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
命令。若返回正確的AccessKey,則說明配置成功。
通過Windows PowerShell
在PowerShell中,設(shè)置新的環(huán)境變量(對(duì)所有新會(huì)話都有效):
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::User)
為所有用戶設(shè)置環(huán)境變量(需要管理員權(quán)限):
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'LTAI4GDty8ab9W4Y1D****', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'IrVTNZNy5yQelTETg0cZML3TQn****', [System.EnvironmentVariableTarget]::Machine)
設(shè)置臨時(shí)的環(huán)境變量(僅當(dāng)前會(huì)話有效):
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "LTAI4GDty8ab9W4Y1D****"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "IrVTNZNy5yQelTETg0cZML3TQn****"
在PowerShell中,執(zhí)行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID
、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET
命令。若返回正確的AccessKey,則說明配置成功。
3. 調(diào)用OpenAPI
這里以特化調(diào)用為例,為您講解調(diào)用過程。如果您選擇泛化調(diào)用方式,請(qǐng)參見泛化調(diào)用。
3.1 初始化請(qǐng)求客戶端
初始化請(qǐng)求客戶端有多種方式,這里以使用AK初始化為例,更多初始化方式,請(qǐng)參見管理訪問憑證。
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({
// 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。
accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
// 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
});
// Endpoint 請(qǐng)參考 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({
// 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。
accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
// 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
});
// Endpoint 請(qǐng)參考 https://api.aliyun.com/product/Dysmsapi
config.endpoint = `dysmsapi.aliyuncs.com`;
return new Dysmsapi20170525.default(config);
}
}
3.2 創(chuàng)建請(qǐng)求對(duì)象&運(yùn)行時(shí)配置
通常您需要根據(jù)業(yè)務(wù)的實(shí)際需要傳入?yún)?shù),您也可自定義運(yùn)行時(shí)配置。
// 創(chuàng)建請(qǐng)求對(duì)象并設(shè)置入?yún)?let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({
phoneNumbers: "<YOUR_VALUE>",
signName: "<YOUR_VALUE>",
templateCode: "<YOUR_VALUE>",
});
// 創(chuàng)建運(yùn)行時(shí)配置對(duì)象
let runtime = new $Util.RuntimeOptions({});
3.3 發(fā)起請(qǐng)求
在V2.0 SDK中,每個(gè)產(chǎn)品的客戶端包含了該產(chǎn)品所提供的所有OpenAPI。此外,對(duì)于每一個(gè)OpenAPI,SDK提供了三種接口定義方式。這樣的設(shè)計(jì)旨在提升開發(fā)靈活性與效率,確保開發(fā)者能夠以最符合自身項(xiàng)目需求的方式調(diào)用API。
接口名稱為OpenAPI名稱首字母小寫。
<接口名稱>
:使用默認(rèn)的運(yùn)行時(shí)配置發(fā)起接口調(diào)用,可以不用傳入運(yùn)行參數(shù)的請(qǐng)求方法。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({ // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。 accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'], // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。 accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], }); // Endpoint 請(qǐng)參考 https://api.aliyun.com/product/Dysmsapi config.endpoint = `dysmsapi.aliyuncs.com`; return new Dysmsapi20170525(config); } static async main(): Promise<void> { let client = Client.createClient(); // 創(chuàng)建請(qǐng)求對(duì)象并設(shè)置入?yún)? let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({ phoneNumbers: "<YOUR_VALUE>", signName: "<YOUR_VALUE>", templateCode: "<YOUR_VALUE>", }); try { // 發(fā)起請(qǐng)求 await client.sendSms(sendSmsRequest); } catch (error) { // 此處僅做打印展示,請(qǐng)謹(jǐn)慎對(duì)待異常處理,在工程項(xiàng)目中切勿直接忽略異常。 // 錯(cuò)誤 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({ // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。 accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'], // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。 accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], }); // Endpoint 請(qǐng)參考 https://api.aliyun.com/product/Dysmsapi config.endpoint = `dysmsapi.aliyuncs.com`; return new Dysmsapi20170525.default(config); } static async main() { let client = Client.createClient(); // 創(chuàng)建請(qǐng)求對(duì)象并設(shè)置入?yún)? let sendSmsRequest = new Dysmsapi20170525.SendSmsRequest({ phoneNumbers: '<YOUR_VALUE>', signName: '<YOUR_VALUE>', templateCode: '<YOUR_VALUE>', }); try { // 發(fā)起請(qǐng)求 await client.sendSms(sendSmsRequest); } catch (error) { // 此處僅做打印展示,請(qǐng)謹(jǐn)慎對(duì)待異常處理,在工程項(xiàng)目中切勿直接忽略異常。 // 錯(cuò)誤 message console.log(error.message); // 診斷地址 console.log(error.data["Recommend"]); Util.default.assertAsString(error.message); } } } exports.Client = Client; Client.main();
<接口名稱>WithOptions
:可配置自定義運(yùn)行時(shí)參數(shù)發(fā)起接口調(diào)用,更多運(yùn)行時(shí)參數(shù)配置請(qǐng)參見進(jìn)階配置。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({ // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。 accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'], // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。 accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], }); // Endpoint 請(qǐng)參考 https://api.aliyun.com/product/Dysmsapi config.endpoint = `dysmsapi.aliyuncs.com`; return new Dysmsapi20170525(config); } static async main(): Promise<void> { let client = Client.createClient(); // 創(chuàng)建請(qǐng)求對(duì)象并設(shè)置入?yún)? let sendSmsRequest = new $Dysmsapi20170525.SendSmsRequest({ phoneNumbers: "<YOUR_VALUE>", signName: "<YOUR_VALUE>", templateCode: "<YOUR_VALUE>", }); // 創(chuàng)建運(yùn)行時(shí)配置對(duì)象 let runtime = new $Util.RuntimeOptions({ }); try { // 發(fā)起請(qǐng)求 await client.sendSmsWithOptions(sendSmsRequest, runtime); } catch (error) { // 此處僅做打印展示,請(qǐng)謹(jǐn)慎對(duì)待異常處理,在工程項(xiàng)目中切勿直接忽略異常。 // 錯(cuò)誤 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({ // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_ID。 accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'], // 必填,請(qǐng)確保代碼運(yùn)行環(huán)境設(shè)置了環(huán)境變量 ALIBABA_CLOUD_ACCESS_KEY_SECRET。 accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], }); // Endpoint 請(qǐng)參考 https://api.aliyun.com/product/Dysmsapi config.endpoint = `dysmsapi.aliyuncs.com`; return new Dysmsapi20170525.default(config); } static async main() { let client = Client.createClient(); // 創(chuàng)建請(qǐng)求對(duì)象并設(shè)置入?yún)? let sendSmsRequest = new Dysmsapi20170525.SendSmsRequest({ phoneNumbers: '<YOUR_VALUE>', signName: '<YOUR_VALUE>', templateCode: '<YOUR_VALUE>', }); // 創(chuàng)建運(yùn)行時(shí)配置對(duì)象 let runtime = new Util.RuntimeOptions({ }); try { // 發(fā)起請(qǐng)求 await client.sendSmsWithOptions(sendSmsRequest, runtime); } catch (error) { // 此處僅做打印展示,請(qǐng)謹(jǐn)慎對(duì)待異常處理,在工程項(xiàng)目中切勿直接忽略異常。 // 錯(cuò)誤 message console.log(error.message); // 診斷地址 console.log(error.data["Recommend"]); Util.default.assertAsString(error.message); } } } exports.Client = Client; Client.main();
<接口名稱>Advance
:專門用于應(yīng)對(duì)直接上傳Object 的場(chǎng)景,該方法默認(rèn)需要傳入運(yùn)行時(shí)參數(shù)。下述示例以視覺智能開放平臺(tái)人體人臉
產(chǎn)品為例介紹SDK如何使用本地文件上傳調(diào)用 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> { // 使用默認(rèn)憑證初始化Credentials Client const credentialClient = new Credential(); const facebodyConfig = new $OpenApi.Config({ // 使用Credentials配置憑證 credential: credentialClient, // 訪問的區(qū)域,facebody目前僅開通上海地域 regionId: 'cn-shanghai', }); const facebodyClient = new Facebody20191230(facebodyConfig); const request = new $Facebody20191230.DetectBodyCountAdvanceRequest({ imageURLObject: createReadStream('<YOUR-FILE-PATH>'), }); // 創(chuàng)建RuntimeObject實(shí)例并設(shè)置運(yùn)行參數(shù)。 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(), // 訪問的區(qū)域,facebody目前僅開通上海地域 regionId: 'cn-shanghai' }); const facebodyClient = new Facebody20191230(facebodyConfig); const request = new DetectBodyCountAdvanceRequest({ imageURLObject: createReadStream('<YOUR-FILE-PATH>'), }); // 創(chuàng)建RuntimeObject實(shí)例并設(shè)置運(yùn)行參數(shù)。 const runtime = new RuntimeOptions({}); const resp = await facebodyClient.detectBodyCountAdvance(request, runtime); console.log(resp.headers); console.log(resp.body); } main();