Skip to content

Commit cd14095

Browse files
samwelkandasamwelkanda
committed
Update project README with usage details
1 parent 24e3e09 commit cd14095

File tree

1 file changed

+143
-1
lines changed

1 file changed

+143
-1
lines changed

‎README.md‎

Lines changed: 143 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,143 @@
1-
# Microsoft Graph SDK for Python
1+
# Microsoft Graph SDK for Python
2+
3+
Get started with the Microsoft Graph SDK for Python by integrating the [Microsoft Graph API](https://docs.microsoft.com/graph/overview) into your Python application!
4+
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, try the [Beta](https://github.com/microsoftgraph/msgraph-beta-sdk-python) SDK.
6+
>
7+
> **Note:** the Microsoft Graph Python SDK is currently in Preview.
8+
9+
## 1. Installation
10+
11+
```py
12+
pip install msgraph-sdk-python
13+
```
14+
15+
## 2. Getting started
16+
## Get started with Microsoft Graph
17+
18+
### 2.1 Register your application
19+
20+
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).
21+
22+
### 2.2 Create an AuthenticationProvider object
23+
24+
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.
25+
26+
Note: This SDK offers an asynchronous API by default. Async is a concurrency model that is far more efficient than multi-threading, and can provide significant performance benefits and enable the use of long-lived network connections such as WebSockets. We support the popular async envronments such as `asyncio`, `anyio` or `trio`. For authentication you need to use one of the async credential classes from `azure.identity`.
27+
28+
```py
29+
from azure.identity.aio import EnvironmentCredential
30+
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider
31+
32+
credential=EnvironmentCredential()
33+
auth_provider = AzureIdentityAuthenticationProvider(credential)
34+
```
35+
36+
### 2.3 Initialise a GraphRequestAdapter object
37+
38+
The SDK uses an adapter object that handles the HTTP concerns. This HTTP adapter object is used to build the Graph client for making requests.
39+
40+
To initialise one using the authentication provider created in the previous step:
41+
42+
```py
43+
from msgraph.graph_request_adapter import GraphRequestAdapter
44+
45+
adapter = GraphRequestAdapter(auth_provider)
46+
```
47+
48+
We currently use [HTTPX](https://www.python-httpx.org/) as our HTTP client. You can pass your custom configured `httpx.AsyncClient` using:
49+
50+
```py
51+
from msgraph.graph_request_adapter import GraphRequestAdapter
52+
from msgraph.core.graph_client_factory import GraphClientFactory
53+
54+
http_Client = GraphClientFactory::create_with_default_middleware(client=httpx.AsyncClient())
55+
request_adapter = GraphRequestAdapter(auth_Provider, http_client)
56+
```
57+
58+
### 2.3 Get a GraphServiceClient object
59+
60+
You must get a **GraphServiceClient** object to make requests against the service.
61+
62+
```py
63+
from msgraph.graph_service_client import GraphServiceClient
64+
65+
client = GraphServiceClient(request_adapter)
66+
```
67+
68+
## 3. Make requests against the service
69+
70+
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).
71+
72+
The following is a complete example that shows how to fetch a user from Microsoft Graph.
73+
74+
```py
75+
import asyncio
76+
from azure.identity.aio import ClientSecretCredential
77+
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider
78+
from msgraph.graph_request_adapter import GraphRequestAdapter
79+
from msgraph.graph_service_client import GraphServiceClient
80+
81+
credential = ClientSecretCredential(
82+
'tenantId',
83+
'clientId',
84+
'clientSecret'
85+
)
86+
auth_provider = AzureIdentityAuthenticationProvider(credential)
87+
request_adapter = GraphRequestAdapter(auth_provider)
88+
client = GraphServiceClient(request_adapter)
89+
90+
user = asyncio.run(client.users_by_id('userPrincipalName').get())
91+
print(user.display_name)
92+
```
93+
94+
Note that to calling `me()` requires a signed-in user and therefore delegated permissions (obtained using the `authorization_code` flow):
95+
96+
```py
97+
import asyncio
98+
from azure.identity.aio import AuthorizationCodeCredential
99+
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider
100+
from msgraph.graph_request_adapter import GraphRequestAdapter
101+
from msgraph.graph_service_client import GraphServiceClient
102+
103+
credential = AuthorizationCodeCredential(
104+
'tenant_id',
105+
'client_id',
106+
'authorization_code',
107+
'redirect_uri',
108+
)
109+
110+
auth_provider = AzureIdentityAuthenticationProvider(credential)
111+
request_adapter = GraphRequestAdapter(auth_provider)
112+
client = GraphServiceClient(request_adapter)
113+
114+
user = asyncio.run(client.me().get())
115+
print(user.display_name)
116+
117+
```
118+
## Documentation and resources
119+
120+
* [Documentation](docs/README.md)
121+
122+
* [Examples](docs/Examples.md)
123+
124+
* [Microsoft Graph website](https://aka.ms/graph)
125+
126+
## Upgrading
127+
128+
For detailed information on breaking changes, bug fixes and new functionality introduced during major upgrades, check out our [Upgrade Guide](UPGRADING.md)
129+
130+
131+
## Issues
132+
133+
View or log issues on the [Issues](https://github.com/microsoftgraph/msgraph-sdk-python/issues) tab in the repo.
134+
135+
## Contribute
136+
137+
Please read our [Contributing](CONTRIBUTING.md) guidelines carefully for advice on how to contribute to this repo.
138+
139+
## Copyright and license
140+
141+
Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT [license](LICENSE).
142+
143+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

0 commit comments

Comments
 (0)