Что Microsoft известно о вас, и как эту информацию можно использовать для получения полезных знаний

Значительная часть моих ежедневных действий на компьютере и смартфоне выполняется с помощью приложений 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.

• Сервер авторизации: этот сервер предоставляет конечному пользователю (Владельцу ресурса) возможность аутентифицироваться. После правильно осуществленной авторизации Сервер авторизации создает маркер доступа к приложению.

  

Теперь рассмотрим, как в 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-запросы. Надеюсь, эта статья поможет вам в автоматизации процессов.

Узнайте, как прокачаться в других специальностях или освоить их с нуля:

• Профессия Data Scientist

• Профессия Data Analyst

• Курс по Data Engineering