Решающая часть программирования – это возможность взаимодействовать с различными интерфейсами прикладного программирования (API). Если вы посетите Google API Explorer , вы найдете огромную библиотеку API, в том числе все их известные приложения, такие как Gmail, Drive и календарь. Проще говоря, API позволяет вам получать или отправлять данные на услуги через HTTP-запросы.
Использование и документация этих API могут сначала быть немного сложными, но как только вы узнаете его, вы сможете применить свои знания для большинства приложений Google.
Я решил написать руководство для начинающих для того, как использовать и понять API Gmail. Руководство основано на документации, означающее, что вы узнаете, что искать и как прочитать его вместо копирования кода. Поскольку большинство других документов Google API будут похожими, вы увидите, что адаптация к ним намного проще, как только вы знаете, как на самом деле прочитать документы. Это позволит вам написать свой собственный код и на самом деле понять, что вы делаете.
Python 3 используется в этом руководстве, но использование должно выглядеть очень похожи на других языках.
Быстрый старт
Google обычно предлагает руководство быстрому пути, чтобы облегчить авторизацию. Это руководство будет использовать авторизацию от руководства QuickStart, что означает, что он будет придет с некоторыми ограничениями, но это достаточно для наших целей. Другой способ получить ключ API заключается в создании нового проекта, который немного сложен.
Гид Python QuickStart можно получить доступ По этой ссылке , но я буду показывать вам, как все здесь сделано.
Вот что выглядит QuickStart:
Включить API Gmail
Первый шаг – включить API и загрузить учетные данные для использования в нашем проекте. Нажав кнопку «Включить кнопку Gmail API» * * *, мы открываем новое окно с нашими учетными данными.
Будет показан наш идентификатор клиента и секрет клиента. Выберите конфигурацию клиента для загрузки. Файл будет сохранен, называется Credgancys.json. Мы сохраним это в той же папке, в котором будет наш код.
Установка библиотек
Установка необходимых библиотек выполняется с помощью простой командой PIP, предоставленной Google. Я вставил его ниже. Я бы порекомендовал сделать это в Виртуальная среда Отказ То есть, однако, не покрыты в этом руководстве.
pip install — upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Первый запуск – разрешить доступ
Перед тем, как мы продолжим следовать в руководстве, нам нужно разрешить доступ к API Gmail для нашего сценария. Давайте начнем с того, что сделали настоящий скрипт.
Создать .py Файл в каталоге проекта (так же, как каталог с Cred angys.json). Ради этого, давайте назовем это Gmail.py.
Скопируйте пример код из Python QuickStart в файл gmail.py * *. Игнорируйте код на данный момент, мы погрузимся в это позже. Нам нужно разрешить доступ к первому запуску – оно будет сохранено только для всех позже.
Просто запустите файл, как обычно, и вы сможете войти в свою учетную запись Google в веб-браузере.
python gmail.py
Войдите в свой аккаунт. Предупреждение, говорящее, что приложение не подтверждено, будет показано. Как мы используем метод QuickStart, наше приложение еще не подтверждено. Просто нажмите на ссылку, показанную на рисунке, чтобы продолжить сейчас и разрешить доступ.
Понимание кода
Пример кода может сначала выглядеть подавлению, но я делю его на меньшие части, чтобы сохранить его простым. К концу вы увидите, что это на самом деле не так сложно.
Импорт и область
Как и в любом другом сценарии Python, мы начнем с импорта. Большинство импорта используются для авторизации с файлом Credentancys.json. Все они предоставляются по умолчанию, поэтому нам не нужно ничего менять.
Тем не менее, обладает наиболее важной частью. Эта переменная будет изменена позже, но на данный момент мы согласимся на прилагаемую область по умолчанию.
Что это говорит, это то, что он позволит нам получить доступ к данным из Gmail.readonly Scope. Есть еще много принципов, и это позволяет набор действий и запросов, которые мы можем сделать в API Gmail. Некоторые другие запросы требуют других областей.
Позже мы добавим еще один объем, чтобы использовать другие функции.
Реквизиты для входа
Авторизация, вероятно, является наиболее продвинутой частью сценария. Мы не будем слишком сильно погрузиться в это, так как он уже настроен на работу с коробки.
Это часть, то получает учетные данные, которые вы скачали из Credents.json. Во-первых, это ищет файл Token.pickle. Это файл, который создан, как только вы разрешили доступ к вашей учетной записи в первый раз. Если файл уже существует, он получает учетные данные от него, что означает, что вам не нужно разрешать доступ несколько раз.
Если файл TOKEN.PICKLE не существует, он загружает учетные данные из файла Cred angys.json. Это требует, чтобы вы разрешали доступ через веб-браузер, который вы сделали ранее.
Учетные данные в любом случае, сохранены в переменной CREDS для последующего использования.
API.
Это забавная часть скрипта: часть выбирает данные из API Gmail. Как видите, это на самом деле не так продвинуто. Это часть, которую мы смотрели глубже в.
Сервис построен с использованием ранее импортированной функции сборки. Учетные данные, которые мы получили ранее, передаются как аргумент.
Служба затем используется для получения всех меток Gmail для учетной записи, которая была авторизована. Данные сохраняются в переменной результатов.
Последняя строка сохраняет все ярлыки на метки переменной. Они отформатированы в виде списка, поэтому значение по умолчанию ([]) указано, если список пуст.
Следующая часть этого руководства будет смотреть на документацию, чтобы сделать некоторое смысл этого.
Результат
В конце напечатаны имена меток (если есть какие-либо).
Понимание документации
Так что это был код QuickStart Code. Тем не менее, это не имеет большого смысла без читания документации. Эта часть покажет вам, как на самом деле понять, что написано в коде, и как вы будете использовать документацию, чтобы написать свой собственный код.
Во-первых, давайте перейдем к вкладке «Ссылка» ** **, чтобы получить доступ к документам.
Влево, показано большое сводное меню. Это полно много информации, но это будет чрезвычайно полезно на предстоящем шаге.
Как мы работаем с этикетками, давайте выберем раздел users.labels, а также обзорная часть, чтобы получить базовую информацию о метках.
Нас приветствует этот экран:
Текст говорит, что этот список методов находится в конце страницы, а также Представления ресурсов ** ** метки. Информация обычно отправляется как JSON, которая обрабатывается как словари в Python.
Это информация о том, что каждая метка, которую мы привлекая. Если мы прокручиваем дальше, мы должны увидеть таблицу, которая предоставляет информацию о каждом свойстве в словаре.
Я подчеркнул название, потому что мы использовали его раньше. Мы получили доступ к названию этикетки, когда мы напечатали этикетки раньше. Нравится:
Этикетка в этом случае, в этом случае словарь, и мы получаем доступ к собственности имени внутри него. Мы могли бы получить доступ к любому другому свойству, которое называется выше, но на данный момент имя в порядке.
Важно отметить, что имя является строкой, но некоторые значения могут быть целыми числами. В документации легко найти легко.
Если мы продолжим прокручивать вниз к нижней части страницы, мы увидим все методы. Краткое описание каждого метода представлено, а также гиперссылка к документации.
Вы будете использовать разные методы в зависимости от того, что вы хотите сделать. Пример QuickStart использует метод списка для получения всех меток на учетной записи Gmail. Если мы хотели создать новую метку, мы использовали метод создания, который мы действительно сделаем позже.
Если мы вернемся к началу вершины и посмотрите на обзор на нашей левой, вы увидите, что у каждого метода есть своя кнопка меню.
Список метод
Давайте посмотрим посмотрите на метод списка, который мы использовали до нажатия списка в строке меню.
Это обеспечивает много полезной информации. Для начала запрос HTTP Get отправляется на этикетки URL для получения всех меток:
https://www.googleapis.com/gmail/v1/users/userId/labels
Мы могли бы сделать это вручную, например, в библиотеке запросов в Python. Однако мы будем использовать предоставленную библиотеку Google в этом руководстве.
Требуется авторизация, но мы уже заботились о этой части ранее.
И последнее, но не менее важно, параметры, которые мы можем перейти к способу списка. Как видите, UserID является единственным, который мы можем пройти.
UserID – это строка, которая представляет адрес электронной почты пользователя. Значение мне может использоваться вместо этого для указания аутентифицированного пользователя. На самом деле мы использовали значение Me в примерном коде.
Мы скоро пойдем глубже в этом, но сначала мы прочитаем другие части документации метода списка.
Авторизация и объем
Сценами могут звучать знакомо, это потому, что мы кратко затронули на нем раньше. Для доступа к способу списка требуется, по меньшей мере, один из предоставленных объемов.
Как видите, мы уже добавили Gmail.readonly Scope в верхней части нашего кода.
Ответ
Последняя часть показывает нам, какой успешный запрос вернет: тело в формате JSON. Все этикетки хранятся в виде списка, который можно получить доступ к клавише этикетки. В основном это:
list_of_labels = response["labels"]
Точно так же, как вы бы использовали обычный словарь в Python.
Сделать запрос списка
Давайте посмотрим на часть API нашего кода сейчас, когда мы собрали еще несколько информации из документации.
Во-первых, услуга построена с нашими учетными данными. Это просто база, которая используется для создания запросов (используя методы, которые мы ранее видели).
Далее мы фактически сделаем запрос, используя метод списка с помощью этого кода. Это может выглядеть немного более знакомым сейчас, как только мы просмотрели документы.
Чтобы легче показать вам, как построен синтаксис, у меня есть Color-Code код вместе с меню, чтобы показать вам, как работает API.
Начнем с переменной услуги. Просто следуя древовидной структуре, метод методом, мы наконец доберемся до метода списка.
Давайте на самом деле посмотрим на метод списка, а особенно знакомый параметр пользователя, который меня прошел как аргумент.
Если мы прокручиваем до вершины документации по методу списка, мы увидим краткое изложение параметров, о которых мы говорили ранее. Указан параметр пользователя, если мы не знаем, что это такое.
Мы просто передаем его как аргумент в метод списка в коде.
Как вы, вероятно, вспомните, запрос должен вернуть словарь в соответствии с ответной частью документации. Мы храним его в переменной результатов.
Чтобы получить доступ к этикеткам, мы используем метод. Получения словаря. Первый аргумент, который мы проходим, – это название того, что мы хотим получить (этикетки), а второй аргумент – это то, что мы возвращаем, если это не найдет ничего с этим именем.
Если нет ключа под названием этикетки, пустой список будет возвращен.
Так что это в основном, как прочитается документация и как работает метод списка. Давайте попробуем сделать что-то еще с начала, а не после документации API.
Создание новой этикетки
Давайте будем использовать наши новые знания и сделать что-то новое, что-то с нуля (почти).
Удалите все код, связанные с API из вашего документа. Сохраняйте только импорт, объем и обработку учетных данных. Мы постараемся создать новый ярлык через API.
Давайте отправимся на обзорные страницы меток. Прокрутите вниз к способам, чтобы увидеть, какой из них нам нужно использовать для создания нашего собственного метода.
Возможно, вы заметили, что есть метод, который буквально называется, создайте, что мы будем использовать. Перейдите в документацию этого метода, чтобы увидеть, что нам нужно.
Давайте начнем с авторизации и областями.
Как видите, нам требуется, по крайней мере, один из трех присутствующих присутствующих. Однако у нас нет ни одного из них в нашем коде. Давайте добавим Gmail.Labels Case.
Переменная SCOPES принимает список, что означает, что мы могли бы просто добавить новую область с помощью сепарации запяты.
Поскольку старая авторизация была сохранена в файле Token.pickle (и этот файл используется для авторизации, если он существует), нам нужно удалить его и повторно создать его с нашим новым объемом.
Запустите приложение Python снова с Python Gmail.py, чтобы повторно авторизовать, однако можно увидеть незначительные изменения:
Добавлена новая зависимость. Вы можете не понять это из-за шведского языка, но он в основном говорит: «Ручка этикетки». Таким образом, новый объем добавил новую зависимость на наше приложение.
Код
Если мы посмотрим на вершину документации по созданию метода, мы можем видеть, что он очень похож на метод списка. Это требует авторизации, он делает запрос HTTP Post и необходим параметр пользователя.
Но как-то нам нужно пройти фактическую метку в нашем запросе. Если мы прокручиваем к телу запроса, посмотрим, как это сделать.
В организме нашей просьбы следует присутствовать метка, по крайней мере, следующие свойства, чтобы создать метку:
labellistvisility.
MessageListvisility
имя
Вы можете узнать о том, какой тип они должны быть, а также то, что они, в документации.
Точно так же, как мы получили данные в словаре, данные должны быть отправлены в виде словаря.
Создание этикетки
Это простая функция для создания метки. Это требует названия и двух других необязательных аргументов. Если они не указаны, шоу и LabelShow будут использоваться в качестве по умолчанию.
Этикетка создана как словарь, а затем возвращается.
Чтобы создать метку с тестом имени, мы бы использовали синтаксис выше.
Сделать запрос на API
Время сделать реальный запрос на API и пропустите нашу ярлык на нашей учетной записи Gmail. Давайте будем следовать той же процедуре, что и в прошлый раз.
У меня есть цвет, кодированный путь к способу создания.
Мы не меняемся по сравнению с нашим последним вызовом API. Начнем с сервиса, который мы создали ранее, и добавляют каждый метод, пока мы не достигнем метода создания. Мы, однако, не полностью сделаны там.
Если мы прокручиваем параметры ** ** Часть документации, мы видим, что нам нужно пройти пользователь в качестве параметра, например, наш последний звонок.
Давайте снова использовали меня, как и документация предлагает.
Мы все еще не хватаем чего-то: фактическая этикетка. Нам нужно как-то пройти ярлык в нашем запросе. Давайте снова прокрутим к телу запроса.
Мы уже создали метку со всеми необходимыми свойствами, поэтому нам нужно пройти его в тело запроса. Это сделано, просто добавив другой параметр на метод создания, называемого корпусом.
Давайте передам наш объект этикетки в нем.
Фактический вызов сделан, но добавить некоторую проверку ошибок, давайте обернуем ее в оператор TRY/кроме.
Если что-то пойдет не так, сообщение об ошибке будет напечатано в нашей консоли. Если все идет как запланировано, создается этикетка, будет напечатана (и метка будет создана).
Итак, давайте посмотрим на части кода, который мы создали, чтобы сделать новый запрос API:
Обработка API на самом деле не так сложно. Фактическая выборка не требует многих строк кода – сложная часть – это авторизация, которую нам даже не нужно обращаться с собой.
Если мы сохраним и запустим код с помощью python gmail.py, на нашей учетной записи Gmail должна быть создана новая метка.
Выполнено!
Мы успешно сделали вызов API для Gmail с нуля и создал нашу собственную этикетку. Такого же основного принципа применяется к большинству других методов в API Gmail, а также другие API Google.
Не стесняйтесь, чтобы попробовать сделать другие запросы, чтобы понять это. Лучший способ учиться – это практиковать. Как только вы начнете понимать документацию, создавая свои собственные вызовы, разве это не так сложно.
Попробуйте создать свои собственные почтовые черновики или извлечь все сообщения входящие почты на основе запроса – все указано в документации.
Я предоставил Полный код На GitHub Если вы хотите посмотреть на окончательные результаты нашего примера. Удачи в ваших проектах и счастливого кодирования!
Оригинал: “https://dev.to/banjoanton/a-beginner-s-guide-to-the-gmail-api-and-its-documentation-4bm0”