Share links - Drive and Photo Service - Alibaba Cloud Documentation Center

This topic describes operations that are related to share links.

Note

The options parameter of the IPDSRequestConfig type is encapsulated based on the request config options of axios. For more information, see AxiosRequestConfig.

createShareLink method

You can call this method to create a share link.

const result = await client.createShareLink(params, options)

Example

await client.createShareLink({
  description: 'test',
  drive_id: '1060',
  expiration: '2021-12-08T15:59:59.999Z',
  file_id_list: ['61a49e39d687d40967164cf98ef65ab5bb554f53'],
  share_pwd: '831956',
})

Request parameters

Parameter	Type	Required	Description
params	ICreateShareLinReq	Yes	The parameters that are used to create a share link.
options	IPDSRequestConfig		Other request parameters.

ICreateShareLinReq

Parameter	Type	Required	Description
description	string		The description.
drive_id	string	Yes	The drive ID.
share_pwd	string		The access code. It can be up to 64 characters in length. If the parameter is left empty, no access code is required.
file_id_list	string[]	Yes	This parameter takes effect only in standard mode. A group of files or a list of folders. The number of files or folders can be up to 100.
file_path_list	string[]	Yes	This parameter takes effect in hosting mode. You can specify either the file_id_list parameter or the file_path_list parameter.
expiration	string	Yes	The time when the share link expires. Specify the time in the RFC 3339 format. Example: 2020-06-28T11:33:00.000+08:00. If the parameter is left empty, the share link is permanently valid.

Response parameters

Parameter	Type	Required	Description
result	IShareLinkItem	Yes	The details of the share link.

cancelShareLink method

You can call this method to cancel a share.

await client.cancelShareLink(params, options)

Example

await client.cancelShareLink({
  share_id: 'YgHgBeXGZWr'
})

Request parameters

Parameter	Type	Required	Description
params	Object	Yes	The parameters that are used to cancel a share.
options	IPDSRequestConfig		Other request parameters

params

Parameter	Type	Required	Description
share_id	string	Yes	The share ID.

Response parameters

No response parameter is returned.

listShareLinks method

You can call this method to query a list of shares.

const result = await client.listShareLinks(params, options)

Example

const {items=[], next_marker} = await client.listShareLinks({
  creator: 'user_id',
  marker: '',
  limit: 100,
})

Request parameters

Parameter	Type	Required	Description
params	Object	Yes	The parameters that are used to query a list of shares.
options	IPDSRequestConfig		Other request parameters.

params

Parameter	Type	Required	Description
limit	number		The maximum number of entries to be returned. Valid values: 1 to 100. Default value: 100.
marker	string		The start identifier of the query.
creator	string		The ID of the creator of the share. If you call this method as an administrator, shares are queried based on the following cases: If you do not specify this parameter, the shares that are created by all users are queried. If you set the value of this parameter to a specific user ID, the shares that are created by the specified user are queried. If you call this method as a regular user, shares are queried based on the following cases: If you do not specify this parameter, the shares that you created are queried. If you set the value of this parameter to a specific user ID other than yours, an error code 403 is returned.

Response parameters

Parameter	Type	Required	Description
result	IListRes<IShareLinkItem>	Yes	The returned result.

IListRes

Parameter	Type	Required	Description
items	IShareLinkItem[]	Yes	The IShareLinkItem parameters.
next_marker	string		The pagination token that is used in the next request to retrieve a new page of results.

IShareLinkItem

Parameter	Type	Description
share_id	string	The share ID.
share_pwd	string	The access code. If this parameter is left empty, an empty string is returned, which indicates that no access code is required.
share_msg	string	The share password.
share_url	string	The share link.
share_policy	'url' \| 'msg'	The share policy. Valid values: url: uses a URL. msg: uses a password.
description	string	The description.
share_name	string	The name of the share.
download_count	number	The number of times that the shared files are downloaded.
preview_count	number	The number of times that the shared files are previewed.
save_count	number	The number of times that the shared files are saved.
drive_id	string	The drive ID.
share_pwd	string	The access code. It can be up to 64 characters in length. If the parameter empty is left empty, no access code is required.
file_id_list	string[]	This parameter is returned in standard mode.
file_path_list	string[]	This parameter is returned in hosting mode.
expiration	Date	The time when the share link expires. The time is in the RFC 3339 format. Example: 2020-06-28T11:33:00.000+08:00. If the parameter is left empty, the share link is permanently valid.
expired	boolean	Indicates whether the share link has expired.
status	'enabled' \| 'disabled'	The state of the share.
creator	string	The ID of the creator of the share link.
created_at	string	The time when the share was created.
updated_at	string	The time when the share was last updated.

getShareLinkByAnonymous method

You can call this method to anonymously query the information about a share without using a token.

const result = await client.getShareLinkByAnonymous(params, options)

Example

const domain_id = 'Your domain ID'
const client = new PDSClient({
  api_endpoint: `https://${domain_id}.api.aliyunpds.com`
})
let info = client.getShareLinkByAnonymous({
  share_id: 'xxxxxx'
})

Request parameters

Parameter	Type	Required	Description
params	Object	Yes	The parameters that are used to query the information about a share.
options	IPDSRequestConfig		Other request parameters.

params

Parameter	Type	Required	Description
share_id	string	Yes	The share ID.

Response parameters

Parameter	Type	Required	Description
result	IAnonymousShareLinkItem	Yes	The returned result.

IAnonymousShareLinkItem

Parameter	Type	Required	Description
avatar	string	Yes	The profile picture of the user who shared the files.
creator_id	string	Yes	The ID of the creator of the share.
creator_name	string	Yes	The nickname of the creator of the share.
creator_phone	string		The mobile number of the creator of the share.
disable_download	boolean		Indicates whether the shared files are prohibited from being downloaded.
disable_preview	boolean		Indicates whether the shared files are prohibited from being previewed.
disable_save	boolean		Indicates whether the shared files are prohibited from being saved.
enable_upload	boolean		Indicates whether the shared files are allowed to be uploaded.
expiration	Date		The time when the share link expires.
preview_limit	number		The maximum number of times that the shared files can be previewed.
require_login	boolean		Indicates whether a logon is required to view the shared files.
save_download_limit	number		The maximum number of times that the shared files can be saved or downloaded.
share_name	string		The name of the share link.
updated_at	string		The time when the share link is last updated.

getShareToken method

You can call this method to anonymously query the share token without using a token.

Note

What is a share token?

A share token is a temporary token that can be used to call specific API operations such as listFiles instead of an access token. This allows users to preview the shared files without the need to log on to the client.

const result = await client.getShareToken(params, options)

Example

const domain_id = 'Your domain ID'
const client = new PDSClient({
  api_endpoint: `https://${domain_id}.api.aliyunpds.com`
})

try {
 
  let info = client.getShareToken({
    share_id: 'xxxxxx',
    // share_pwd: 'Access code' // If an access code is specified, enter the access code.
  })

}catch(e){
  // If an access code is required but no access code is specified, an error is reported.
  if (e.code == 'InvalidResource.SharePwd'){
    // An access code is required. 
  }
}

Request parameters

Parameter	Type	Required	Description
params	Object	Yes	The parameters that are used to query the share token.
options	IPDSRequestConfig		Other request parameters.

params

Parameter	Type	Required	Description
share_id	string	Yes	The share ID.
share_pwd	string		The access code.

Response parameters

Parameter	Type	Required	Description
result	IShareToken	Yes	The returned result.

IShareToken

Parameter	Type	Required	Description
share_token	string	Yes	The share token.
expire_time	string	Yes	The time when the share token expires.
expires_in	string	Yes	The validity period of the share token. Unit: seconds.

Use a share token

The following sample code uses a share token to query a list of shared files.

const share_token = 'The share token that you queried'
const share_id = 'Your share ID'
const domain_id = 'Your domain ID'

const client = new PDSClient({
  api_endpoint: `https://${domain_id}.api.aliyunpds.com`,
  share_token,
})

let {items=[], next_marker} = client.listFiles({ 
  share_id, 
  parent_file_id: 'root'
},
/*
{
  headers: {
    'x-share-token': share_token
  }
} */
)