onedrive-api

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
  });

Changelog