Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@microsoft/microsoft-graph-client

microsoftgraph2.4mMIT3.0.7TypeScript support: included

Microsoft Graph Client Library

Microsoft, Graph, SDK, JavaScript, Client

readme

Microsoft Graph JavaScript Client Library

npm version badge Known Vulnerabilities Licence code style: prettier Downloads

The Microsoft Graph JavaScript client library is a lightweight wrapper around the Microsoft Graph API that can be used server-side and in the browser.

Looking for IntelliSense on models (Users, Groups, etc.)? Check out the Microsoft Graph Types v1.0 and beta!!

TypeScript demo

Node version requirement

Node.js 12 LTS or higher. The active Long Term Service (LTS) version of Node.js is used for on-going testing of existing and upcoming product features.

For Node.js 18 users, it is recommended to disable the experimental fetch feature by supplying the --no-experimental-fetch command-line flag while using the Microsoft Graph JavaScript client library.

Installation

Via npm

npm install @microsoft/microsoft-graph-client

import @microsoft/microsoft-graph-client into your module.

Also, you will need to import any fetch polyfill which suits your requirements. Following are some fetch polyfills -

import "isomorphic-fetch"; // or import the fetch polyfill you installed
import { Client } from "@microsoft/microsoft-graph-client";

Via Script Tag

Include graph-js-sdk.js in your HTML page.

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@microsoft/microsoft-graph-client/lib/graph-js-sdk.js"></script>

In case your browser doesn't have support for Fetch [support] or Promise [support], you need to use polyfills like github/fetch for fetch and es6-promise for promise.

<!-- polyfilling promise -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/es6-promise/dist/es6-promise.auto.min.js"></script>

<!-- polyfilling fetch -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/whatwg-fetch/dist/fetch.umd.min.js"></script>

<!-- depending on your browser you might wanna include babel polyfill -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@babel/polyfill@7.4.4/dist/polyfill.min.js"></script>

Getting started

1. Register your application

To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform. Learn more about this -

2. Create a Client Instance

The Microsoft Graph client is designed to make it simple to make calls to Microsoft Graph. You can use a single client instance for the lifetime of the application.

For information on how to create a client instance, see Creating Client Instance

3. Make requests to the graph

Once you have authentication setup and an instance of Client, you can begin to make calls to the service. All requests should start with client.api(path) and end with an action.

Example of getting user details:

try {
    let userDetails = await client.api("/me").get();
    console.log(userDetails);
} catch (error) {
    throw error;
}

Example of sending an email to the recipients:

// Construct email object
const mail = {
    subject: "Microsoft Graph JavaScript Sample",
    toRecipients: [
        {
            emailAddress: {
                address: "example@example.com",
            },
        },
    ],
    body: {
        content: "<h1>MicrosoftGraph JavaScript Sample</h1>Check out https://github.com/microsoftgraph/msgraph-sdk-javascript",
        contentType: "html",
    },
};
try {
    let response = await client.api("/me/sendMail").post({ message: mail });
    console.log(response);
} catch (error) {
    throw error;
}

For more information, refer: Calling Pattern, Actions, Query Params, API Methods and more.

Samples and tutorials

Step-by-step training exercises that guide you through creating a basic application that accesses data via the Microsoft Graph:

The Microsoft Graph JavaScript SDK provides a TokenCredentialAuthenticationProvider to authenticate using the @azure/identity auth library. Learn more:

The Microsoft Graph JavaScript SDK provides a LargeFileUploadTask to upload large files to OneDrive, Outlook and Print API:

Questions and comments

We'd love to get your feedback about the Microsoft Graph JavaScript client library. You can send your questions and suggestions to us in the Issues section of this repository.

Contributing

Please see the contributing guidelines.

Additional resources

Tips and Tricks

Third Party Notices

See Third Party Notices for information on the packages that are included in the package.json

Security Reporting

If you find a security issue with our libraries or services please report it to secure@microsoft.com with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License");

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

changelog

Changelog

1.4.0

New Features

  • Added Search query param functionality

Bug Fixes

1.3.0

New Features

  • Support for Large File upload [#1, #2]
  • Batching made easy [#1, #2]

Bug Fixes

1.2.0

Updates

  • Two output js files, one with polyfills for Fetch-API and ES6-Promises lib/graph-js-sdk-web.js and one without lib/graph-js-sdk-core.js [Refer README.md for usage]
  • Enum for ResponseType, which lists down the available ResponseType options in autocomplete

Bug Fix

  • Cannot access the property "request-id" of undefined in GraphError handling

1.1.0

New Features

  • Support for Multipart POST request

Updates

  • Light weight FetchAPI dependency (in replacement for SuperAgent)

Bug Fixes

  • Updated putStream and getStream to work for all sized files
  • Added obfuscation for output js file (graph-js-sdk-web.js)
  • Updated versions of mocha and chai to 5.2.0 and 4.1.2 to fix security vulnerability in growl (which is a dependency of mocha)
  • Running unit test files under types directory
  • Compiling ts files

1.0.0

  • Added tests for new Graph functionality - Delta query, Extensibility, OneNote, and more.

0.4.0

  • Add support for ES5. Make sure to use graph-js-sdk-web.js for web apps
  • Removed iterator helper method.

0.3.1

  • Support for Node.js versions 4 and 5

0.3.0

  • Migrated away from typings in client library core and TypeScript sample

0.2.2

  • Updated SuperAgent to version 3.3.0

0.2.0

  • Breaking change for existing apps - Initialize the client library with MicrosoftGraph.Client.init({...}). See the updated usage section below for code samples.
  • Added response handling tests to simulate Graph calls
  • Added type declarations file for core client library, which adds intellisense for chained methods.