12.wrapping-apis.pdf
- 1. Пакет - обёртка над API Разбираемся с HTTP запросами и пакетом httr2 Алексей Селезнёв
- 3. API – Application Programing Interface, программный интерфейс приложения
- 4. HTTP запросы • Составляющие HTTP запроса • URL адрес • Метод (GET, POST, DELETE, PUT) • Заголовки • Тело запроса • GET параметры • Составляющие ответа • Статус (1**, 2**, 3**, 4**, 5**) • Заголовки • Тело
- 5. Семейства функций пакета httr2 • request() – Создаёт объект запроса • req_*() – Функции для компоновки запроса • req_headers() – добавить в запрос заголовки • req_body_raw(), req_body_file(), req_body_json(), req_body_form(), req_body_multipart() – тело запроса • req_perform() – Отправка запроса • req_url_query() – Добавление GET параметров запросу • resp_*() – Функции извлечения элементов ответа от сервера • resp_body_raw(), resp_has_body(), resp_body_string(), resp_body_json(), resp_body_html(), resp_body_xml() – парсинг тела ответа • resp_headers(), resp_header() – Извлечение заголовков ответов • resp_status(), resp_status_desc(), resp_is_error() – Проверка статуса ответа
- 6. Этапыработыс API 1. Авторизация 2. Компоновка и отправка запроса 3. Получение ответа, и приведение его к необходимому виду
- 7. Управление конфиденциальными данными Процесс авторизации зачастую реализован одним из двух способов • Токен привязан к вашему аккаунту, и находится в его настройках (например Githyb_PAT) • Авторизация проходит по специальному протоколу Oauth (facebook, google, twitter, …)
- 8. Управление конфиденциальными данными В упрощённом варианте, когда ваш токен хранится в настройках аккаунта используйте следующий механизм для добавления таких учётных данных в пакет 1. Создайте ключ шифрование командой secret_make_key() 2. Зашифруйте токен с помощью secret_encrypt() 3. Расшифровывайте токен с помощью команды secret_decrypt()
- 9. Управление конфиденциальными данными в пакете Логика httr2 заключается в том, что вы создаёте один ключ шифрования для каждого пакета, и помещаете его в переменную среды YOURPACKAGE_KEY 1. С помощью функции usethis::edit_r_environ() откройте и отредактируйте .Renviron файл вашего пакета, добавив в него переменную среды, поместив в неё ключ созданный с помощью команды secret_make_key() 2. Используйте команды secret_encrypt() и secret_decrypt() передав в аргумент key не сам ключ, а имя переменной среды, в которой хранится ключ. 3. Добавьте ключ в раздел repository secrets 4. Расшарьте ключ на рабочие процессы GHA, которым он нужен, добавив строку в соответствующий рабочий процесс:
- 10. Ключ не доступен • В виньетках вы можете запустить knitr::opts_chunk(eval = secret_has_key("YOURPACKAGE_KEY")), чтобы код внутри чанков выполнялся только в том случае, если ваш ключ доступен. • В примерах вы можете окружить блоки кода, для которых требуется ключ, с помощью if (httr2::secret_has_key("YOURPACKAGE_KEY")) {} . • Тесты не требуют от вас дополнительных действий, т.к. когда secret_decrypt() запускается в testthat, он автоматически запускает skip() для пропуска теста, если ключ недоступен.
- 11. Обработка ошибок • Создайте отдельную вспомогательную функцию, которая будет принимать объект ответа от API, и возвращать сообщение об ошибке • При отправке запроса добавьте глагол req_error(), и в аргумент body передайте созданную в предыдущем пункте функцию.
- 12. OAuth 1. Создаёте приложение, для получения его ID и Secret 2. Далее из R запускаете браузер для генерации токена, либо кода для обмена на токен 3. Если на предыдущем шаге вы получили код, следующим шагом надо его обменять на токен 4. Далее кешируете полученный токен, можно в локальный файл 5. Многие API выдают токены с ограниченным сроком работы, такие токены по истечению этого срока необходимо обновлять, зачастую отдельным запросом
- 13. Обзор всего рабочего процесса 1. Изучаете раздел документации по авторизации в API 2. Реализуете часть кода по прохождению авторизации, т.к. вам нужен токен для дальнейшей работы 3. Изучаете документацию эндпоинтов и ресурсов API, с целью найти общие паттерны 4. Изучаете отдают ли какую то полезную информацию ошибочные запросы 5. Изучаете существующие лимиты 6. Создаёте общую функцию для компоновки запросов 7. Оборачиваете в отдельные функции все эндпонинты, основой для этих обёрток должна быть функция из предыдущего пункта
- 14. Заголовок слайда