Skip to content

Commit a61e4dc

Browse files
vgremvgrem
committed
docs & example updates
1 parent c93a12c commit a61e4dc

File tree

5 files changed

+114
-43
lines changed

5 files changed

+114
-43
lines changed

‎README.md

+19-27
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from office365.azure_env import AzureEnvironment
2+
13
# About
24
Microsoft 365 & Microsoft Graph library for Python
35

@@ -172,19 +174,18 @@ The list of examples:
172174

173175
Refer [examples section](examples/sharepoint) for another scenarios
174176

175-
### Support for non-standard SharePoint Online Environments
176-
177-
Support for non-standard SharePoint Environments is currently being implemented. Currently supported:
178-
- GCC High
177+
### Support for Azure environments
179178

180-
To enable authentication to GCC High endpoints, add the `environment='GCCH'` parameter when calling the
179+
To enable authentication to specific Azure environment endpoints, add the `environment` parameter when calling the
181180
`ClientContext class` with `.with_user_credentials`, `.with_client_credentials`, or `.with_credentials`
182181

183182
Example:
184183
```python
184+
from office365.azure_env import AzureEnvironment
185185
from office365.sharepoint.client_context import ClientContext
186+
from office365.runtime.auth.client_credential import ClientCredential
186187
client_credentials = ClientCredential('{client_id}','{client_secret}')
187-
ctx = ClientContext('{url}').with_credentials(client_credentials, environment='GCCH')
188+
ctx = ClientContext('{url}', environment=AzureEnvironment.USGovernmentHigh).with_credentials(client_credentials)
188189
```
189190

190191
# Working with Outlook API
@@ -213,26 +214,13 @@ Using [Microsoft Authentication Library (MSAL) for Python](https://pypi.org/proj
213214
> in the provided examples. Other forms of token acquisition can be found here: https://msal-python.readthedocs.io/en/latest/
214215
215216
```python
216-
import msal
217217
from office365.graph_client import GraphClient
218-
219-
def acquire_token():
220-
"""
221-
Acquire token via MSAL
222-
"""
223-
authority_url = 'https://login.microsoftonline.com/{tenant_id_or_name}'
224-
app = msal.ConfidentialClientApplication(
225-
authority=authority_url,
226-
client_id='{client_id}',
227-
client_credential='{client_secret}'
228-
)
229-
token = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
230-
return token
231-
232-
233-
client = GraphClient(acquire_token)
234-
218+
client = GraphClient(tenant='{tenant_name_or_id}').with_client_secret(
219+
client_id='{client_id}',
220+
client_secret='{client_secret}'
221+
)
235222
```
223+
Example: [with_client_secret](examples/auth/with_client_secret.py)
236224

237225
But in terms of Microsoft Graph API authentication, another OAuth spec compliant libraries
238226
such as [adal](https://github.com/AzureAD/azure-activedirectory-library-for-python)
@@ -268,7 +256,9 @@ The example demonstrates how to send an email via [Microsoft Graph endpoint](htt
268256
```python
269257
from office365.graph_client import GraphClient
270258

271-
client = GraphClient(acquire_token_func)
259+
client = GraphClient(tenant='{tenant_name_or_id}').with_username_and_password(
260+
'{client_id}', '{username}', '{password}'
261+
)
272262

273263
client.me.send_mail(
274264
subject="Meet for lunch?",
@@ -334,7 +324,7 @@ which corresponds to [`list available drives` endpoint](https://docs.microsoft.c
334324
from office365.graph_client import GraphClient
335325

336326
tenant_name = "contoso.onmicrosoft.com"
337-
client = GraphClient(acquire_token_func)
327+
client = GraphClient(tenant=tenant_name)
338328
drives = client.drives.get().execute_query()
339329
for drive in drives:
340330
print("Drive url: {0}".format(drive.web_url))
@@ -415,7 +405,9 @@ Example: Create a new page
415405

416406
```python
417407
from office365.graph_client import GraphClient
418-
client = GraphClient(acquire_token_func)
408+
client = GraphClient(tenant='{tenant_name_or_id}').with_username_and_password(
409+
'{client_id}', '{username}', '{password}'
410+
)
419411

420412
files = {}
421413
with open("./MyPage.html", 'rb') as f, \

‎examples/auth/with_client_secret.py

+1-14
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,9 @@
88
https://learn.microsoft.com/en-us/entra/identity-platform/msal-authentication-flows#client-credentials
99
"""
1010

11-
import msal
12-
1311
from office365.graph_client import GraphClient
1412
from tests import test_client_id, test_client_secret, test_tenant
1513

16-
17-
def acquire_token():
18-
authority_url = "https://login.microsoftonline.com/{0}".format(test_tenant)
19-
app = msal.ConfidentialClientApplication(
20-
authority=authority_url,
21-
client_id=test_client_id,
22-
client_credential=test_client_secret,
23-
)
24-
return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
25-
26-
27-
client = GraphClient(acquire_token)
14+
client = GraphClient(tenant=test_tenant).with_client_secret(test_client_id, test_client_secret)
2815
root_site = client.sites.root.get().execute_query()
2916
print(root_site.web_url)

‎examples/auth/with_client_secret_custom.py

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"""
2+
Acquires a token by using application secret
3+
4+
The following options are supported:
5+
- utilize built in GraphClient(tenant=tenant).with_client_secret(client_id, client_secret) method
6+
- or provide a custom callback function to GraphClient constructor as demonstrated below
7+
8+
https://learn.microsoft.com/en-us/entra/identity-platform/msal-authentication-flows#client-credentials
9+
"""
10+
11+
import msal
12+
13+
from office365.graph_client import GraphClient
14+
from tests import test_client_id, test_client_secret, test_tenant
15+
16+
17+
def acquire_token():
18+
authority_url = "https://login.microsoftonline.com/{0}".format(test_tenant)
19+
app = msal.ConfidentialClientApplication(
20+
authority=authority_url,
21+
client_id=test_client_id,
22+
client_credential=test_client_secret,
23+
)
24+
return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
25+
26+
27+
client = GraphClient(acquire_token)
28+
root_site = client.sites.root.get().execute_query()
29+
print(root_site.web_url)

‎generator/import_metadata.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,13 @@ def export_to_file(path, content):
2626
"--endpoint",
2727
dest="endpoint",
2828
help="Import metadata endpoint",
29-
default="sharepoint",
29+
default="graph",
3030
)
3131
parser.add_argument(
3232
"-p",
3333
"--path",
3434
dest="path",
35-
default="./metadata/SharePoint.xml",
35+
default="./metadata/Graph.xml",
3636
help="Import metadata endpoint",
3737
)
3838

‎generator/metadata/Graph.xml

+63
Original file line numberDiff line numberDiff line change
@@ -41270,6 +41270,12 @@ within the time frame of their original request."/>
4127041270
<Member Name="allVersions" Value="1"/>
4127141271
<Member Name="linkedFiles" Value="2"/>
4127241272
<Member Name="unknownFutureValue" Value="4"/>
41273+
<Member Name="advancedIndexing" Value="8"/>
41274+
<Member Name="listAttachments" Value="16"/>
41275+
<Member Name="htmlTranscripts" Value="32"/>
41276+
<Member Name="messageConversationExpansion" Value="64"/>
41277+
<Member Name="locationsWithoutHits" Value="256"/>
41278+
<Member Name="allItemsInFolder" Value="512"/>
4127341279
</EnumType>
4127441280
<EnumType Name="additionalOptions" IsFlags="true">
4127541281
<Member Name="none" Value="0"/>
@@ -41279,6 +41285,15 @@ within the time frame of their original request."/>
4127941285
<Member Name="subfolderContents" Value="8"/>
4128041286
<Member Name="listAttachments" Value="16"/>
4128141287
<Member Name="unknownFutureValue" Value="32"/>
41288+
<Member Name="htmlTranscripts" Value="64"/>
41289+
<Member Name="advancedIndexing" Value="128"/>
41290+
<Member Name="allItemsInFolder" Value="256"/>
41291+
<Member Name="includeFolderAndPath" Value="512"/>
41292+
<Member Name="condensePaths" Value="1024"/>
41293+
<Member Name="friendlyName" Value="2048"/>
41294+
<Member Name="splitSource" Value="4096"/>
41295+
<Member Name="optimizedPartitionSize" Value="8192"/>
41296+
<Member Name="includeReport" Value="16384"/>
4128241297
</EnumType>
4128341298
<EnumType Name="caseAction">
4128441299
<Member Name="contentExport" Value="0"/>
@@ -41316,6 +41331,13 @@ within the time frame of their original request."/>
4131641331
<Member Name="Many" Value="1"/>
4131741332
<Member Name="unknownFutureValue" Value="2"/>
4131841333
</EnumType>
41334+
<EnumType Name="cloudAttachmentVersion">
41335+
<Member Name="latest" Value="1"/>
41336+
<Member Name="recent10" Value="2"/>
41337+
<Member Name="recent100" Value="3"/>
41338+
<Member Name="all" Value="4"/>
41339+
<Member Name="unknownFutureValue" Value="5"/>
41340+
</EnumType>
4131941341
<EnumType Name="dataSourceContainerStatus">
4132041342
<Member Name="active" Value="1"/>
4132141343
<Member Name="released" Value="2"/>
@@ -41337,6 +41359,13 @@ within the time frame of their original request."/>
4133741359
<Member Name="allCaseNoncustodialDataSources" Value="8"/>
4133841360
<Member Name="unknownFutureValue" Value="16"/>
4133941361
</EnumType>
41362+
<EnumType Name="documentVersion">
41363+
<Member Name="latest" Value="1"/>
41364+
<Member Name="recent10" Value="2"/>
41365+
<Member Name="recent100" Value="3"/>
41366+
<Member Name="all" Value="4"/>
41367+
<Member Name="unknownFutureValue" Value="5"/>
41368+
</EnumType>
4134041369
<EnumType Name="exportCriteria" IsFlags="true">
4134141370
<Member Name="searchHits" Value="1"/>
4134241371
<Member Name="partiallyIndexed" Value="2"/>
@@ -41347,6 +41376,7 @@ within the time frame of their original request."/>
4134741376
<Member Name="directory" Value="1"/>
4134841377
<Member Name="pst" Value="2"/>
4134941378
<Member Name="unknownFutureValue" Value="3"/>
41379+
<Member Name="msg" Value="4"/>
4135041380
</EnumType>
4135141381
<EnumType Name="exportFormat">
4135241382
<Member Name="pst" Value="0"/>
@@ -41365,6 +41395,16 @@ within the time frame of their original request."/>
4136541395
<Member Name="pdfReplacement" Value="4"/>
4136641396
<Member Name="tags" Value="16"/>
4136741397
<Member Name="unknownFutureValue" Value="32"/>
41398+
<Member Name="splitSource" Value="64"/>
41399+
<Member Name="includeFolderAndPath" Value="128"/>
41400+
<Member Name="friendlyName" Value="256"/>
41401+
<Member Name="condensePaths" Value="512"/>
41402+
<Member Name="optimizedPartitionSize" Value="1024"/>
41403+
</EnumType>
41404+
<EnumType Name="itemsToInclude" IsFlags="true">
41405+
<Member Name="searchHits" Value="1"/>
41406+
<Member Name="partiallyIndexed" Value="2"/>
41407+
<Member Name="unknownFutureValue" Value="4"/>
4136841408
</EnumType>
4136941409
<EnumType Name="purgeAreas" IsFlags="true">
4137041410
<Member Name="mailboxes" Value="1"/>
@@ -41381,6 +41421,14 @@ within the time frame of their original request."/>
4138141421
<Member Name="site" Value="2"/>
4138241422
<Member Name="unknownFutureValue" Value="4"/>
4138341423
</EnumType>
41424+
<EnumType Name="statisticsOptions" IsFlags="true">
41425+
<Member Name="includeRefiners" Value="1"/>
41426+
<Member Name="includeQueryStats" Value="2"/>
41427+
<Member Name="includeUnindexedStats" Value="4"/>
41428+
<Member Name="advancedIndexing" Value="8"/>
41429+
<Member Name="locationsWithoutHits" Value="16"/>
41430+
<Member Name="unknownFutureValue" Value="32"/>
41431+
</EnumType>
4138441432
<EnumType Name="deploymentStatus">
4138541433
<Member Name="upToDate" Value="1"/>
4138641434
<Member Name="outdated" Value="2"/>
@@ -41966,6 +42014,10 @@ within the time frame of their original request."/>
4196642014
<Property Name="status" Type="microsoft.graph.security.dataSourceContainerStatus"/>
4196742015
</EntityType>
4196842016
<EntityType Name="ediscoveryAddToReviewSetOperation" BaseType="microsoft.graph.security.caseOperation">
42017+
<Property Name="additionalDataOptions" Type="microsoft.graph.security.additionalDataOptions" Nullable="false"/>
42018+
<Property Name="cloudAttachmentVersion" Type="microsoft.graph.security.cloudAttachmentVersion" Nullable="false"/>
42019+
<Property Name="documentVersion" Type="microsoft.graph.security.documentVersion" Nullable="false"/>
42020+
<Property Name="itemsToInclude" Type="microsoft.graph.security.itemsToInclude" Nullable="false"/>
4196942021
<NavigationProperty Name="reviewSet" Type="microsoft.graph.security.ediscoveryReviewSet"/>
4197042022
<NavigationProperty Name="search" Type="microsoft.graph.security.ediscoverySearch"/>
4197142023
</EntityType>
@@ -42035,6 +42087,7 @@ within the time frame of their original request."/>
4203542087
<Property Name="indexedItemsSize" Type="Edm.Int64"/>
4203642088
<Property Name="mailboxCount" Type="Edm.Int32"/>
4203742089
<Property Name="siteCount" Type="Edm.Int32"/>
42090+
<Property Name="statisticsOptions" Type="microsoft.graph.security.statisticsOptions" Nullable="false"/>
4203842091
<Property Name="unindexedItemCount" Type="Edm.Int64"/>
4203942092
<Property Name="unindexedItemsSize" Type="Edm.Int64"/>
4204042093
<NavigationProperty Name="search" Type="microsoft.graph.security.ediscoverySearch"/>
@@ -42053,8 +42106,10 @@ within the time frame of their original request."/>
4205342106
<EntityType Name="ediscoveryPurgeDataOperation" BaseType="microsoft.graph.security.caseOperation"/>
4205442107
<EntityType Name="ediscoverySearchExportOperation" BaseType="microsoft.graph.security.caseOperation">
4205542108
<Property Name="additionalOptions" Type="microsoft.graph.security.additionalOptions"/>
42109+
<Property Name="cloudAttachmentVersion" Type="microsoft.graph.security.cloudAttachmentVersion" Nullable="false"/>
4205642110
<Property Name="description" Type="Edm.String"/>
4205742111
<Property Name="displayName" Type="Edm.String"/>
42112+
<Property Name="documentVersion" Type="microsoft.graph.security.documentVersion" Nullable="false"/>
4205842113
<Property Name="exportCriteria" Type="microsoft.graph.security.exportCriteria"/>
4205942114
<Property Name="exportFileMetadata" Type="Collection(microsoft.graph.security.exportFileMetadata)"/>
4206042115
<Property Name="exportFormat" Type="microsoft.graph.security.exportFormat"/>
@@ -42981,6 +43036,9 @@ within the time frame of their original request."/>
4298143036
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoveryReviewSet"/>
4298243037
<Parameter Name="search" Type="microsoft.graph.security.ediscoverySearch"/>
4298343038
<Parameter Name="additionalDataOptions" Type="microsoft.graph.security.additionalDataOptions"/>
43039+
<Parameter Name="itemsToInclude" Type="microsoft.graph.security.itemsToInclude"/>
43040+
<Parameter Name="cloudAttachmentVersion" Type="microsoft.graph.security.cloudAttachmentVersion"/>
43041+
<Parameter Name="documentVersion" Type="microsoft.graph.security.documentVersion"/>
4298443042
</Action>
4298543043
<Action Name="export" IsBound="true">
4298643044
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoveryReviewSet"/>
@@ -43009,6 +43067,7 @@ within the time frame of their original request."/>
4300943067
</Action>
4301043068
<Action Name="estimateStatistics" IsBound="true">
4301143069
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoverySearch"/>
43070+
<Parameter Name="statisticsOptions" Type="microsoft.graph.security.statisticsOptions"/>
4301243071
</Action>
4301343072
<Action Name="exportReport" IsBound="true">
4301443073
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoverySearch"/>
@@ -43017,6 +43076,8 @@ within the time frame of their original request."/>
4301743076
<Parameter Name="exportCriteria" Type="microsoft.graph.security.exportCriteria"/>
4301843077
<Parameter Name="exportLocation" Type="microsoft.graph.security.exportLocation"/>
4301943078
<Parameter Name="additionalOptions" Type="microsoft.graph.security.additionalOptions"/>
43079+
<Parameter Name="cloudAttachmentVersion" Type="microsoft.graph.security.cloudAttachmentVersion"/>
43080+
<Parameter Name="documentVersion" Type="microsoft.graph.security.documentVersion"/>
4302043081
</Action>
4302143082
<Action Name="exportResult" IsBound="true">
4302243083
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoverySearch"/>
@@ -43027,6 +43088,8 @@ within the time frame of their original request."/>
4302743088
<Parameter Name="additionalOptions" Type="microsoft.graph.security.additionalOptions"/>
4302843089
<Parameter Name="exportFormat" Type="microsoft.graph.security.exportFormat"/>
4302943090
<Parameter Name="exportSingleItems" Type="Edm.Boolean"/>
43091+
<Parameter Name="cloudAttachmentVersion" Type="microsoft.graph.security.cloudAttachmentVersion"/>
43092+
<Parameter Name="documentVersion" Type="microsoft.graph.security.documentVersion"/>
4303043093
</Action>
4303143094
<Action Name="purgeData" IsBound="true">
4303243095
<Parameter Name="bindingParameter" Type="microsoft.graph.security.ediscoverySearch"/>

0 commit comments

Comments
 (0)