Microsoft 365 & Microsoft Graph Library for Python
Project description
About
Office 365 & Microsoft Graph library for Python
Usage
- Installation
- Working with SharePoint API
- Working with Outlook API
- Working with OneDrive API
- Working with Teams API
- Working with OneNote API
- Working with Planner API
Status
Installation
Use pip:
pip install Office365-REST-Python-Client
Note
Alternatively the latest version could be directly installed via GitHub:
pip install git+https://github.com/vgrem/Office365-REST-Python-Client.git
Working with SharePoint API
The list of supported API versions:
- SharePoint 2013 REST API and above
- SharePoint Online & OneDrive for Business REST API
Authentication
The following auth flows are supported:
-
app principals flow:
ClientContext.with_credentials(client_credentials)
Usage:
client_credentials = ClientCredential('{client_id}','{client_secret}') ctx = ClientContext('{url}').with_credentials(client_credentials)
Documentation: refer Granting access using SharePoint App-Only for a details
Example: connect_with_app_principal.py
-
user credentials flow:
ClientContext.with_credentials(user_credentials)
Usage:
user_credentials = UserCredential('{username}','{password}') ctx = ClientContext('{url}').with_credentials(user_credentials)
Example: connect_with_user_credential.py
-
certificate credentials flow:
ClientContext.with_certificate(tenant, client_id, thumbprint, cert_path)
Documentation: Granting access via Azure AD App-Only
Example: connect_with_client_certificate.py
Examples
There are two approaches available to perform API queries:
ClientContext class
- where you target SharePoint resources such asWeb
,ListItem
and etc (recommended)
from office365.runtime.auth.user_credential import UserCredential from office365.sharepoint.client_context import ClientContext site_url = "https://{your-tenant-prefix}.sharepoint.com" ctx = ClientContext(site_url).with_credentials(UserCredential("{username}", "{password}")) web = ctx.web ctx.load(web) ctx.execute_query() print("Web title: {0}".format(web.properties['Title']))
or alternatively via method chaining (a.k.a Fluent Interface):
from office365.runtime.auth.user_credential import UserCredential from office365.sharepoint.client_context import ClientContext site_url = "https://{your-tenant-prefix}.sharepoint.com" ctx = ClientContext(site_url).with_credentials(UserCredential("{username}", "{password}")) web = ctx.web.get().execute_query() print("Web title: {0}".format(web.properties['Title']))
-
RequestOptions class
- where you construct REST queries (and no model is involved)The example demonstrates how to read
Web
properties:
import json from office365.runtime.auth.user_credential import UserCredential from office365.runtime.http.request_options import RequestOptions from office365.sharepoint.client_context import ClientContext site_url = "https://{your-tenant-prefix}.sharepoint.com" ctx = ClientContext(site_url).with_credentials(UserCredential("{username}", "{password}")) request = RequestOptions("{0}/_api/web/".format(site_url)) response = ctx.execute_request_direct(request) json = json.loads(response.content) web_title = json['d']['Title'] print("Web title: {0}".format(web_title))
The list of examples:
-
Working with files
-
Working with lists and list items
Refer examples section for another scenarios
Working with Outlook API
The list of supported APIs:
Since Outlook REST APIs are available in both Microsoft Graph and the Outlook API endpoint, the following clients are available:
GraphClient
which targets Outlook APIv2.0
version (preferable nowadays, refer transition to Microsoft Graph-based Outlook REST API for a details)
-OutlookClient
which targets Outlook APIv1.0
version (not recommended for usage sincev1.0
version is being deprecated.)
Authentication
The Microsoft Authentication Library (MSAL) for Python which comes as a dependency is used as a default library to obtain tokens to call Microsoft Graph API.
Using Microsoft Authentication Library (MSAL) for Python
Note: access token is getting acquired via Client Credential flow in the provided examples
import msal from office365.graph_client import GraphClient def acquire_token(): """ Acquire token via MSAL """ authority_url = 'https://login.microsoftonline.com/{tenant_id_or_name}' app = msal.ConfidentialClientApplication( authority=authority_url, client_id='{client_id}', client_credential='{client_secret}' ) token = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"]) return token client = GraphClient(acquire_token)
But in terms of Microsoft Graph API authentication, another OAuth spec compliant libraries such as adal are supported as well.
Using ADAL Python
Usage
import adal from office365.graph_client import GraphClient def acquire_token_func(): authority_url = 'https://login.microsoftonline.com/{tenant_id_or_name}' auth_ctx = adal.AuthenticationContext(authority_url) token = auth_ctx.acquire_token_with_client_credentials( "https://graph.microsoft.com", "{client_id}", "{client_secret}") return token client = GraphClient(acquire_token_func)
Example
The example demonstrates how to send an email via Microsoft Graph endpoint.
Note: access token is getting acquired via Client Credential flow
from office365.graph_client import GraphClient client = GraphClient(acquire_token_func) message = client.me.messages.new() # type: Message message.subject = "Meet for lunch?" message.body = "The new cafeteria is open." message.to_recipients = ["fannyd@contoso.onmicrosoft.com"] client.me.send_mail(message).execute_query()
Working with OneDrive API
Documentation
Authentication
The Microsoft Authentication Library (MSAL) for Python which comes as a dependency is used to obtain token
import msal def acquire_token_func(): """ Acquire token via MSAL """ authority_url = 'https://login.microsoftonline.com/{tenant_id_or_name}' app = msal.ConfidentialClientApplication( authority=authority_url, client_id='{client_id}', client_credential='{client_secret}' ) token = app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"]) return token
Examples
Example: list available drives
The example demonstrates how to enumerate and print drive's url
which corresponds to list available drives
endpoint
Note: access token is getting acquired via Client Credential flow
from office365.graph_client import GraphClient tenant_name = "contoso.onmicrosoft.com" client = GraphClient(acquire_token_func) drives = client.drives.get().execute_query() for drive in drives: print("Drive url: {0}".format(drive.web_url))
Example: download the contents of a DriveItem(folder facet)
from office365.graph_client import GraphClient client = GraphClient(acquire_token_func) # retrieve drive properties drive = client.users["{user_id_or_principal_name}"].drive.get().execute_query() # download files from OneDrive into local folder with tempfile.TemporaryDirectory() as path: download_files(drive.root, path)
where
def download_files(remote_folder, local_path): drive_items = remote_folder.children.get().execute_query() for drive_item in drive_items: if drive_item.file is not None: # is file? # download file content with open(os.path.join(local_path, drive_item.name), 'wb') as local_file: drive_item.download(local_file).execute_query()
Refer OneDrive examples section for a more examples.
Working with Microsoft Teams API
Authentication
The Microsoft Authentication Library (MSAL) for Python which comes as a dependency is used to obtain token
Examples
Example: create a new team under a group
The example demonstrates how create a new team under a group
which corresponds to Create team
endpoint
from office365.graph_client import GraphClient client = GraphClient(acquire_token_func) new_team = client.groups["{group_id}"].add_team().execute_query_retry()
Working with Microsoft Onenote API
The library supports OneNote API in terms of calls to a user's OneNote notebooks, sections, and pages in a personal or organization account
Example: Create a new page
from office365.graph_client import GraphClient client = GraphClient(acquire_token_func) files = {} with open("./MyPage.html", 'rb') as f, \ open("./MyImage.png", 'rb') as img_f, \ open("./MyDoc.pdf", 'rb') as pdf_f: files["imageBlock1"] = img_f files["fileBlock1"] = pdf_f page = client.me.onenote.pages.add(presentation_file=f, attachment_files=files).execute_query()
Working with Microsoft Planner API
The example demonstrates how to create a new planner task
which corresponds to Create plannerTask
endpoint:
from office365.graph_client import GraphClient client = GraphClient(acquire_token_func) task = client.planner.tasks.add(title="New task", planId="--plan id goes here--").execute_query()
Third Party Libraries and Dependencies
The following libraries will be installed when you install the client library:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for Office365-REST-Python-Client-2.3.11.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8931ff7069911eb611512a3456c95fe8cad6b6efd8691f04009adc561258cf3f |
|
MD5 | 95d8261f5b1e8c2ac718d0e759221eab |
|
BLAKE2-256 | 92981b73d3dd547b1f284cd277e1eb2cbe8d2051344a6c5a2d81398ebc9c20f3 |
Hashes for Office365_REST_Python_Client-2.3.11-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8fa54030db2edb0d295b9f07c46720bd5da3329a5ba677db8dab2b7fa4092305 |
|
MD5 | 17601051697761da2f7435726cfe8485 |
|
BLAKE2-256 | eaf8801cbd682c8eca1608bd7379223c8ab8a94e2ce20d47d69eb44414e96589 |