Phenquestions
Tanto la gente de GitHub como los desarrolladores externos no pueden gestionar toda esta complejidad sin una interfaz común. Esta interfaz común es lo que llamamos API de GitHub. Todas las utilidades de GitHub, como cli, interfaz de usuario web, etc., utilizan esta interfaz común para administrar recursos (los recursos son entidades como repositorios, claves ssh, etc.).
En este tutorial aprenderemos algunos conceptos básicos de cómo se interactúa con una API usando GitHub API v3 y Python3. La última versión 4 de la API de GitHub requiere que aprenda sobre GraphQL, lo que da como resultado una curva de aprendizaje más pronunciada. Así que me limitaré a la versión tres, que todavía está activa y es bastante popular.
Cómo hablar con una API web
Las API web son las que le permiten utilizar todos los servicios ofrecidos por una aplicación web, como GitHub, mediante programación utilizando el lenguaje de su elección. Por ejemplo, vamos a utilizar Python para nuestro caso de uso, aquí. Técnicamente, puede hacer todo lo que hace en GitHub usando la API, pero nos limitaremos a leer solo la información de acceso público.
Su programa Python hablará con una API de la misma manera que su navegador se comunicará con un sitio web. Es decir, principalmente a través de solicitudes HTTPS. Estas solicitudes contendrán diferentes 'partes', comenzando por el método de la solicitud [GET, POST, PUT, DELETE], la URL en sí, una cadena de consulta, un encabezado HTTP y un cuerpo o una carga útil. La mayoría de estos son opcionales. Sin embargo, necesitaremos proporcionar un método de solicitud y la URL a la que estamos realizando la solicitud.
Qué son y cómo se representan en una solicitud HTTPS es algo que veremos lento a medida que comencemos a escribir Python Scripts para interactuar con GitHub.
Un ejemplo
Agregar claves SSH a un servidor recién creado es siempre un proceso torpe. Escribamos un script de Python que recuperará sus claves SSH públicas de GitHub y lo agregará al archivo Authorized_keys en cualquier servidor Linux o Unix donde ejecute este script. Si no sabe cómo generar o usar claves SSH, aquí hay un excelente artículo sobre cómo hacer exactamente eso. Asumiré que ha creado y agregado sus propias claves SSH públicas a su cuenta de GitHub.
Una implementación de Python muy simple e ingenua para lograr la tarea que describimos anteriormente es la que se muestra a continuación:
solicitudes de importaciónimportar sistema operativo
# Obteniendo información del usuario
unix_user = input ("Ingrese su nombre de usuario Unix:")
github_user = input ("Ingrese su nombre de usuario de GitHub:")
# Asegurándose .El directorio ssh existe y abre el archivo Authorized_keys
ssh_dir = '/ inicio /' + unix_user + '/.ssh / '
si no os.camino.existe (ssh_dir):
os.makedirs (ssh_dir)
autorizado_keys_file = open (ssh_dir + 'autorizado_keys', 'a')
# Enviar una solicitud a la API GiHub y almacenar la respuesta en una variable llamada 'respuesta'
api_root = "https: // api.github.com "
request_header = 'Aceptar': 'aplicación / vnd.github.v3 + json '
respuesta = solicitudes.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Procesando la respuesta y agregando claves al archivo autorizado_keys
porque yo en respuesta.json ():
archivo_de_claves_autorizadas.escribir (i ['clave'] + '\ n')
Ignoremos el manejo de archivos de Python y los detalles varios y observemos estrictamente la solicitud y la respuesta. Primero importamos el módulo de solicitudes. Esta biblioteca nos permite realizar llamadas a la API con mucha facilidad. Esta biblioteca es también uno de los mejores ejemplos de un proyecto de código abierto bien hecho. Aquí está el sitio oficial en caso de que quiera echar un vistazo más de cerca a los documentos.
A continuación, establecemos una variable api_root.
api_root = "https: // api.github.com "Esta es la subcadena común en todas las URL a las que realizaremos llamadas a la API. Entonces, en lugar de escribir "https: // api.github.com ”cada vez que necesitamos acceder a https: // api.github.com / users o https: // api.github.com / users /api_root + '/ users /' o api_root + '/ users / como se muestra en el fragmento de código.
A continuación, configuramos el encabezado en nuestra solicitud HTTPS, lo que indica que las respuestas están destinadas a la API de la versión 3 y deben tener el formato JSON. GitHub respetaría esta información de encabezado.
1. OBTENER Solicitud
Entonces, ahora que tenemos nuestra URL y la información del encabezado (opcional) almacenada en diferentes variables, es hora de realizar la solicitud.
respuesta = solicitudes.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)La solicitud es de tipo 'get' porque estamos leyendo información disponible públicamente de GitHub. Si estuviera escribiendo algo en su cuenta de usuario de GitHub, usaría POST. De manera similar, otros métodos están destinados a otras funciones como DELETE es para eliminar recursos como repositorios.
2. Punto final de API
El punto final de la API al que nos estamos dirigiendo es:
https: // api.github.com / users /Cada recurso de GitHub tiene su propio punto final de API. Sus solicitudes de GET, PUT, DELETE, etc.se realizan en el punto final que proporcionó. Dependiendo del nivel de acceso que tenga, GitHub le permitirá continuar con esa solicitud o la rechazará.
La mayoría de las organizaciones y usuarios de GitHub establecen una gran cantidad de información legible y pública. Por ejemplo, mi cuenta de usuario de GitHub tiene un par de repositorios públicos y claves SSH públicas a las que cualquiera puede acceder (incluso sin una cuenta de usuario de GitHub). Si desea tener un control más detallado de su cuenta personal, puede generar un "Token de acceso personal" para leer y escribir información privilegiada almacenada en su cuenta personal de GitHub. Si está escribiendo una aplicación de terceros, destinada a ser utilizada por otros usuarios, entonces un Token OAuth de dicho usuario es lo que su aplicación requeriría.
Pero como puede ver, se puede acceder a mucha información útil sin crear ningún token.
3. Respuesta
La respuesta se devuelve desde el servidor API de GitHub y se almacena en la variable denominada respuesta. La respuesta completa se puede leer de varias formas, como se documenta aquí. Solicitamos explícitamente contenido de tipo JSON de GitHub, por lo que procesaremos la solicitud, como si fuera JSON. Para hacer esto, llamamos al método json () desde el módulo de solicitudes que lo decodificará en objetos nativos de Python como diccionarios y listas.
Puede ver las claves que se añaden al archivo autorizado_keys en este bucle for:
porque yo en respuesta.json ():archivo_de_claves_autorizadas.escribir (i ['clave'] + '\ n')
Si imprime la respuesta.json (), notará que es una lista de Python con diccionarios de Python como miembros. Cada diccionario tiene una clave llamada 'clave' con su clave SSH pública como valor para esa clave. Para que pueda agregar estos valores uno por uno a su archivo Authorized_keys. Y ahora puede SSH fácilmente en su servidor desde cualquier computadora que tenga cualquiera de las claves SSH privadas correspondientes a una de las claves públicas que acabamos de agregar.
Explorando más
Mucho trabajo con las API implica una inspección cuidadosa de la documentación de la API en sí más que escribir líneas de código. En el caso de GitHub, la documentación es una de las mejores de la industria. Pero leer sobre los documentos de la API y hacer llamadas a la API usando Python es bastante poco interesante como actividad independiente.
Antes de continuar, le recomendaría que proponga una tarea que le gustaría realizar usando Python en su cuenta de GitHub. Luego intente implementarlo leyendo solo la documentación oficial proporcionada por Python, sus bibliotecas dependientes y GitHub. Esto también lo ayudará a adoptar una mentalidad más saludable en la que comprenderá lo que sucede dentro de su código y lo mejorará gradualmente con el tiempo.
