Office 365 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 Microsoft Teams 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
- create a list item
- read a list item
- update a list item
- delete a list item
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 Microsoft Authentication Client compliant libraries such as adal are supported as well.
Using ADAL Python
Usage
import adal from office365.graph_client import GraphClient def acquire_token(): 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)
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) message_json = { "Message": { "Subject": "Meet for lunch?", "Body": { "ContentType": "Text", "Content": "The new cafeteria is open." }, "ToRecipients": [ { "EmailAddress": { "Address": "jdoe@contoso.onmicrosoft.com" } } ] }, "SaveToSentItems": "false" } login_name = "mdoe@contoso.onmicrosoft.com" client.users[login_name].send_mail(message_json) client.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(): """ 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) drives = client.drives client.load(drives) client.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) # retrieve drive properties 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.
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 tenant_name = "contoso.onmicrosoft.com" client = GraphClient(tenant_name, acquire_token) new_team = client.groups["{group_id}"].add_team() client.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.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 989f95a02d4b722d0fdd5c9f920d4b54bb0d91cf9312095ca8694e2dcc8b2aeb |
|
MD5 | c7609a50c9ae897842380050863cc589 |
|
BLAKE2-256 | e3feef2ef03c5caa209a29c336daa916eff9dcf498e43e3d31035d15077c0daa |
Hashes for Office365_REST_Python_Client-2.3.1-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ab9f62c0db73902a1602e4ffacc348348460c428939c3a4a4c913b6a03f033ad |
|
MD5 | 8e4574e106c1df26259f939533f6a7c6 |
|
BLAKE2-256 | 0f89a21bbcaff096ac6a209aa284db2c571a40792b646abc03a2adaf526833d8 |