Office365-rest-python-client

Changelog

SharePoint API:

- `ListItem.validate_update_list_item` method: setting `dates_in_utc` as an _optional_ parameter (509)
- `Search` namespace enhancements 496


Example 1: submit search (KQL) query expression via `SearchService.query` method

python
ctx = ClientContext(site_url).with_credentials(credentials)
search = SearchService(ctx)
result = search.query("IsDocument:1").execute_query()



Example 2: construct sorting search results query and submit via `SearchService.post_query` method

python
ctx = ClientContext(site_url).with_credentials(credentials)
search = SearchService(ctx)
request = SearchRequest(query_text="IsDocument:1",
sort_list=[Sort("LastModifiedTime", 1)],
select_properties=["Path", "LastModifiedTime"],
row_limit=20)
result = search.post_query(request).execute_query()

Changelog

SharePoint API:

- `ListItem` introduced support for system metadata update (330)
- `SiteProperies.update` method bug fix 480
- `Web.ensure_folder_path` method bug fix 452


Support for `ListItem` system update

Prefer `ListItem.validate_update_list_item` method which supports overriding system metadata,
Here is an example which demonstrates how to update list item _system metadata_ (namely `Author` and `Modified` field values):

python
ctx = ClientContext(site_url).with_credentials(credentials)

list_tasks = ctx.web.lists.get_by_title("Tasks")
items = list_tasks.items.get().top(1).execute_query()
if len(items) == 0:
sys.exit("No items for update found")

item_to_update = items[0] type: ListItem
author = ctx.web.site_users.get_by_email(user_principal_name)

modified_date = datetime.utcnow() - timedelta(days=3)
result = item_to_update.validate_update_list_item({
"Author": FieldUserValue.from_user(author),
"Modified": modified_date
}).execute_query()

has_any_error = any([item.HasException for item in result.value])
if has_any_error:
print("Item update completed with errors, for details refer 'ErrorMessage' property")
else:
print("Item has been updated successfully")

Changelog


- 433: OneDrive API: support for downloading large files (via chunked download) by juguerre

Example:

python
from office365.graph_client import GraphClient
from office365.onedrive.driveitems.driveItem import DriveItem


def print_download_progress(offset):
print("Downloaded '{0}' bytes...".format(offset))


client = GraphClient(acquire_token_by_username_password)
1. address file by path and get file metadata
file_item = client.me.drive.root.get_by_path("archive/big_buck_bunny.mp4").get().execute_query() type: DriveItem
2 download a large file (chunked file download)
with tempfile.TemporaryDirectory() as local_path:
with open(os.path.join(local_path, file_item.name), 'wb') as local_file:
file_item.download_session(local_file, print_download_progress).execute_query()
print("File '{0}' has been downloaded into {1}".format(file_item.name, local_file.name))




- 430: improved support for overriding underlying HTTP request settings(such as proxy and SSL) by juguerre


- 465: SharePoint API: allow passing scopes via certificate authentication method by theodoriss

Example

python
from office365.sharepoint.client_context import ClientContext


cert_settings = {
'client_id': '-- app id--',
'thumbprint': "-- cert thumbprint--",
'cert_path': 'mycert.pem'),
'scopes': ['https://contoso.onmicrosoft.com/.default']
}

ctx = ClientContext(test_site_url).with_client_certificate(test_tenant, **cert_settings)
current_web = ctx.web.get().execute_query()
print("{0}".format(current_web.url))



- 461: include `pytz` to install dependency by Zahlii



- Microsoft Graph API: Improved support for delta queries ([official docs](https://docs.microsoft.com/en-us/graph/delta-query-overview))

Example: get incremental changes for users

python
client = GraphClient(acquire_token_func)
changed_users = self.client.users.delta.get().execute_query()

Changelog

List of changes:
- 234: determines if security validation expired and refresh if expired for SharePoint client
- SharePoint API enhanced support for `publishing` & `webhooks` namespaces
- Planner API model has been updated
- Outlook API enhancements, namely the support for download MIME content of a message


SharePoint API: create a Site Page

The example demonstrates how to create a [`Site Page`](https://docs.microsoft.com/en-us/openspecs/sharepoint_protocols/ms-pubcsom/80b6936f-abee-41fa-aa40-d5dfaa18c219)

python

ctx = ClientContext(team_site_url).with_credentials(client_credentials)
new_page = ctx.site_pages.pages.add()
new_page.save_draft(title="My news page")
new_page.publish().execute_query()


SharePoint API: create a new webhook

The example demonstrates how to create a webhook to SharePoint list:

python

ctx = ClientContext(site_url).with_credentials(client_credentials)
push_service_url = "https://westeurope0.pushnp.svc.ms/notifications?token=526a9d28-d4ec-45b7-81b9-4e1599524784"
target_list = client.web.lists.get_by_title("Documents")
subscription = target_list.subscriptions.add(push_service_url).execute_query()



where

push_service_url - your service endpoint URL. SharePoint sends an HTTP POST to this endpoint when events occur in the specified resource

Refer [Overview of SharePoint webhooks](https://docs.microsoft.com/en-us/sharepoint/dev/apis/webhooks/overview-sharepoint-webhooks) for a details.


Planner API: create a task ([`Create plannerTask` endpoint](https://docs.microsoft.com/en-us/graph/api/planner-post-tasks?view=graph-rest-1.0&tabs=http))

python
from office365.graph_client import GraphClient

client = GraphClient(acquire_token_func)
plan = ensure_plan(client.me.planner, "My plan")
task = client.planner.tasks.add(title="New task", planId=plan.id).execute_query()




Outlook API: download MIME content of a message ([`Get MIME content of a message` endpoint](https://docs.microsoft.com/en-us/graph/outlook-get-mime-message))

The example demonstrates how to download an Outlook message body in MIME format and save into a file:

python
client = GraphClient(acquire_token_func)
requires Mail.ReadWrite permission
user = client.users[test_user_principal_name]
messages = user.messages.select(["id"]).top(10).get().execute_query()
with tempfile.TemporaryDirectory() as local_path:
for message in messages: type: Message
with open(os.path.join(local_path, message.id + ".eml"), 'wb') as local_file:
message.download(local_file).execute_query() download MIME representation of a message

Changelog

Bug fixes
- 407 `SecurableObject.get_user_effective_permissions` de-serializing response bug fixed
- 400 improved support for managing file versions (SharePoint API)
- initial support for [Reports API](https://docs.microsoft.com/en-us/graph/reportroot-concept-overview) has been introduced
- initial support for [Search API](https://docs.microsoft.com/en-us/graph/search-concept-overview) has been introduced

Examples

Example: how to download a file version

python
ctx = ClientContext(team_site_url).with_credentials(client_credentials)
version = ctx.web.get_file_by_server_relative_path(file_url).versions.get_by_id(512)
with open(download_path, "wb") as local_file:
file = version.download(local_file).execute_query()


Documentation:


Example: how to determine what kind of permissions the user has on a file

Documentation: [`ListItem.GetUserEffectivePermissions` method](https://docs.microsoft.com/en-us/previous-versions/office/sharepoint-csom/jj862521(v=office.15))

python
from pprint import pprint

from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.permissions.permission_kind import PermissionKind


client = ClientContext(team_site_url).with_credentials(user_credentials)
file_url = "/sites/team/Shared Documents/Guide.docx"

target_user = client.web.site_users.get_by_email(test_user_principal_name_alt)
target_file = client.web.get_file_by_server_relative_path(file_url)
result = target_file.listItemAllFields.get_user_effective_permissions(target_user).execute_query()
pprint(result.value.permission_levels) print all permission levels

verify whether user has Reader role to a file
if result.value.has(PermissionKind.OpenItems):
print("User has access to read a file")



Example: how to get the count of Microsoft 365 activations on desktops and devices (via Reports API)

Documentation: [`reportRoot: getOffice365ActivationsUserCounts`](https://docs.microsoft.com/en-us/graph/api/reportroot-getoffice365activationsusercounts?view=graph-rest-1.0)

python
import msal
from office365.graph_client import GraphClient

def acquire_token_by_client_credentials():
settings = load_settings()
authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
app = msal.ConfidentialClientApplication(
authority=authority_url,
client_id=client_id,
client_credential=client_secret
)
return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

client = GraphClient(acquire_token_by_client_credentials)
result = client.reports.get_office365_activations_user_counts().execute_query()



Example: how to search files (via Search API)

Documentation: [use the Microsoft Search API to search content in OneDrive and SharePoint](https://docs.microsoft.com/en-us/graph/search-concept-files)

python
import msal
from office365.graph_client import GraphClient

def acquire_token_by_client_credentials():
settings = load_settings()
authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
app = msal.ConfidentialClientApplication(
authority=authority_url,
client_id=client_id,
client_credential=client_secret
)
return app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])

client = GraphClient(acquire_token_by_client_credentials)
result = client.search.query("Guide.docx", entity_types=["driveItem"]).execute_query()

Changelog

Bug fixes
- 402 and 387: removed _invalid_ dependency to `generator` module rikeshtailor
- 399: fix for downloading a file
- `Web.get_folder_by_server_relative_path` return type fix sharifhsn

Improvements:
- error handling improvements (in terms of covering network exceptions along with invalid HTTP requests) beliaev-maksim
- improvements for _JSON Batching_ support, for both v3 and [v4](https://docs.microsoft.com/en-us/graph/json-batching) versions