Office 365 & Microsoft Graph library for Python
- Installation
- Working with SharePoint API
- Working with Outlook API
- Working with OneDrive API
- Working with Microsoft Teams API
Use pip:
pip install Office365-REST-Python-Client
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:
AuthenticationContext.ctx_auth.acquire_token_for_app(client_id, client_secret)
(refer Granting access using SharePoint App-Only for a details) - user credentials flow:
AuthenticationContext.ctx_auth.acquire_token_for_user(username, password)
- certificate credentials flow
ClientContext.connect_with_certificate(site_url, client_id,thumbprint, certificate_path)
There are two approaches available to perform API queries:
ClientContext class
- where you target SharePoint resources such asWeb
,ListItem
and etc (recommended)
from office365.sharepoint.client_context import ClientContext
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.sharepoint.client_context import ClientContext
ctx = ClientContext(site_url).with_credentials(UserCredential(username, password))
web = ctx.web.load().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.UserCredential import UserCredential
from office365.runtime.http.request_options import RequestOptions
from office365.sharepoint.client_context import ClientContext
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 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 Outlookv2.0
version (preferable nowadays, refer transition to Microsoft Graph-based Outlook REST API for a details)OutlookClient
which targets Outlookv1.0
version (not recommended for usage sincev1.0
version is being deprecated.)
ADAL Python library is utilized to authenticate users to Active Directory (AD) and obtain tokens
The example demonstrates how to send an email via Microsoft Graph endpoint.
Note: access token is getting acquired via Client Credential flow
def get_token(auth_ctx):
token = auth_ctx.acquire_token_with_client_credentials(
"https://graph.microsoft.com",
client_id,
client_secret)
return token
tenant_name = "contoso.onmicrosoft.com"
client = GraphClient(tenant_name, get_token)
message_json = {
"Message": {
"Subject": "Meet for lunch?",
"Body": {
"ContentType": "Text",
"Content": "The new cafeteria is open."
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "[email protected]"
}
}
]
},
"SaveToSentItems": "false"
}
login_name = "[email protected]"
client.users[login_name].send_mail(message_json)
client.execute_query()
ADAL Python library is utilized to authenticate users to Active Directory (AD) and obtain tokens
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
def get_token(auth_ctx):
"""Acquire token via client credential flow (ADAL Python library is utilized)"""
token = auth_ctx.acquire_token_with_client_credentials(
"https://graph.microsoft.com",
client_id,
client_secret)
return token
tenant_name = "contoso.onmicrosoft.com"
client = GraphClient(tenant_name, get_token)
drives = client.drives
client.load(drives)
client.execute_query()
for drive in drives:
print("Drive url: {0}".format(drive.web_url))
# retrieve drive properties (source)
drive = client.users[user_id_or_principal_name].drive
client.load(drive)
client.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
client.load(drive_items)
client.execute_query()
for drive_item in drive_items:
if not drive_item.file.is_server_object_null: # is file?
# download file content
with open(os.path.join(local_path, drive_item.name), 'wb') as local_file:
drive_item.download(local_file)
client.execute_query()
Refer OneDrive examples section for a more examples.
ADAL Python library is utilized to authenticate users to Active Directory (AD) and obtain tokens
The example demonstrates how create a new team under a group
which corresponds to Create team
endpoint
tenant_name = "contoso.onmicrosoft.com"
client = GraphClient(tenant_name, get_token)
new_team = client.groups[group_id].add_team()
client.execute_query()
where
def get_token(auth_ctx):
"""Acquire token via client credential flow (ADAL Python library is utilized)
:type auth_ctx: adal.AuthenticationContext
"""
token = auth_ctx.acquire_token_with_client_credentials(
"https://graph.microsoft.com",
client_id,
client_secret)
return token
The following libraries will be installed when you install the client library: