You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* creating table of contents
* CreateClient md changes, more links in toc
* Adding additional resources
* Removing travis badge
* Apply suggestions from code review
Co-authored-by: Mustafa Zengin <muzengin@microsoft.com>
* replace - with :
Co-authored-by: Mustafa Zengin <muzengin@microsoft.com>
Copy file name to clipboardExpand all lines: README.md
+61-65
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,40 @@
1
1
# Microsoft Graph JavaScript Client Library
2
2
3
-
[](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)[](https://travis-ci.org/microsoftgraph/msgraph-sdk-javascript)[](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript)[](https://github.com/microsoftgraph/msgraph-sdk-javascript)[](https://github.com/microsoftgraph/msgraph-sdk-javascript)[](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)
3
+
[](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)[](https://snyk.io/test/github/microsoftgraph/msgraph-sdk-javascript)[](https://github.com/microsoftgraph/msgraph-sdk-javascript)[](https://github.com/microsoftgraph/msgraph-sdk-javascript)[](https://www.npmjs.com/package/@microsoft/microsoft-graph-client)
4
4
5
5
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.
6
6
7
-
**Looking for IntelliSense on models (Users, Groups, etc.)? Check out the [Microsoft Graph Types](https://github.com/microsoftgraph/msgraph-typescript-typings) repository!**
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).
52
+
import `@microsoft/microsoft-graph-client` into your module.
53
+
54
+
Also, you will need to import any fetch polyfill which suits your requirements.
@@ -48,60 +84,25 @@ In case your browser doesn't have support for [Fetch](https://developer.mozilla.
48
84
```
49
85
50
86
## Getting started
51
-
52
87
### 1. Register your application
53
88
54
-
Register your application to use Microsoft Graph API using one of the following supported authentication portals:
55
-
56
-
-[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.
57
-
-[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.
58
-
59
-
### 2. Authenticate for the Microsoft Graph service
60
-
61
-
The Microsoft Graph JavaScript Client Library has an adapter implementation for the following -
62
-
63
-
- ([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)).
64
-
65
-
> Learn how to [create an instance of TokenCredentialAuthenticationProvider](./docs/TokenCredentialAuthenticationProvider.md).
66
-
67
-
- ([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)).
68
-
69
-
> Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./docs/ImplicitMSALAuthenticationProvider.md).
70
-
71
-
User can integrate own preferred authentication library by implementing `IAuthenticationProvider` interface. Refer implementing [Custom Authentication Provider](./docs/CustomAuthenticationProvider.md).
72
-
73
-
### 3. Initialize a Microsoft Graph Client object with an authentication provider
74
-
75
-
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`.
89
+
To call Microsoft Graph, your app must acquire an access token from the Microsoft identity platform.
90
+
Learn more about this -
91
+
-[Authentication and authorization basics for Microsoft Graph](https://docs.microsoft.com/en-us/graph/auth/auth-concepts)
92
+
-[Register your app with the Microsoft identity platform](https://docs.microsoft.com/en-us/graph/auth/auth-concepts)
76
93
77
-
#### For browser environment
94
+
###2. Create a Client Instance
78
95
79
-
```typescript
80
-
const options = {
81
-
authProvider, // An instance created from previous step
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.
91
97
92
-
const options = {
93
-
authProvider, // An instance created from previous step
94
-
};
95
-
const client =Client.initWithMiddleware(options);
96
-
```
98
+
For information on how to create a client instance, see [Creating Client Instance](./docs/CreatingClientInstance.md)
97
99
98
-
For more information on initializing client, refer [this document](./docs/CreatingClientInstance.md).
99
100
100
-
### 4. Make requests to the graph
101
+
### 3. Make requests to the graph
101
102
102
-
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).
103
+
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).
103
104
104
-
Getting user details
105
+
Example of getting user details:
105
106
106
107
```typescript
107
108
try {
@@ -112,7 +113,7 @@ try {
112
113
}
113
114
```
114
115
115
-
Sending an email to the recipients
116
+
Example of sending an email to the recipients:
116
117
117
118
```typescript
118
119
// Construct email object
@@ -140,16 +141,6 @@ try {
140
141
141
142
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/).
-[Getting Raw Response](docs/GettingRawResponse.md)
152
-
153
144
## Questions and comments
154
145
155
146
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.
@@ -160,11 +151,16 @@ Please see the [contributing guidelines](CONTRIBUTING.md).
- The Microsoft Graph TypeScript definitions enable editors to provide intellisense on Microsoft Graph objects including users, messages, and groups.
157
+
-[@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)
Copy file name to clipboardExpand all lines: docs/CreatingClientInstance.md
+30-21
Original file line number
Diff line number
Diff line change
@@ -4,35 +4,43 @@ Initialization of the Client can be done in one of below two ways
4
4
5
5
## 1. Create With ClientOptions [Recommended]
6
6
7
+
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
8
+
7
9
In order to instantiate a Client object, one has to pass in the `authProvider` or `middleware` chain in [ClientOptions](../src/IClientOptions.ts).
8
10
9
11
### Option A. Default Middleware chain
10
12
11
-
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.
13
+
The default middleware chain contains consecutively chained instances of the following:
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.
20
+
To create a client instance with the default middleware chain:
14
21
15
-
```typescript
16
-
// Instantiating Client with ImplicitMSALAuthenticationProvider
22
+
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.
17
23
18
-
// An Optional options for initializing the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js/wiki/MSAL-basics#configuration-options
19
-
const msalConfig = {
20
-
auth: {
21
-
clientId: <CLIENT_ID> // Client Id of the registered application
22
-
},
23
-
};
24
+
2. Pass the instance as `authProvider` in [ClientOptions](../src/IClientOptions.ts) to instantiate the Client which will create and set the default middleware chain.
24
25
25
-
// Important Note: This library implements loginPopup and acquireTokenPopup flow, remember this while initializing the msal
26
-
// Initialize the MSAL @see https://github.com/AzureAD/microsoft-authentication-library-for-js#1-instantiate-the-useragentapplication
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).
33
+
The Microsoft Graph JavaScript Client Library has an adapter implementation for the following -
34
+
35
+
- ([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)).
36
+
37
+
> Learn how to [create an instance of TokenCredentialAuthenticationProvider](./TokenCredentialAuthenticationProvider.md).
38
+
39
+
-**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)).
40
+
41
+
> Learn how to [create an instance of ImplicitMSALAuthenticationProvider](./ImplicitMSALAuthenticationProvider.md).
42
+
43
+
**User can integrate any preferred authentication library by implementing `IAuthenticationProvider` interface**. Refer implementing [Custom Authentication Provider](./CustomAuthenticationProvider.md) for more detailed information.
36
44
37
45
```typescript
38
46
let clientOptions:ClientOptions= {
@@ -42,11 +50,14 @@ let clientOptions: ClientOptions = {
Refer, [custom authentication provider](./CustomAuthenticationProvider.md) for more detailed information.
46
-
47
53
### Option B. Custom Middleware chain
48
54
49
-
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).
55
+
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.
56
+
57
+
To create a client instance with the custom middleware chain:
58
+
59
+
1. Refer to [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information.
60
+
2. Create the middleware chain and pass first middleware in the chain as `middleware` in [ClientOptions](../src/IClientOptions.ts).
50
61
51
62
```typescript
52
63
let clientOptions:ClientOptions= {
@@ -56,8 +67,6 @@ let clientOptions: ClientOptions = {
Refer, [custom middleware chain](./CustomMiddlewareChain.md) for more detailed information.
60
-
61
70
## 2. Create With Options
62
71
63
72
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.
Copy file name to clipboardExpand all lines: docs/OtherAPIs.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -81,7 +81,7 @@ try {
81
81
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)
0 commit comments