Skip to main content

Microsoft 365 & Microsoft Graph Library for Python

Project description

About

Office 365 & Microsoft Graph library for Python

Usage

  1. Installation
  2. Working with SharePoint API
  3. Working with Outlook API
  4. Working with OneDrive API
  5. Working with Teams API
  6. Working with OneNote API
  7. Working with Planner API

Status

Downloads PyPI PyPI pyversions Build 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:

Authentication

The following auth flows are supported:

Examples

There are two approaches available to perform API queries:

  1. ClientContext class - where you target SharePoint resources such as Web, 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']))
  1. 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:

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 API v2.0 version (preferable nowadays, refer transition to Microsoft Graph-based Outlook REST API for a details)
    - OutlookClient which targets Outlook API v1.0 version (not recommended for usage since v1.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

OneDrive Graph API reference

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:

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Office365-REST-Python-Client, version 2.3.10
Filename, size File type Python version Upload date Hashes
Filename, size Office365_REST_Python_Client-2.3.10-py3-none-any.whl (463.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size Office365-REST-Python-Client-2.3.10.tar.gz (232.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page