集成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。
登錄SDK中心,選擇將要使用產品,例如您將要調用短信服務 SMS(Short Message Service)的API。
在安裝頁面,SDK 代系選擇V2.0,所有語言選擇TypeScript。然后在快速入門頁簽中,您可以獲取短信服務 SMS(Short Message Service)的SDK安裝方式。
獲取泛化調用SDK安裝方式
泛化調用方式不依賴任何一個產品的SDK,只依賴核心包@alicloud/openapi-client
,即可調用阿里云API。Node.js語言安裝配置文件如下,最新版本請參見alicloud/openapi-client:
npm i @alicloud/openapi-client
2. 設置訪問憑據
調用阿里云OpenAPI通常需要設置訪問憑據(AccessKey),詳情請參見憑據。為了避免憑據泄露,常見的方案是將其寫入到環境變量中,更多安全方案請參見憑據的安全使用方案。以設置環境變量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=<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_ID
、Get-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();