Примечание: эта статья выражает всю мою боль и мучения, связанные с изучением процесса получения результата.
Все совпадения с реальными личностями или историческими событиями случайны. Я не испытываю ненависти к Google.
Gmail API это достаточно перспективный способ получения и управления содержимым почтового ящика Google для автоматизации различных процессов.
На примере этой статьи хотелось бы получать письма из почтового ящика по определенным критериям и присвоить определенную метку.
Всегда, конечно, есть способ получения через IMAP, но сейчас нужно еще и присваивать письмам определенные ярлыки и в перспективе производить всякие прочие манипуляции (отправка, удаление, перемещение внутри папок).
Для начала, нужно разобраться как работать с этим API. В этом нам будет помогать Will Smith и приложение для получения снимков экрана xscreenshot.
Чтобы получить доступ, нужно зайти на консоль разработчика и создать там приложение, которое будет работать с содержимым ящика.
console.cloud.google.com/home/dashboard
WTF? Кто я? Где я? Что я тут делаю?
Первым шагом будет создание приложения.
1. Нажать “Select a project”
2. В открывшемся окне нажать “New Project”.
Приложение можно как-то по-своему назвать для удобства.
После создания автоматически перенаправит на страницу панели управления приложением.
Если не произойдет перенаправление, можно выбрать его в выпадающем списке.
Чтобы не заморачиваться, сразу зайти в Apis&Services
Выбираем “ENABLE APIS AND SERVICES”
На открывшейся странице выбрать нужное api
Затем включить его
Крутилка покрутится и апи замутится.
Потом перекинет на страничку апи, где надо нажать “create credentials”
Затем, выбрать gmail api и другие пункты. Я выбрал “User Data” и нажал “Done”.
Возможно, нужно было выбрать “Application Data”, но это как-то в другой раз.
Дальше заходим в это свежесозданное API.
Создаем API key и OAuth client ID.
Заходим туда же, выбираем OAuth Client ID.
В принципе, думаю, достаточно создать только одного OAuth клиента.
Возникает такой экран:
Нажимаем, попадаем на страницу настройки.
Как показала практика, достаточно "Internal", меньше мороки с последующими проверками будет, не нужно будет подтверждать права на домен и т.д.
Заполняем указанные поля, жмем save & continue на нескольких последующих экранах ничего не заполняя.
Также нужно зайти в Credentials > ваше приложение и заполнить все поля Redirect URI.
Что бы не возникало неопределенности, я заполняю в двух вариантах: example.com/oauth и example.com/oauth/, т.е. без косой черты в конце и с косой чертой, т.к. есть мнение, что http запрос может не отработать без слеша в конце.
На этом пока все, надеюсь, ничего не упустил.
Для проверки можно сходить в песочницу, где можно из браузера делать запросы.
https://developers.google.com/gmail/api/reference/rest?apix=true
Для начала, хочу получить список лейблов, т.е., директорий в почтовом ящике.
Я планирую перекладывать письма в какой-то из ящиков, например “обработанные”, обозначая, что некий скрипт над ними потрудился и теперь они складываются куда-то в коробку.
Создаю ярлык "обработанные".
Заполняем поле UserID - собственный e-mail, делаем запрос. В результате видно список папок, в том числе, "обработанные".
Это был достаточно простой пример. В принципе, для начала достаточно, я сам не всё API исследовал.
Дальше, нужно получить список писем. Из них нужно будет взять id, по которым уже брать кадое отдельное письмо.
Первый запрос - получение списка писем.
https://developers.google.com/gmail/api/reference/rest/v1/users.messages/list
Пот вот этому ID письма можем делать с ним все, что угодно.
https://developers.google.com/gmail/api/reference/rest/v1/users.messages/modify
Например, присвоить ему созданную ранее метку.
Видим результат.
Теперь, было бы неплохо сделать то же самое из командной строки без всяких прочих фреймворков.
Для полноценной работы и так, что бы работало нормально нужно получить 4 вещи:
1. clientID
2. client secret
Идем сюда: console.cloud.google.com/apis/credentials?project
Жмем: OAuth 2.0 Client IDs
Находим client id и client secret, которые понадобятся дальше.
3. redirect uri
Это видимый извне ресурс, на который поисходит перенаправление в барузере после успешной авторизации.
Его примерный вид должен быть такой: https://example.com/oauth
Как заполняется карточка приложения для работы с API - написано чуть выше.
4. refresh token
Это специальный долговременный ключ, который нужен для получения короткоживущего ключа - Access Token, который используется в течение одного, например, запроса.
Для его получения [refresh token] нужно выполнить цепочку действий:
4.1 авторизоваться через браузер для получения кода OAuth. Как собрать такую ссылку на bash показываю ниже. Потом достаточно просто скопировать url и перейти по нему. Или можно вручную подставить свои параметры в ссылку.
https://accounts.google.com/o/oauth2/auth?client_id=[client_id]&redirect_uri=https://example.com/googleoauth/&scope=hxxps://mail.google.com/&response_type=code&include_granted_scopes=true&access_type=offline&login_hint=user@example.comprompt=consent&state=qwerty
Варик на баше:
Такие параметры как &access_type=offline&login_hint= Этот адрес электронной почты защищен от спам-ботов. У вас должен быть включен JavaScript для просмотра. &;prompt=consent&state=qwerty влияют на то, что в ответе будет именно пригодный для автоматизации refresh_token.
После авторизации перекинет на страницу, на которой в адресной строке в виде параметра будет код для отправки запроса на получение Refresh Token. Тут кликнуть по указанному аккаунту или ввести другой, ну, если вы дочитали до этого места и хоть что-то поняли, то не запутаетесь.
Подтвердить, разрешить.
Код получить.
С этим кодом нужно сделать curl запрос для получения refresh token - долговременного ключа, который необходим для выдачи кратковременных ключей доступа - access token.
Может быть такая боль:
{
"error": "invalid_grant",
"error_description": "Bad Request"
}
Тут надежного рецепта нет, только четкое пошаговое выполнение инструкции. В случае такого ответа надо проверить синтаксис запроса, все настройки и разрешения приложения. Как вариант, закодировать урленкодом тело curl запроса.
К статье прикрепляю текстовый файл с запросами, если в тексте поломается или криво отобразится
Если четко следовать инструкции, будет примерно такой ответ:
{
"access_token": "ya29.A0ARrdaM-MrStK_J1_w1QHphocG6efc7VdsJVqsygtYяяяяяяяяяяяяЙЙЙЙЙЙЙЙЙЙЙооооооооооЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ",
"expires_in": 3599,
"refresh_token": "1//0cp3SZfDYжжжжжжжжжжОООООООООООООООппппппппппппААААААААААААААА",
"scope": "https://mail.google.com/",
"token_type": "Bearer"
}
В этом ответе есть refresh_token, который можно куда-то сохранить и периодически дергать апи для получения access_token, который, собственно, и дает доступ к апи.
Дальше можно сходить в песочницу гугля, скопировать оттуда пример запроса и, подставив свой access_token, делать запросы.
https://developers.google.com/gmail/api/reference/rest/v1/users.messages/list
| Файл | Описание | Размер файла: |
|---|---|---|
 gmail_api.txt | 0.5 Кб |