onedrive-api
v1.1.1
Published
OneDrive module for communicating with oneDrive API. Built using functional programming pattern
Downloads
42,907
Readme
onedrive-api
OneDrive API module for NodeJS. This module handels operations with OneDrive API. For authenticating with OneDrive, we suggest using OS solutions like simple-oauth2. We are accepting pull requests for any missing features
Install
npm install onedrive-api
API
Items
- createFolder
- createLink
- customEndpoint
- delete
- download
- partialDownload
- getMetadata
- listChildren
- preview
- sync
- thumbnails
- update
- uploadSimple
- uploadSession
Examples
Require module
// JavaScript
const oneDriveAPI = require("onedrive-api")
// TypeScript
import oneDriveAPI from "onedrive-api";
oneDriveAPI.items
.listChildren({
accessToken: accessToken,
itemId: "root",
drive: "me", // 'me' | 'user' | 'drive' | 'group' | 'site'
driveId: "", // BLANK | {user_id} | {drive_id} | {group_id} | {sharepoint_site_id}
})
.then((childrens) => {
// list all children of given root directory
//
// console.log(childrens);
// returns body of https://dev.onedrive.com/items/list.htm#response
});
items.createFolder
Create Folder
Returns: Promise<Object> - folder meta object
| Param | Type | Default | Description |
|--------------------| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| [params.itemId] | String | root | Item id |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.name | String | | New folder name |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
oneDriveAPI.items
.createFolder({
accessToken: accessToken,
rootItemId: "root",
name: "Folder name",
})
.then((item) => {
// console.log(item)
// returns body of https://dev.onedrive.com/items/create.htm#response
});
items.createLink
Get long-lived embeddable sharing-link
Returns: Promise<Object> - Items sharing link object
| Param | Type | Default | Description |
|--------------------|---------------------|-------------|-------------------------------------------------------------------------------------------------|
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.itemId | String | | Item id |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| params.type | String | embed
| The type of sharing link. Either view
, edit
or embed
. |
| params.body | Object | | Request body |
oneDriveAPI.items
.createLink({
accessToken: accessToken,
itemId: createdFile.id,
type: "view",
body: {
password: "123"
}
})
.then((linkObject) => {
// console.log(linkObject);
});
items.customEndpoint
Call custom endpoint with JSON response.
Returns: Promise<Object> - JSON object.
| Param | Type | Description | | | ------------------ | ------------------- | ------------------------------------------- | ------------- | | params | Object | | | | params.accessToken | String | OneDrive access token | | | params.url | String | Endpoint url. Ex. 'groups/{groupId}/drives' | | | params.body | Object | false | Optional body | | params.method | String | Optional method | |
oneDriveAPI.items
.customEndpoint({
accessToken: accessToken,
url: "me/drive/special/cameraroll",
// method: 'GET'
// body: {}
})
.then((r) => {
console.log(r);
})
.catch((e) => {
console.log(e);
});
items.delete
Delete item (file or folder)
Returns: Promise<void> - The promise will throw HttpError if the delete API fail.
| Param | Type | Default | Description |
| ------------------ | ------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemId | String | | Item id |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
oneDriveAPI.items
.delete({
accessToken: accessToken,
itemId: createdFolder.id,
})
.then(() => {
// file is deleted
})
.catch((error) => {
// error.response.statusCode => error code
// error.response.statusMessage => error message
});
items.download
Download item content
Returns: Promise - A promise with the result being a Readable stream
with item's content
| Param | Type | Default | Description |
|--------------------| ------------------- | ----------- |-------------------------------------------------------------------------------------------------|
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemId | String | | item id |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| params.format | String | undefined
| Converts the content to specified format. Format options: 'glb'
/'html'
/'jpg'
/'pdf'
|
const promise = oneDriveAPI.items.download({
accessToken: accessToken,
itemPath: 'path/to/file/file.pdf',
});
promise.then((fileStream) => fileStream.pipe(SomeWritableStream));
items.partialDownload
Download item content partially. You must either provide graphDownloadURL
or the itemId
to download the file.
If only the itemId
is provided, the function will try to get the download URL for you with additional getMetadata()
function call.
Returns: Promise<ReadableStream> - A promise with the result is a Readable stream
with partial item's content
| Param | Type | Default | Description |
| ----------------------- | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.graphDownloadURL | String | | @microsoft.graph.downloadUrl
of the item |
| params.itemId | String | | item id. This parameter will be skipped if graphDownloadURL
is provided. |
| params.itemPath | String | | Item path (ignored if itemId
or graphDownloadURL
is set) |
| params.bytesFrom | Number | 0
| Starting download byte. |
| params.bytesTo | Number | | Ending byte to download. Must be set |
| params.drive | String | 'me'
| Only be used if only params.itemId
is set and params.graphDownloadURL
is undefined. If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
const partialPromise = oneDriveAPI.items.partialDownload({
accessToken: accessToken,
bytesFrom: 0, // start byte
bytesTo: 1034, // to byte
graphDownloadURL: createdItem["@microsoft.graph.downloadUrl"],
// optional params
itemId: createdItem.id, // only be used when `graphDownloadURL` is NOT provided
drive: "me", // only be used when only `itemId` is provided
driveId: "me", // only be required when `drive` is provided
});
partialPromise.then((fileStream) => fileStream.pipe(SomeWritableStream));
items.getMetadata
Get items metadata (file or folder)
Returns: Promise<Object> - Item's metadata
| Param | Type | Default | Description |
| ------------------ | ------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.itemId | String | | Item id |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
oneDriveAPI.items
.getMetadata({
accessToken: accessToken,
itemId: createdFolder.id,
})
.then((item) => {
// console.log(item);
// returns body of https://dev.onedrive.com/items/update.htm#response
});
items.listChildren
List childrens
Returns: Promise<Object> - object of children items
| Param | Type | Default | Description |
|------------------------| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| [params.itemId] | String | root | Item id |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| params.queryParameters | String | undefined
| OData system query options. |
oneDriveAPI.items
.listChildren({
accessToken: accessToken,
itemId: createdFolder.id,
query: "?$filter=createdDateTime le 2020-07-07T12:56:51.577Z",
})
.then((childrens) => {
// console.log(childrens);
// returns body of https://dev.onedrive.com/items/list.htm#response
});
items.preview
Create short-lived embeddable preview url
Returns: Promise<Object> - object with embeddable url
| Param | Type | Default | Description |
|--------------------|---------------------|-------------|-------------------------------------------------------------------------------------------------|
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.itemId | String | | Item id |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| params.body | Object | | Request body |
oneDriveAPI.items
.preview({
accessToken: accessToken,
itemId: createdFile.id,
body: {
zoom: 1
}
})
.then((urlObject) => {
// console.log(urlObject);
});
items.sync
Sync changes
Returns: Promise<Object> - Object represent the changes since last sync
| Param | Type | Description | | ------------------ | ------------------- | --------------------------------------------------- | | params | Object | | | params.accessToken | String | OneDrive access token | | params.next | String | nextLink (or deltaLink returned from last session). |
oneDriveAPI.items
.sync({
accessToken: accessToken,
next: "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)",
})
.then((item) => {
// console.log(item);
// returns body of https://docs.microsoft.com/nb-no/onedrive/developer/rest-api/api/driveitem_delta?view=odsp-graph-online#response
});
items.thumbnails
Retrieve thumbnails for an item
Returns: Promise<Object> - object with thumbnail urls
| Param | Type | Default | Description |
|------------------------|---------------------|-------------|-------------------------------------------------------------------------------------------------|
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.itemId | String | | Item id |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| params.queryParameters | String | | OData query parameters |
oneDriveAPI.items
.preview({
accessToken: accessToken,
itemId: createdFile.id
})
.then((thumbnailsObject) => {
// console.log(thumbnailsObject);
});
items.update
Update item metadata
Returns: Promise<Object> - Item meta object
| Param | Type | Default | Description |
| ------------------ | ------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.itemId | String | | Item id |
| params.itemPath | String | | Item path (ignored if itemId
is set) |
| params.toUpdate | Object | | Object to update |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
oneDriveAPI.items
.update({
accessToken: accessToken,
itemId: createdFolder.id,
toUpdate: {
name: "newFolderName",
},
})
.then((item) => {
// console.log(item);
// returns body of https://dev.onedrive.com/items/update.htm#response
});
items.uploadSimple
Create file with simple upload
Returns: Promise<Object> - Item
| Param | Type | Default | Description |
| --------------------- | ------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.filename | String | | File name |
| [params.parentId] | String | root | Parent id |
| [params.parentPath] | String | | Parent path (if parentPath is defined, than parentId is ignored) |
| params.readableStream | Object | | Readable Stream with file's content |
| params.drive | String | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
oneDriveAPI.items
.uploadSimple({
accessToken: accessToken,
filename: filename,
readableStream: readableStream,
})
.then((item) => {
// console.log(item);
// returns body of https://dev.onedrive.com/items/upload_put.htm#response
});
items.uploadSession
Create a file with session upload. Use this for the files over 4MB. This is a synchronous wrapper around asynchronous method, which means that on the failed upload you can't resume the upload but need to retry the implementation. I am accepting PRs for asynchronous implementation.
Returns: Promise<Object> - Item
| Param | Type | Default | Description |
| ----------------------- | --------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| params | Object | | |
| params.accessToken | String | | OneDrive access token |
| params.filename | String | | File name |
| params.fileSize | Number | | Size of the file |
| [params.parentId] | String | root | Parent id |
| [params.parentPath] | String | | Parent path (if parentPath is defined, than parentId is ignored) |
| params.readableStream | Object | | Readable Stream with file's content |
| params.drive | string | 'me'
| If it's set to be either 'user'
/'drive'
/'group'
/'site'
, params.driveId
has to be set. |
| params.driveId | String | undefined
| The id of the drive that was shared to you. Must be set if params.drive
is set. |
| [params.chunksToUpload] | Number | 20 | Chunks to upload per request. More chunks per request requires more RAM |
| process | function | | A callback emit a variable represent the bytes that were transferred |
oneDriveAPI.items
.uploadSession(
{
accessToken: accessToken,
filename: filename,
fileSize: fileSize,
readableStream: readableStream,
},
(bytesUploaded) => {
console.log(bytesUploaded);
},
)
.then((item) => {
// console.log(item);
// returns body of https://docs.microsoft.com/en-us/onedrive/developer/rest-api/api/driveitem_createuploadsession?view=odsp-graph-online#http-response
});