Phenquestions
Люди в GitHub и сторонние разработчики не могут справиться со всей этой сложностью без общего интерфейса. Этот общий интерфейс - это то, что мы называем GitHub API. Каждая утилита GitHub, такая как cli, веб-интерфейс и т. Д., Использует этот общий интерфейс для управления ресурсами (ресурсы являются объектами, такими как репозитории, ключи ssh и т. Д.).
В этом руководстве мы познакомимся с некоторыми основами взаимодействия с API с помощью GitHub API v3 и Python3. Последняя версия 4 GitHub API требует, чтобы вы узнали о GraphQL, что приводит к более крутой кривой обучения. Поэтому я буду придерживаться только третьей версии, которая все еще активна и довольно популярна.
Как поговорить с веб-API
Веб-API - это то, что позволяет вам использовать все услуги, предлагаемые веб-приложением, например GitHub, программно, используя язык по вашему выбору. Например, мы собираемся использовать Python для нашего варианта использования, здесь. Технически вы можете делать все, что делаете на GitHub, используя API, но мы ограничимся чтением только общедоступной информации.
Ваша программа Python будет взаимодействовать с API точно так же, как ваш браузер общается с веб-сайтом. То есть в основном через HTTPS-запросы. Эти запросы будут содержать разные «части», начиная с метода запроса [GET, POST, PUT, DELETE], самого URL-адреса, строки запроса, заголовка HTTP и тела или полезной нагрузки. Большинство из них не являются обязательными. Однако нам нужно будет предоставить метод запроса и URL-адрес, по которому мы делаем запрос.
Что это такое и как они представлены в запросе HTTPS, мы увидим медленно, когда начнем писать скрипты Python для взаимодействия с GitHub.
Пример
Добавление ключей SSH к вновь созданному серверу - всегда неуклюжий процесс. Давайте напишем сценарий Python, который будет извлекать ваши общедоступные ключи SSH из GitHub и добавлять их в файл authorized_keys на любом сервере Linux или Unix, на котором вы запускаете этот сценарий. Если вы не знаете, как сгенерировать или использовать ключи SSH, вот отличная статья о том, как это сделать. Я предполагаю, что вы создали и добавили свои собственные общедоступные ключи SSH в свою учетную запись GitHub.
Очень простая и наивная реализация Python для достижения описанной выше задачи показана ниже:
запросы на импортимпорт ОС
# Получение пользовательского ввода
unix_user = input ("Введите свое имя пользователя Unix:")
github_user = input ("Введите свое имя пользователя GitHub:")
# Убедиться .Каталог ssh существует и открытие файла authorized_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
если не ос.дорожка.существует (ssh_dir):
Операционные системы.македирс (ssh_dir)
авторизованный_ключ_файл = открытый (ssh_dir + 'authorized_keys', 'a')
# Отправка запроса в GiHub API и сохранение ответа в переменной с именем'response '
api_root = "https: // api.github.com "
request_header = 'Принять': 'application / vnd.github.v3 + json '
ответ = запросы.получить (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Обработка ответа и добавление ключей в файл authorized_keys
для я в ответ.json ():
авторизованный_keys_file.написать (я ['ключ'] + '\ n')
Давайте проигнорируем обработку файлов Python и прочие детали и строго посмотрим на запрос и ответ. Сначала мы импортировали модуль запросов на импорт, эта библиотека позволяет нам очень легко выполнять вызовы API. Эта библиотека также является одним из лучших примеров правильно выполненного проекта с открытым исходным кодом. Вот официальный сайт, если вы хотите поближе познакомиться с документами.
Далее мы устанавливаем переменную api_root.
api_root = "https: // api.github.com "Это общая подстрока во всех URL-адресах, к которым мы будем обращаться к API. Поэтому вместо того, чтобы набирать «https: // api.github.com »каждый раз, когда нам нужно получить доступ к https: // api.github.com / users или https: // api.github.com / users /api_root + '/ users /' или же api_root + '/ пользователи / как показано во фрагменте кода.
Затем мы устанавливаем заголовок в нашем запросе HTTPS, указывая, что ответы предназначены для API версии 3 и должны быть в формате JSON. GitHub будет уважать эту информацию заголовка.
1. GET запрос
Итак, теперь, когда у нас есть наш URL и (необязательная) информация заголовка, хранящаяся в разных переменных, пришло время сделать запрос.
ответ = запросы.получить (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Запрос имеет тип get, потому что мы читаем общедоступную информацию с GitHub. Если бы вы что-то писали под своей учетной записью GitHub, вы бы использовали POST. Точно так же другие методы предназначены для других функций, например, DELETE предназначен для удаления ресурсов, таких как репозитории.
2. Конечная точка API
Конечная точка API, к которой мы обращаемся:
https: // api.github.com / users /У каждого ресурса GitHub есть собственная конечная точка API. Ваши запросы на GET, PUT, DELETE и т. Д. Затем отправляются на указанную вами конечную точку. В зависимости от уровня доступа, который у вас есть, GitHub либо разрешит вам выполнить этот запрос, либо отклонит его.
Большинство организаций и пользователей на GitHub устанавливают огромное количество информации, доступной для чтения и общедоступной. Например, в моей учетной записи пользователя GitHub есть несколько общедоступных репозиториев и общедоступные ключи SSH, доступ к которым может читать любой (даже без учетной записи пользователя GitHub). Если вы хотите более детально контролировать свою личную учетную запись, вы можете сгенерировать «токен личного доступа» для чтения и записи конфиденциальной информации, хранящейся в вашей личной учетной записи GitHub. Если вы пишете стороннее приложение, предназначенное для использования другими пользователями, то токен OAuth указанного пользователя - это то, что потребуется вашему приложению.
Но, как видите, много полезной информации можно получить без создания токена.
3. Ответ
Ответ возвращается с сервера API GitHub и сохраняется в переменной с именем response. Полный ответ можно прочитать несколькими способами, как описано здесь. Мы явно запросили содержимое типа JSON у GitHub, поэтому мы обработаем запрос, как будто это JSON. Для этого мы вызываем метод json () из модуля запросов, который декодирует его в собственные объекты Python, такие как словари и списки.
Вы можете увидеть, как ключи добавляются в файл authorized_keys в этом цикле for:
для я в ответ.json ():авторизованный_keys_file.написать (я ['ключ'] + '\ n')
Если вы распечатаете ответ.json (), вы заметите, что это список Python со словарями Python в качестве членов. В каждом словаре есть ключ с именем «ключ» с вашим публичным SSH-ключом в качестве значения этого ключа. Таким образом, вы можете добавлять эти значения одно за другим в свой файл authorized_keys. И теперь вы можете легко подключиться к серверу по SSH с любого компьютера, на котором есть какие-либо закрытые SSH-ключи, соответствующие одному из открытых ключей, которые мы только что добавили.
Дальнейшие исследования
Большая работа с API требует тщательного изучения самой документации API, а не написания строк кода. В случае GitHub документация - одна из лучших в отрасли. Но чтение документации API и выполнение вызовов API с использованием Python довольно неинтересно как отдельное действие.
Прежде чем идти дальше, я бы порекомендовал вам придумать одну задачу, которую вы хотели бы выполнить с помощью Python в своей учетной записи GitHub. Затем попробуйте реализовать его, прочитав только официальную документацию, предоставленную Python, его зависимыми библиотеками и GitHub. Это также поможет вам выработать более здоровый образ мышления, при котором вы понимаете, что происходит внутри вашего кода, и постепенно улучшаете его.
