Skip to content

Commit cd4e64e

Browse files
rkodevrkodev
committed
Draft readme copy for packages
1 parent bc7f59f commit cd4e64e

3 files changed

Lines changed: 262 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
Get started with the Microsoft Graph SDK for Typescript by integrating the [Microsoft Graph API](https://docs.microsoft.com/graph/overview) into your Typescript application!
44

5-
> **Note:** this SDK allows you to build applications using the [v1.0](https://docs.microsoft.com/graph/use-the-api#version) of Microsoft Graph. If you want to try the latest Microsoft Graph APIs.
5+
> **Note:** this SDK allows you to build applications using the [v1.0](https://docs.microsoft.com/graph/use-the-api#version) of Microsoft Graph. If you want to try the latest Microsoft Graph APIs, use our [beta SDK](https://github.com/microsoftgraph/msgraph-beta-sdk-typescript) instead.
6+
67
>
78
> **Note:** the Microsoft Graph Typescript SDK is currently in Pre-Release.
89

‎packages/msgraph-sdk-admin/README.md‎

Lines changed: 73 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,80 @@
11
# `@microsoft/msgraph-sdk-admin`
22

3-
> TODO: description
3+
Get started with the Microsoft Graph SDK for Typescript by integrating the [Microsoft Graph API](https://docs.microsoft.com/graph/overview) into your Typescript application!
4+
5+
> **Note:** this package is complementary package that allows you to build applications using the [v1.0](https://docs.microsoft.com/graph/use-the-api#version) of Microsoft Graph. . If you want to try the latest Microsoft Graph APIs, use our [beta SDK](https://github.com/microsoftgraph/msgraph-beta-sdk-typescript) instead.
6+
7+
This package provides a fluent API for interacting with Microsoft Graph administrative functions.
8+
9+
> **Note:** This package is not a standalone package and is most functional when used in conjunction with the main Microsoft Graph SDK. Please refer to the installation and setting up of [@microsoft/msgraph-sdk](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/README.md) for more information on setting up and using the SDK.
410
5-
## Usage
611

12+
## Installation
13+
14+
To install the package, use npm:
15+
16+
```shell
17+
# this will install the main package
18+
npm install @microsoft/msgraph-sdk
19+
# this will install the authentication provider for Azure Identity / Microsoft Entra
20+
npm install @microsoft/kiota-authentication-azure @azure/identity
21+
# this will install the fluent API package for the administrative API paths
22+
npm install @microsoft/msgraph-sdk-admin
723
```
8-
const msgraphSdkJavascriptAdmin = require('@microsoft/msgraph-sdk-admin');
924

10-
// TODO: DEMONSTRATE API
25+
## Usage
26+
27+
Here is an example of how to use the package:
28+
29+
```typescript
30+
import { createGraphServiceClient, GraphRequestAdapter } from "@microsoft/msgraph-sdk";
31+
import { AzureIdentityAuthenticationProvider } from "@microsoft/kiota-authentication-azure";
32+
import { ClientSecretCredential } from "@azure/identity";
33+
import "@microsoft/msgraph-sdk-admin"
34+
35+
// Create a credential using ClientSecretCredential
36+
const credential = new ClientSecretCredential(
37+
'YOUR_TENANT_ID',
38+
'YOUR_CLIENT_ID',
39+
'YOUR_CLIENT_SECRET',
40+
);
41+
42+
// Create an authentication provider
43+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["https://graph.microsoft.com/.default"]);
44+
45+
// Create a request adapter
46+
const requestAdapter = new GraphRequestAdapter(authProvider);
47+
48+
// Create a GraphServiceClient
49+
const graphServiceClient = createGraphServiceClient(requestAdapter);
50+
51+
// Use the GraphServiceClient to make requests by including the appropriate API calls package
52+
// e.g graphServiceClient.admin.(complete your call)
53+
1154
```
55+
56+
## Documentation
57+
58+
For more detailed documentation, see:
59+
60+
* [Overview](https://docs.microsoft.com/graph/overview)
61+
* [Collections](https://docs.microsoft.com/graph/sdks/paging)
62+
* [Making requests](https://docs.microsoft.com/graph/sdks/create-requests)
63+
* [Known issues](https://github.com/MicrosoftGraph/msgraph-sdk-typescript/issues)
64+
* [Contributions](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/CONTRIBUTING.md)
65+
66+
## Issues
67+
68+
For known issues, see [issues](https://github.com/MicrosoftGraph/msgraph-sdk-typescript/issues).
69+
70+
## Contributions
71+
72+
The Microsoft Graph SDK is open for contribution. To contribute to this project, see [Contributing](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/CONTRIBUTING.md).
73+
74+
## License
75+
76+
Licensed under the [MIT license](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/LICENSE).
77+
78+
## Third-party notices
79+
80+
[Third-party notices](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/LICENSE)

‎packages/msgraph-sdk/README.md‎

Lines changed: 187 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,193 @@
1-
# `@microsoft/msgraph-sdk`
1+
# Microsoft Graph SDK for Typescript
22

3-
> TODO: description
3+
Get started with the Microsoft Graph SDK for Typescript by integrating the [Microsoft Graph API](https://docs.microsoft.com/graph/overview) into your Typescript application!
44

5-
## Usage
5+
> **Note:** this SDK allows you to build applications using the [v1.0](https://docs.microsoft.com/graph/use-the-api#version) of Microsoft Graph. If you want to try the latest Microsoft Graph APIs, use our [beta SDK](https://github.com/microsoftgraph/msgraph-beta-sdk-typescript) instead.
66
7+
>
8+
> **Note:** the Microsoft Graph Typescript SDK is currently in Pre-Release.
9+
10+
## 1. Installation
11+
12+
```shell
13+
# this will install the main package
14+
npm install @microsoft/msgraph-sdk
15+
# this will install the authentication provider for Azure Identity / Microsoft Entra
16+
npm install @microsoft/kiota-authentication-azure @azure/identity
17+
# this will install the fluent API package for the users API paths (Replace with required package)
18+
npm install @microsoft/msgraph-sdk-users
19+
```
20+
21+
## 2. Getting started
22+
23+
> Note: we are working to add the getting started information for Typescript to our public documentation, in the meantime the following sample should help you getting started.
24+
25+
### 2.1 Register your application
26+
27+
Register your application by following the steps at [Register your app with the Microsoft Identity Platform](https://docs.microsoft.com/graph/auth-register-app-v2).
28+
29+
### 2.2 Create an AuthenticationProvider object
30+
31+
An instance of the **GraphServiceClient** class handles building client. To create a new instance of this class, you need to provide an instance of **AuthenticationProvider**, which can authenticate requests to Microsoft Graph.
32+
33+
<!-- TODO restore that and remove the snippets below once the SDK hits GA and the public documentation has been updated -->
34+
<!-- For an example of how to get an authentication provider, see [choose a Microsoft Graph authentication provider](https://docs.microsoft.com/graph/sdks/choose-authentication-providers?tabs=typescript). -->
35+
36+
#### 2.2.1 Authorization Code Provider
37+
38+
```TypeScript
39+
// @azure/identity
40+
const credential = new AuthorizationCodeCredential(
41+
'YOUR_TENANT_ID',
42+
'YOUR_CLIENT_ID',
43+
'YOUR_CLIENT_SECRET',
44+
'AUTHORIZATION_CODE',
45+
'REDIRECT_URL',
46+
);
47+
48+
// @microsoft/kiota-authentication-azure
49+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["User.Read"]);
50+
```
51+
52+
#### 2.2.2 Client Credentials Provider
53+
54+
##### With a certificate
55+
56+
```TypeScript
57+
// @azure/identity
58+
const credential = new ClientCertificateCredential(
59+
'YOUR_TENANT_ID',
60+
'YOUR_CLIENT_ID',
61+
'YOUR_CERTIFICATE_PATH',
62+
);
63+
64+
// @microsoft/kiota-authentication-azure
65+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["https://graph.microsoft.com/.default"]);
766
```
8-
const msgraphSdkJavascript = require('@microsoft/msgraph-sdk');
967

10-
// TODO: DEMONSTRATE API
68+
##### With a secret
69+
70+
```TypeScript
71+
// @azure/identity
72+
const credential = new ClientSecretCredential(
73+
'YOUR_TENANT_ID',
74+
'YOUR_CLIENT_ID',
75+
'YOUR_CLIENT_SECRET',
76+
);
77+
78+
// @microsoft/kiota-authentication-azure
79+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["https://graph.microsoft.com/.default"]);
1180
```
81+
82+
#### 2.2.3 On-behalf-of provider
83+
84+
```TypeScript
85+
// @azure/identity
86+
const credential = new OnBehalfOfCredential({
87+
tenantId: 'YOUR_TENANT_ID',
88+
clientId: 'YOUR_CLIENT_ID',
89+
clientSecret: 'YOUR_CLIENT_SECRET',
90+
userAssertionToken: 'JWT_TOKEN_TO_EXCHANGE',
91+
});
92+
93+
// @microsoft/kiota-authentication-azure
94+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["https://graph.microsoft.com/.default"]);
95+
```
96+
97+
#### 2.2.4 Device code provider
98+
99+
```TypeScript
100+
// @azure/identity
101+
const credential = new DeviceCodeCredential({
102+
tenantId: 'YOUR_TENANT_ID',
103+
clientId: 'YOUR_CLIENT_ID',
104+
userPromptCallback: (info) => {
105+
console.log(info.message);
106+
},
107+
});
108+
109+
// @microsoft/kiota-authentication-azure
110+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["User.Read"]);
111+
```
112+
113+
#### 2.2.5 Interactive provider
114+
115+
```TypeScript
116+
// @azure/identity
117+
const credential = new InteractiveBrowserCredential({
118+
tenantId: 'YOUR_TENANT_ID',
119+
clientId: 'YOUR_CLIENT_ID',
120+
redirectUri: 'http://localhost',
121+
});
122+
123+
// @microsoft/kiota-authentication-azure
124+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["User.Read"]);
125+
```
126+
127+
#### 2.2.6 Username/password provider
128+
129+
```TypeScript
130+
// @azure/identity
131+
const credential = new UsernamePasswordCredential(
132+
'YOUR_TENANT_ID',
133+
'YOUR_CLIENT_ID',
134+
'YOUR_USER_NAME',
135+
'YOUR_PASSWORD',
136+
);
137+
138+
// @microsoft/kiota-authentication-azure
139+
const authProvider = new AzureIdentityAuthenticationProvider(credential, ["User.Read"]);
140+
```
141+
142+
### 2.3 Get a Graph Service Client Adapter object
143+
144+
You must get a **GraphServiceClient** object to make requests against the service.
145+
146+
```typescript
147+
const requestAdapter = new GraphRequestAdapter(authProvider);
148+
const graphServiceClient = createGraphServiceClient(requestAdapter);
149+
```
150+
151+
## 3. Make requests against the service
152+
153+
After you have a **GraphServiceClient** that is authenticated, you can begin making calls against the service. The requests against the service look like our [REST API](https://docs.microsoft.com/graph/api/overview?view=graph-rest-1.0).
154+
155+
### 3.1 Get user's detailed information
156+
157+
To retrieve the user's detailed information:
158+
159+
```typescript
160+
import { createGraphServiceClient, GraphRequestAdapter } from "@microsoft/msgraph-sdk";
161+
import "@microsoft/msgraph-sdk-users";
162+
163+
const requestAdapter = new GraphRequestAdapter(authProvider);
164+
const graphServiceClient = createGraphServiceClient(requestAdapter);
165+
166+
const jane = await graphServiceClient.users.byUserId("jane@contoso.com").get();
167+
```
168+
169+
## 4. Documentation
170+
171+
For more detailed documentation, see:
172+
173+
* [Overview](https://docs.microsoft.com/graph/overview)
174+
* [Collections](https://docs.microsoft.com/graph/sdks/paging)
175+
* [Making requests](https://docs.microsoft.com/graph/sdks/create-requests)
176+
* [Known issues](https://github.com/MicrosoftGraph/msgraph-sdk-typescript/issues)
177+
* [Contributions](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/CONTRIBUTING.md)
178+
179+
## 5. Issues
180+
181+
For known issues, see [issues](https://github.com/MicrosoftGraph/msgraph-sdk-typescript/issues).
182+
183+
## 6. Contributions
184+
185+
The Microsoft Graph SDK is open for contribution. To contribute to this project, see [Contributing](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/CONTRIBUTING.md).
186+
187+
## 7. License
188+
189+
Licensed under the [MIT license](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/LICENSE).
190+
191+
## 8. Third-party notices
192+
193+
[Third-party notices](https://github.com/microsoftgraph/msgraph-sdk-typescript/blob/main/LICENSE)

0 commit comments

Comments
 (0)