diff --git a/README.md b/README.md index 26eadff7d..5da386090 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,40 @@ # Microsoft Graph JavaScript Client Library -[![npm version badge](https://img.shields.io/npm/v/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) [![Travis](https://travis-ci.org/microsoftgraph/msgraph-sdk-javascript.svg?maxAge=86400)](https://travis-ci.org/microsoftgraph/msgraph-sdk-javascript) [![Known Vulnerabilities](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript/badge.svg?maxAge=86400)](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript) [![Licence](https://img.shields.io/github/license/microsoftgraph/msgraph-sdk-javascript.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![Downloads](https://img.shields.io/npm/dm/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) +[![npm version badge](https://img.shields.io/npm/v/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) [![Known Vulnerabilities](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript/badge.svg?maxAge=86400)](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript) [![Licence](https://img.shields.io/github/license/microsoftgraph/msgraph-sdk-javascript.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/microsoftgraph/msgraph-sdk-javascript) [![Downloads](https://img.shields.io/npm/dm/@microsoft/microsoft-graph-client.svg?maxAge=86400)](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) 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](https://github.com/microsoftgraph/msgraph-typescript-typings) repository!** +- [Microsoft Graph JavaScript Client Library](#microsoft-graph-javascript-client-library) + - [Installation](#installation) + - [Via npm](#via-npm) + - [Via Script Tag](#via-script-tag) + - [Getting started](#getting-started) + - [1. Register your application](#1-register-your-application) + - [2. Create a Client Instance](#2-create-a-client-instance) + - [3. Make requests to the graph](#3-make-requests-to-the-graph) + - Documentation + - [HTTP Actions](docs/Actions.md) + - [Chained APIs to call Microsoft Graph](docs/CallingPattern.md) + - [OData system query options - Query Parameters](docs/QueryParameters.md) + - [Batch multiple requests into single HTTP request](docs/content/Batching.md) + - [Configurations to your request](docs/OtherAPIs.md) + - [Query](docs/OtherAPIs.md#QUERY) + - [Version](docs/OtherAPIs.md#VERSION) + - [Headers](docs/OtherAPIs.md#HEADER-AND-HEADERS) + - [Options](docs/OtherAPIs.md#OPTION-AND-OPTIONS) + - [MiddlewareOptions](docs/OtherAPIs.md#MIDDLEWAREOPTIONS) + - [ResponseType](docs/OtherAPIs.md#RESPONSETYPE) + - [Upload large files to OneDrive, Outlook, Print API](docs/tasks/LargeFileUploadTask.md) + - [Page Iteration](docs/tasks/PageIterator.md) + - [Getting Raw Response](docs/GettingRawResponse.md) + - [Creating an instance of TokenCredentialAuthenticationProvider](docs/TokenCredentialAuthenticationProvider.md) + - [Questions and comments](#questions-and-comments) + - [Contributing](#contributing) + - [Additional resources](#additional-resources) + - [Third Party Notices](#third-party-notices) + - [Security Reporting](#security-reporting) + - [License](#license) + - [We Value and Adhere to the Microsoft Open Source Code of Conduct](#we-value-and-adhere-to-the-microsoft-open-source-code-of-conduct) [![TypeScript demo](https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-javascript/master/types-demo.PNG)](https://github.com/microsoftgraph/msgraph-typescript-typings) @@ -16,10 +46,16 @@ The Microsoft Graph JavaScript client library is a lightweight wrapper around th npm install @microsoft/microsoft-graph-client ``` -import `@microsoft/microsoft-graph-client` into your module and also you will need polyfills for fetch like [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch). +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 - +* [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch). +* [cross-fetch](https://www.npmjs.com/package/cross-fetch) +* [whatwg-fetch](https://www.npmjs.com/package/whatwg-fetch) ```typescript -import "isomorphic-fetch"; +import "isomorphic-fetch"; // or import the fetch polyfill you installed import { Client } from "@microsoft/microsoft-graph-client"; ``` @@ -45,60 +81,25 @@ In case your browser doesn't have support for [Fetch](https://developer.mozilla. ``` ## Getting started - ### 1. Register your application -Register your application to use Microsoft Graph API using one of the following supported authentication portals: - -- [Microsoft Application Registration Portal](https://apps.dev.microsoft.com): Register a new application that works with Microsoft Accounts and/or organizational accounts using the unified V2 Authentication Endpoint. -- [Microsoft Azure Active Directory](https://manage.windowsazure.com): Register a new application in your tenant's Active Directory to support work or school users for your tenant or multiple tenants. - -### 2. Authenticate for the Microsoft Graph service - -The Microsoft Graph JavaScript Client Library has an adapter implementation for the following - - -- ([TokenCredentialAuthenticationProvider](src/authentication/TokenCredentialAuthenticationProvider.ts)) to support [Azure Identity TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md) (Azure Identity client library for JavaScript) which takes care of getting the `accessToken`. @azure/identity library does not ship with this library, user has to include it externally (For including @azure/identity, refer [this](https://www.npmjs.com/package/@azure/identity)). - - > Learn how to [create an instance of TokenCredentialAuthenticationProvider](./docs/TokenCredentialAuthenticationProvider.md). - -- ([ImplicitMSALAuthenticationProvider](src/ImplicitMSALAuthenticationProvider.ts)) for [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core) (Microsoft Authentication Library) which takes care of getting the `accessToken`. MSAL library does not ship with this library, user has to include it externally (For including MSAL, refer [this](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core#installation)). - - > Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./docs/ImplicitMSALAuthenticationProvider.md). - -User can integrate own preferred authentication library by implementing `IAuthenticationProvider` interface. Refer implementing [Custom Authentication Provider](./docs/CustomAuthenticationProvider.md). - -### 3. Initialize a Microsoft Graph Client object with an authentication provider - -An instance of the **Client** class handles requests to Microsoft Graph API and processing the responses. To create a new instance of this class, you need to provide an instance of [`IAuthenticationProvider`](src/IAuthenticationProvider.ts) which needs to be passed as a value for `authProvider` key in [`ClientOptions`](src/IClientOptions.ts) to a static initializer method `Client.initWithMiddleware`. +To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform. +Learn more about this - +- [Authentication and authorization basics for Microsoft Graph](https://docs.microsoft.com/en-us/graph/auth/auth-concepts) +- [Register your app with the Microsoft identity platform](https://docs.microsoft.com/en-us/graph/auth/auth-concepts) -#### For browser environment +### 2. Create a Client Instance -```typescript -const options = { - authProvider, // An instance created from previous step -}; -const Client = MicrosoftGraph.Client; -const client = Client.initWithMiddleware(options); -``` - -#### For node environment - -```typescript -import { Client } from "@microsoft/microsoft-graph-client"; +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. -const options = { - authProvider, // An instance created from previous step -}; -const client = Client.initWithMiddleware(options); -``` +For information on how to create a client instance, see [Creating Client Instance](./docs/CreatingClientInstance.md) -For more information on initializing client, refer [this document](./docs/CreatingClientInstance.md). -### 4. Make requests to the graph +### 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 be start with `client.api(path)` and end with an [action](./docs/Actions.md). +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](./docs/Actions.md). -Getting user details +Example of getting user details: ```typescript try { @@ -109,7 +110,7 @@ try { } ``` -Sending an email to the recipients +Example of sending an email to the recipients: ```typescript // Construct email object @@ -137,16 +138,6 @@ try { For more information, refer: [Calling Pattern](docs/CallingPattern.md), [Actions](docs/Actions.md), [Query Params](docs/QueryParameters.md), [API Methods](docs/OtherAPIs.md) and [more](docs/). -## Documentation - -- [Batching](docs/content/Batching.md) -- [Large File Upload Task](docs/tasks/LargeFileUploadTask.md) -- [Page Iterator](docs/tasks/PageIterator.md) -- [Actions](docs/Actions.md) -- [Query Parameters](docs/QueryParameters.md) -- [Other APIs](docs/OtherAPIs.md) -- [Getting Raw Response](docs/GettingRawResponse.md) - ## 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](https://github.com/microsoftgraph/msgraph-sdk-javascript/issues) section of this repository. @@ -157,11 +148,16 @@ Please see the [contributing guidelines](CONTRIBUTING.md). ## Additional resources -- [Microsoft Graph website](https://graph.microsoft.io) -- [Microsoft Graph TypeScript types](https://github.com/microsoftgraph/msgraph-typescript-typings/) -- [Build Angular single-page apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-angularspa) -- [Build Node.js Express apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-nodeexpressapp) -- [Office Dev Center](http://dev.office.com/) +- [Microsoft Graph website](https://graph.microsoft.io) + +- The Microsoft Graph TypeScript definitions enable editors to provide intellisense on Microsoft Graph objects including users, messages, and groups. + - [@microsoft/microsoft-graph-types](https://www.npmjs.com/package/@microsoft/microsoft-graph-types) or [@types/microsoft-graph](https://www.npmjs.com/package/@types/microsoft-graph) + - [@microsoft/microsoft-graph-types-beta](https://www.npmjs.com/package/@microsoft/microsoft-graph-types-beta) +- [Build React Native apps with Microsoft Graph](https://docs.microsoft.com/en-us/graph/tutorials/react-native) +- [Build Angular single-page apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-angularspa) +- [Build Node.js Express apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-nodeexpressapp) +- [Microsoft Graph Toolkit: UI Components and Authentication Providers for Microsoft Graph](https://docs.microsoft.com/en-us/graph/toolkit/overview) +- [Office Dev Center](http://dev.office.com/) ## Third Party Notices diff --git a/docs/CreatingClientInstance.md b/docs/CreatingClientInstance.md index 52e81828b..2e4c493fe 100644 --- a/docs/CreatingClientInstance.md +++ b/docs/CreatingClientInstance.md @@ -4,35 +4,43 @@ Initialization of the Client can be done in one of below two ways ## 1. Create With ClientOptions [Recommended] +The Microsoft Graph SDK client configures a default set of middleware that allows the SDK to communicate with the Microsoft Graph endpoints. This default set is customizable, allowing you to change the behavior of the client + In order to instantiate a Client object, one has to pass in the `authProvider` or `middleware` chain in [ClientOptions](../src/IClientOptions.ts). ### Option A. Default Middleware chain -Pass an instance of a class which implements [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface as `authProvider` in [ClientOptions](../src/IClientOptions.ts), which will instantiate the Client with default set of middleware chain. +The default middleware chain contains consecutively chained instances of the following: +- [AuthenticationHandler](../src/middleware/AuthenticationHandler.ts) +- [RetryHandler](../src/middleware/RetryHandler.ts) +- [RedirectHandler](../src/middleware/RedirectHandler.ts) +- [TelemetryHandler](../src/middleware/TelemetryHandler.ts) +- [HTTPMessageHandler](../src/middleware/HTTPMessageHandler.ts) -Library is shipped with one such authentication provider named [ImplicitMSALAuthenticationProvider](../src/ImplicitMSALAuthenticationProvider.ts). This ImplicitMSALAuthenticationProvider depends on an authentication library [msal.js](https://github.com/AzureAD/microsoft-authentication-library-for-js) which is not shipped along with the library, one has to externally include msal.js to use ImplicitMSALAuthenticationProvider. +To create a client instance with the default middleware chain: -```typescript -// Instantiating Client with ImplicitMSALAuthenticationProvider +1. Create an instance of a class which implements [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface. This class should contain the logic to get the access token to be passed to the Microsoft Graph API. -// An Optional options for initializing the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/MSAL-basics#configuration-options -const msalConfig = { - auth: { - clientId: // Client Id of the registered application - }, -}; +2. Pass the instance as `authProvider` in [ClientOptions](../src/IClientOptions.ts) to instantiate the Client which will create and set the default middleware chain. -// Important Note: This library implements loginPopup and acquireTokenPopup flow, remember this while initializing the msal -// Initialize the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js#1-instantiate-the-useragentapplication -const msalApplication = new UserAgentApplication(msalConfig); -const options = new MicrosoftGraph.MSALAuthenticationProviderOptions(); // An array of graph scopes +```typescript let clientOptions: ClientOptions = { - authProvider: new ImplicitMSALAuthenticationProvider(msalApplication, options) + authProvider: new YourAuthProviderClass(), }; const client = Client.initWithMiddleware(clientOptions); ``` -Want to use own preferred authentication library, for which one has to implement [AuthenticationProvider](../src/IAuthenticationProvider.ts) interface and pass in the instance of it as `authProvider` in [ClientOptions](../src/IClientOptions.ts). +The Microsoft Graph JavaScript Client Library has an adapter implementation for the following - + +- ([TokenCredentialAuthenticationProvider](src/authentication/TokenCredentialAuthenticationProvider.ts)) to support [Azure Identity TokenCredential](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md) (Azure Identity client library for JavaScript) which takes care of getting the `accessToken`. @azure/identity library does not ship with this library, user has to include it externally (For including @azure/identity, refer [this](https://www.npmjs.com/package/@azure/identity)). + + > Learn how to [create an instance of TokenCredentialAuthenticationProvider](./TokenCredentialAuthenticationProvider.md). + +- **DEPRECATED** ([ImplicitMSALAuthenticationProvider](src/ImplicitMSALAuthenticationProvider.ts)) for [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core) (Microsoft Authentication Library) which takes care of getting the `accessToken`. MSAL library does not ship with this library, user has to include it externally (For including MSAL, refer [this](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-core#installation)). + + > Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./ImplicitMSALAuthenticationProvider.md). + +**User can integrate any preferred authentication library by implementing `IAuthenticationProvider` interface**. Refer implementing [Custom Authentication Provider](./CustomAuthenticationProvider.md) for more detailed information. ```typescript let clientOptions: ClientOptions = { @@ -42,11 +50,14 @@ let clientOptions: ClientOptions = { const client = Client.initWithMiddleware(clientOptions); ``` -Refer, [custom authentication provider](./CustomAuthenticationProvider.md) for more detailed information. - ### Option B. Custom Middleware chain -Want to have complete control over the request and the response objects, one can provide his own chain of middleware. Have to pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts). +The Microsoft Graph SDK client allows configuring custom middleware, allowing you to change the behavior of the client. For example, you can insert customized logging, or add a test handler to simulate specific scenarios. + +To create a client instance with the custom middleware chain: + +1. Refer to [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information. +2. Create the middleware chain and pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts). ```typescript let clientOptions: ClientOptions = { @@ -56,8 +67,6 @@ let clientOptions: ClientOptions = { const client = Client.initWithMiddleware(clientOptions); ``` -Refer, [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information. - ## 2. Create With Options Pass an [authProvider function](../src/IAuthProvider.ts) in [Options](../src/IOptions.ts) while initializing the Client. In this case, user has to provide his own implementation for getting and refreshing accessToken. A callback will be passed into this authProvider function, accessToken or error needs to be passed in to that callback. diff --git a/docs/OtherAPIs.md b/docs/OtherAPIs.md index 74f9a2a8c..577cc492a 100644 --- a/docs/OtherAPIs.md +++ b/docs/OtherAPIs.md @@ -81,7 +81,7 @@ try { You can pass in additional request options through `.option()` and `.options()`, either individually or in a dictionary. Options can be [node specific](https://github.com/bitinn/node-fetch#options) or [from fetch standard](https://fetch.spec.whatwg.org/#requestinit) ```typescript -let HttpProxyAgent = require('http-proxy-agent'); +let HttpProxyAgent = require('https-proxy-agent'); try { // HTTP/HTTPS proxy to connect to let proxy = ;