Значительная часть моих ежедневных действий на компьютере и смартфоне выполняется с помощью приложений Microsoft. Отправить электронную почту, создать заметку в календаре, просмотреть файлы в облачном хранилище, обменяться сообщениям в рабочих группах — все эти операции так или иначе выполняются приложениями Microsoft. Нравится мне это или нет, все мои данные хранятся в Microsoft Cloud. У Microsoft имеется полезный инструмент — API-интерфейс, предоставляющий доступ к большей части таких данных и позволяющий управлять ими, так почему бы им не воспользоваться для получения полезной информации?
В этой статье представлено полное руководство по созданию собственного приложения Dashboard с использованием API Microsoft Graph и Django для анализа данных платформ OneDrive, Outlook и др.
Чтобы понять, о чём пойдет речь в этой статье, взгляните на следующий скриншот. Из статьи вы узнаете:
о моём опыте работы с API, о том, как самому создавать запросы для доступа к данным;
о том, как работает процесс аутентификации, предоставляющий приложениям необходимые разрешения;
о том, как осуществляются обработка и визуализация данных в Django.
Оглавление
Краткое руководство по Microsoft Graph — быстрый способ начать работу с API Microsoft Graph.
OAuth 2.0 — как работает процесс регистрации в системе.
Запрос данных с использованием Graph API.
Анализ и визуализация данных с помощью Plotly.
Выводы.
Краткое руководство по Microsoft Graph — быстрый способ начать работу с API Microsoft Graph
Несколько лет назад Microsoft перешла с Live SDK на Microsoft Graph. Теперь в качестве API для доступа ко всем данным и информации платформы Microsoft 365 выступает Microsoft Graph [1, 2].
Начать работу в API Microsoft Graph можно несколькими способами. Самый простой из них — использовать Краткое руководство по Microsoft Graph, с помощью которого создаются новый App ID и App Secret для процесса аутентификации, и в итоге будет создан типовой проект.
(1) На первом шаге нужно определить язык программирования, который будет использоваться для создания приложения. Поскольку я предпочитаю Python, для создания примера приложения я воспользуюсь простым приложением Django.
Если Вы не знакомы с Django, можете прочитать одну из моих предыдущих статей, в которых максимально простым языком поясняются принципы работы Django. Если приложение будет создаваться с нуля, за необходимой справкой обратитесь к соответствующему руководству в Microsoft Docs.
(2) После выбора языка создаётся новый App ID с App Secret — они понадобятся позже для процесса авторизации.
Просмотреть список зарегистрированных приложений можно на портале Azure в каталоге Azure Active Directory.
(3) После выполнения команд, описанных в Кратком руководстве по Microsoft Graph, будет создано типовое приложение с готовой основной структурой и процессом аутентификации. Загрузите пример кода и сохраните его в словаре проекта.
Структура примера кода аналогична структуре обычного приложения Django. Файл oauth_settings.yml содержит настройки для аутентификации — требуемые конечные точки, App ID и App Secret.
Требования к установке
(4) До первого запуска приложения необходимо установить необходимые пакеты Python.
Простой способ установки всей среды определён в файле requirements.txt [3]. Поскольку для работы приложений иногда требуются определённые версии библиотеки, имеет смысл создать Виртуальную среду [4]. Для этого перейдите в каталог проекта и запустите следующую команду: virtualenv_graph. Будет создана Виртуальная среда.
python -m venv virtualenv_graphВ папке проекта появится новый каталог virtualenv_graph с копией интерпретатора Python. Для работы с только что созданной средой graph-tutorial её необходимо активировать, запустив пакетный файл activate:
graph-tutorial\Scripts\activate.batПосле активации в начале командной строки появится имя вашей Виртуальной среды (в скобках). Так вы поймёте, что среда активирована. Все необходимые пакеты Python устанавливаются в среде следующей командой:
Migrate — распространение изменений на базу данных
(5) Следующая команда отображает используемую в приложении структуру модели на базу данных:
python manage.py migrateВ результате будут созданы определённые таблицы по умолчанию для используемых приложений Django: django.contrib.auth и django.contrib.session.
(6) Команда python manage.py runserver запускает облегчённый веб-сервер на локальной машине. Если не будет указано иное, локальный веб-сервер использует порт 8000 и имеет адрес 127.0.0.1.
Теперь можно входить в систему, используя регистрационные данные учётной записи на портале Office365.
OAuth 2.0 — как работает процесс регистрации
Для понимания того, что делает данный пример кода, нужно представлять, какие функции выполняет протокол OAuth 2.0.OAuth 2.0 — стандартный отраслевой протокол аутентификации, позволяющий пользователям предоставлять сторонним приложениям доступ к ресурсам пользователей без предоставления таким приложениям доступа к вашим постоянным учётным данным [5, 6].
Такую функциональность можно реализовать, так как уровень авторизации протокола OAuth отделяет роль клиента от роли владельца ресурса. Не очень понятно? Постараюсь объяснить, какие роли задействуются в потоке рабочих операций протокола OAuth и как они связаны друг с другом [5].
Владелец ресурса: лицо, предоставляющее доступ к ресурсу. В нашем случае доступ к данным Microsoft Cloud через вашу учётную запись на платформе Microsoft 365 предоставляете приложению вы, то есть владельцем ресурса являетесь вы.
Сервер ресурсов: место, в котором размещаются защищённые ресурсы.
Клиент: приложение, запрашивающее доступ к ресурсу, в данном случае — только что скачанное нами приложение Django.
Сервер авторизации: этот сервер предоставляет конечному пользователю (Владельцу ресурса) возможность аутентифицироваться. После правильно осуществленной авторизации Сервер авторизации создает маркер доступа к приложению.
OAuth 2.0 для веб-серверных приложений.
Теперь рассмотрим, как в Python запускается рабочий поток авторизации с помощью приложения Template.
Запрос маркера доступа с Платформы удостоверений Microsoft
Как я уже сказал, вначале приложение должно отправить запрос на Сервер аутентификации. Поэтому нам нужно использовать версию протокола OAuth 2.0. для Платформы удостоверений Microsoft [7].
Нажатие кнопки Sign-in вызывает функцию sign_in в tutorial.views.py, которая для формирования URL-запроса, в свою очередь, вызывает функцию get_sign_in_url.На первом шаге потока операций авторизации клиентское приложение направляет пользователей к конечной точке /authorize. В запросе указываются [7]:
ID приложения, назначенное вашему приложению в процессе регистрации;
переменная scope, в которой определяются разрешения, запрашиваемые приложением у пользователя;
URI перенаправления — расположение, в котором Сервер авторизации отправляет пользователя после успешной авторизации приложения и предоставления ему кода авторизации или маркера доступа.
Все параметры, необходимые для выполнения процесса авторизации, хранятся в YAML-файле oauth_settings.yml.
(3) После того как пользователь аутентифицируется и, соответственно, предоставит доступ приложению, Сервер аутентификации сформирует ответ с Кодом авторизации и перенаправит пользователя на указанный URI перенаправления.
(4) Имея App ID и App Secret, вы можете запросить у Сервера авторизации Маркер доступа и Маркер обновления.
(5) Маркер доступа разрешает доступ к API по крайней мере в той части, в которой требуемые разрешения были определены в переменной scope.
Таким образом, мы получили доступ к запрашиваемым ресурсам. Теперь надо понять, как извлечь интересующие нас данные.
Запрос данных с использованием Graph API
Для поиска соответствующих конечных точек данных используется Обозреватель Graph. В этом средстве разработчика уже реализован ряд запросов, связанных с вашей учётной записью и различными приложениями Microsoft. Если нужно найти информацию, не охватываемую такими запросами, обратитесь к соответствующим документам (например, для OneDrive).
Меня, в частности, интересуют данные, хранящиеся на моём облачном диске One Drive. Но общая концепция извлечения данных одинакова для SharePoint, OneNote, Outlook, Teams и многих других платформ.
При работе с другими платформами к переменной scope в файле oauth_settings.yml нужно добавить соответствующие разрешения. Процедура добавления разрешений описана здесь: Справка по разрешениям в Microsoft Graph. Для того чтобы можно было считывать и записывать файлы в One Drive, добавьте к переменной scope параметр Files.ReadWrite.All. Приведу пример: мне нужно получить информацию по всем файлам в папке /Bilder/Eigene Aufnahmen. Вместе с только что сгенерированным Маркером доступа я отправляю запрос GET на /drive/root:/<path>:/children и получаю данные по всем файлам указанного пути.
# <graph_helper.py>
def get_one_drive_items(token):
graph_client = OAuth2Session(token=token)
# Send GET to /drive/root
items = graph_client.get('{0}/drive/root:/Bilder/Eigene Aufnahmen:/children'.format(graph_url))
# Return the JSON result
return items.json()
# <views.py>
def one_drive(request):
context = initialize_context(request)
token = get_token(request)
files = get_one_drive_items(token)
for file in files['value']:
file['DownloadUrl'] = file['@microsoft.graph.downloadUrl']
context['files'] = files['value']
return render(request, 'tutorial/one_drive.html', context)И последнее, что делает функция просмотра one_drive, — формирует HTML-файл one_drive.html для распечатки только что полученных данных из API. Структура файла one_drive.html аналогична структуре файла calendar.html, уже имеющегося в типовом приложении.
{% extends "tutorial/layout.html" %}
{% block content %}
<h1>Pictures uploaded to One Drive</h1>
<table class="table">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Created</th>
<th scope="col">Download Link</th>
</tr>
</thead>
<tbody>
{% if files %}
{% for file in files %}
<tr>
<td>{{ file.name }}</td>
<td>{{ file.createdDateTime }}</td>
<td><a href="{{ file.DownloadUrl }}">Download</a></td>
</tr>
{% endfor %}
{% endif %}
</tbody>
</table>
{% endblock %}Теперь нужно добавить функцию просмотра one_drive к модулю прокладки маршрута urls.py.
# <tutorial.urls.py>
from django.urls import path
from . import views
urlpatterns = [
...
path('calendar', views.calendar, name='calendar'),
path('one_drive', views.one_drive, name='one_drive'),
]Теперь по адресу http://localhost:8000/one_drive выводится HTML-таблица со всеми файлами в папке /Bilder/Eigene Aufnahme.
Анализ и визуализация данных с помощью Plotly.
Для визуализации данных я использовал библиотеку Plotly. Если эта библиотека не установлена, установите Plotly, используя команду pip:
pip install plotlyМеня интересует время, когда были сделаны фотографии.Чтобы результат стал более наглядным, я сгруппирую фотографии по неделям, когда они были сделаны.
Для этого я добавляю новую пару «ключ — значение» в словарь files['values'], определяемый как календарная неделя даты создания. После этого я передаю значения словаря в кадр данных Pandas. В Pandas реализовано несколько методов управления кадрами данных, я воспользуюсь одним из них. Операция groupby группирует все записи по атрибуту CreationWeek, метод .count() осуществляет подсчёт количества всех вхождений записей.
def one_drive(request):
context = initialize_context(request)
token = get_token(request)
files = get_one_drive_items(token)
for file in files['value']:
file['DownloadUrl'] = file['@microsoft.graph.downloadUrl']
file['CreationDay'] = datetime.datetime.strptime(file['createdDateTime'], '%Y-%m-%dT%H:%M:%S.%fZ').date()
file['CreationWeek'] = str(file['CreationDay'].isocalendar()[1]) + '-' + str(file['CreationDay'].year)
# sum all items by calendar week
items_df = pd.DataFrame.from_dict(files['value'])
items_df = items_df.groupby(by="CreationWeek", dropna=False).count()
items_df.rename(columns={'createdDateTime': 'count'}, inplace=True)
# define new figure with plotly
fig = px.bar(x=items_df.index.tolist(),
y=items_df['count'].tolist(),
labels=dict(x="Calendar Week", y="Number of umploaded pictures")
)
# graph plot
plt_div = plot(fig, output_type='div')
# define context
context['files'] = files['value']
context['plot_div'] = plt_div
return render(request, 'tutorial/one_drive.html', context)Результат выводится в виде столбчатой диаграммы. Мы рассмотрели простой пример поэтапного создания собственного приложения для информационной панели (дашборда), в котором демонстрируется способ доступа к службам Microsoft.
Выводы
В этой статье я поделился опытом работы с API-интерфейсом Microsoft Graph. Мы узнали, как выполняются:
1) процесс аутентификации с использованием Платформы удостоверений Microsoft;
2) запрос данных через Graph API;
3) визуализация данных с использованием Plotly.
Помимо извлечения данных в интерфейсе Graph реализован широкий спектр функций POST. Добавление записей в календарь, загрузка файлов, создание нового канала Microsoft Team — все эти операции можно осуществлять через HTTP-запросы. Надеюсь, эта статья поможет вам в автоматизации процессов.
Полезные ссылки
Узнайте, как прокачаться в других специальностях или освоить их с нуля:
Другие профессии и курсы
ПРОФЕССИИ
КУРСЫ
