如何使用PDSClient類 - Drive and Photo Service

本文檔主要介紹 PDSClient 類的用法，包括構造方法，公用方法和事件監聽的用法。

PDSClient 構造方法

建立一個可以調用所有 PDS API 的執行個體。

const client = new PDSClient(config, context);

參數說明

欄位	類型	必須	說明
config	IClientParams	是	請看下面的 `IClientParams` 欄位說明
context	IContext		執行環境內容。詳情請看 `IContext` 介紹。

IClientParams 欄位說明

欄位	類型	必須	說明
token_info	TokenInfo		通過 OAuth 登入或者JWT App 簽發的 `token` 資訊。
share_token	string		分享token。
api_endpoint	string	Y1	PDS API 地址，一般構成為：`https://{domainId}.api.aliyunpds.com`。
path_type	string		domain 的儲存路徑類型, 目前僅支援：`StandardMode`, 預設：`StandardMode`。
version	string		版本號碼，目前僅支援：`v2`。預設 `v2`。
refresh_token_fun	Function		`token` 到期時回調方法，該方法需要返回`Promise<TokenInfo>`。
refresh_share_token_fun	Function		`share_token` 到期時回調方法，該方法需要返回`Promise<string>`，返回新的 `share_token`。

api_endpoint 和 auth_endpoint 至少傳一個。

TokenInfo欄位說明

欄位	類型	必須	說明
access_token	string	是	代表使用者身份的 `JWT`。一般有效期間2小時。
refresh_token	string		重新整理 `token`，可用於重新整理到期的 `access_token`。
expire_time	string		`access_token` 的有效時間。一般為簽發`token` 2小時後的時間。
expires_in	string		`access_token`到期時間，單位秒。如：7200
token_type	string		`access_token` 類型，預設：`Bearer`
user_id	string		目前使用者唯一標識。
role	string		目前使用者角色。
...其他欄位			其他欄位請看Token - 擷取存取權杖。

IContext 欄位說明

欄位	類型	必須	說明
isNode	boolean	是	是否是Node.js環境。
Axios	object	是	詳見axios模組。
AxiosNodeAdapter	object		在`Node.js`環境下匯出`JS SDK`中的`Context`中的 `AxiosNodeAdapter`。
platform	string		即`Node.js`中的`process.platform`。取值範圍："`win32`", "`darwin`","`linux`" 。
os	object		`Node.js` 原生的 `os` 模組
fs	object		`Node.js` 原生的 `fs` 模組
path	object		`Node.js` 原生的`path`模組
cp	object		`Node.js` 原生的`child_process`模組。
http	object		`Node.js` 原生的`http`模組
https	object		`Node.js` 原生的`https`模組
crypto	object		`Node.js` 原生的`crypto`模組
worker_threads	object		`Node.js` 原生的`worker_threads`模組

如何擷取 Token

token 的擷取可以有多種方案，根據應用類型，具體擷取方法請看：應用概述。

如何重新整理 Token

access_token 的有效期間是 2 小時， refresh_token 的有效期間是 7 天。在 refresh_token 有效期間內，不管access_token是否失效，都是可以重新整理 token 的。

重新整理 token 後，舊的 access_token 和 refresh_token 失效。

具體步驟：

在初始化 PDSClient 的時候，配置 refresh_token_fun。

const client = new PDSClient({
   refresh_token_fun: async ()=>{
     // 此處調用後端重新整理token。 my_refresh_token_fun 為自己封裝的重新整理token方法。
     const token_info = await my_refresh_token_fun()
     return token_info
   }
});

封裝重新整理 token 方法。請看 Token - 擷取存取權杖

基礎公用方法

setToken 方法

如果不在建構函式傳入 token_info，可以調用此方法傳入。

確保 client 有效 token_info，才能調用後端介面。

client.setToken(token_info)

參數說明

欄位	類型	必須	說明
token_info	TokenInfo	是	傳入token_info。

無

setShareToken 方法

調用分享相關介面時，需要用到此方法。

如果不在建構函式傳入 share_token，可以調用此方法傳入。

確保 client 有效 share_token，才能調用後端介面。

client.setShareToken(share_token)

參數說明

欄位	類型	必須	說明
share_token	string	是	傳入share_token。

無

postAPI 方法

基礎 API 服務調用方法。基於此方法，可以封裝出調用任何 PDS API 方法。

const result = await client.postAPI(pathname, data={}, options={})

說明

請求參數中的 options: IPDSRequestConfig 基於 axios 的 request config 封裝，詳情請看：AxiosRequestConfig。

參數說明

欄位	類型	必須	說明
pathname	string	是	調用 API 服務的 pathname。比如 API 是 `/v2/file/list`, 此處傳入 `/file/list` 即可。
data	object		調用 `pathname` 對應介面的參數 JSON。
options	IPDSRequestConfig		其他請求參數。

欄位	類型	必須	說明
result	object		介面返回的結果資料。

舉例

let {items =[]} = await client.postAPI('/file/list', {
  drive_id: '1050', 
  parent_file_id: 'root',
})
console.log(items)

事件監聽

目前僅支援 error 事件。

error 事件

client.on('error', (error, req_opt)=> {
   console.log('Error',  error)
   console.log('Request Options:', req_opt)
})

回呼函數的參數說明

欄位	類型	必須	說明
error	PDSError	是	錯誤資訊。類型是 `PDSError`, 常規包含 `{code,message,reqId,status}` 幾個欄位。
req_opt	IPDSRequestConfig		請求參數。

PDSError 欄位說明

欄位	類型	必須	說明
status	number		服務端報錯返回的 `http status`。如果是用戶端報錯此項為空白。
code	string		服務端報錯返回的`code`欄位。如果是用戶端報錯此項一般為 `ClientError`
message	string	是	服務端報錯返回的`message`欄位。
reqId	string		服務端報錯返回的`requestId`欄位。如果是用戶端報錯則此項為空白
stack	string		調試用的 error stack
type	string		可選值：`ClientError`, `ServerError`。

PDSClient 構造方法

參數說明

如何擷取 Token

如何重新整理 Token

基礎公用方法

setToken 方法

參數說明

返回

setShareToken 方法

參數說明

返回

postAPI 方法

參數說明

返回

舉例

事件監聽

error 事件

回呼函數的參數說明