Office 365 & Microsoft Graph library for Python
- 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
Use pip:
pip install Office365-REST-Python-Client
Alternatively the latest version could be directly installed via GitHub:
pip install git+https://github.com/vgrem/Office365-REST-Python-Client.git
The list of supported API versions:
- SharePoint 2013 REST API and above
- SharePoint Online & OneDrive for Business REST API
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
There are two approaches available to perform API queries:
ClientContext class- where you target SharePoint resources such asWeb,ListItemand 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
Webproperties:
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
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:
GraphClientwhich targets Outlook APIv2.0version (preferable nowadays, refer transition to Microsoft Graph-based Outlook REST API for a details)
-OutlookClientwhich targets Outlook APIv1.0version (not recommended for usage sincev1.0version is being deprecated.)
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)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 = ["[email protected]"]
client.me.send_mail(message).execute_query()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 tokenThe 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))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.
The Microsoft Authentication Library (MSAL) for Python which comes as a dependency is used to obtain token
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()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()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()The following libraries will be installed when you install the client library:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent