Phenquestions
As pessoas do GitHub, e também desenvolvedores terceirizados, não conseguem gerenciar toda essa complexidade sem uma interface comum. Essa interface comum é o que chamamos de API GitHub. Cada utilitário GitHub, como um CLI, IU da web, etc., usa essa interface comum para gerenciar recursos (recursos sendo entidades como repositórios, chaves SSH etc.).
Neste tutorial, aprenderemos alguns princípios básicos de como fazer a interface com uma API usando GitHub API v3 e Python3. A última v4 da API GitHub requer que você aprenda sobre GraphQL, o que resulta em uma curva de aprendizado mais íngreme. Então, vou me limitar a apenas a versão três, que ainda está ativa e muito popular.
Como falar com uma API da web
As APIs da web permitem que você use todos os serviços oferecidos por um aplicativo da web, como o GitHub, programaticamente usando a linguagem de sua escolha. Por exemplo, vamos usar Python para nosso caso de uso, aqui. Tecnicamente, você pode fazer tudo o que faz no GitHub usando a API, mas nos restringiremos a apenas ler as informações publicamente acessíveis.
Seu programa Python estará se comunicando com uma API da mesma maneira que seu navegador se comunica com um site. Ou seja, principalmente por meio de solicitações HTTPS. Essas solicitações conterão diferentes 'partes', começando com o método da solicitação [GET, POST, PUT, DELETE], o próprio URL, uma string de consulta, um cabeçalho HTTP e um corpo ou uma carga útil. A maioria deles é opcional. No entanto, precisaremos fornecer um método de solicitação e o URL para o qual estamos fazendo a solicitação.
O que são e como são representados em uma solicitação HTTPS é algo que veremos lento quando começarmos a escrever scripts Python para interagir com o GitHub.
Um exemplo
Adicionar chaves SSH a um servidor recém-criado é sempre um processo desajeitado. Vamos escrever um script Python que irá recuperar suas chaves SSH públicas do GitHub e adicioná-lo ao arquivo authorized_keys em qualquer servidor Linux ou Unix onde você executar este script. Se você não sabe como gerar ou usar chaves SSH, aqui está um excelente artigo sobre como fazer exatamente isso. Presumo que você tenha criado e adicionado suas próprias chaves SSH públicas à sua conta do GitHub.
Uma implementação de Python muito simples e ingênua para realizar a tarefa que descrevemos acima é mostrada abaixo:
pedidos de importaçãoimportar os
# Obtendo entrada do usuário
unix_user = input ("Digite seu nome de usuário Unix:")
github_user = input ("Digite seu nome de usuário GitHub:")
# Ter certeza .O diretório ssh existe e está abrindo o arquivo authorized_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
se não os.caminho.existe (ssh_dir):
os.makedirs (ssh_dir)
authorised_keys_file = open (ssh_dir + 'authorized_keys', 'a')
# Enviando uma solicitação à API GiHub e armazenando a resposta em uma variável chamada 'resposta'
api_root = "https: // api.github.com "
request_header = 'Aceitar': 'application / vnd.github.v3 + json '
resposta = pedidos.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Processando a resposta e anexando chaves ao arquivo authorized_keys
para mim em resposta.json ():
authorised_keys_file.escrever (i ['chave'] + '\ n')
Vamos ignorar o manuseio de arquivos Python e detalhes diversos e examinar estritamente a solicitação e a resposta. Primeiro importamos as solicitações de importação do módulo de solicitações, esta biblioteca nos permite fazer chamadas de API muito facilmente. Esta biblioteca também é um dos melhores exemplos de um projeto de código aberto bem feito. Este é o site oficial, caso você queira dar uma olhada mais de perto na documentação.
Em seguida, definimos uma variável api_root.
api_root = "https: // api.github.com "Esta é a substring comum em todos os URLs para os quais faremos chamadas de API. Então, em vez de digitar “https: // api.github.com ”toda vez que precisamos acessar https: // api.github.com / users ou https: // api.github.com / users /api_root + '/ users /' ou api_root + '/ users / conforme mostrado no snippet de código.
Em seguida, definimos o cabeçalho em nossa solicitação HTTPS, indicando que as respostas são destinadas à versão 3 da API e devem ser formatadas em JSON. O GitHub respeitaria essas informações de cabeçalho.
1. Solicitação GET
Agora que temos nossa URL e (opcional) as informações do cabeçalho armazenadas em diferentes variáveis, é hora de fazer a solicitação.
resposta = pedidos.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)A solicitação é do tipo 'get' porque estamos lendo informações publicamente disponíveis no GitHub. Se você estivesse escrevendo algo na sua conta de usuário do GitHub, usaria o POST. Da mesma forma, outros métodos são destinados a outras funções como DELETE é para deletar recursos como repositórios.
2. Endpoint API
O endpoint da API que estamos procurando é:
https: // api.github.com / users /Cada recurso GitHub tem seu próprio endpoint de API. Suas solicitações de GET, PUT, DELETE, etc, são feitas em relação ao endpoint que você forneceu. Dependendo do nível de acesso que você tem, o GitHub irá permitir que você prossiga com a solicitação ou negá-la.
A maioria das organizações e usuários no GitHub define uma grande quantidade de informações legíveis e públicas. Por exemplo, minha conta de usuário do GitHub tem alguns repositórios públicos e chaves SSH públicas que qualquer pessoa pode acessar (mesmo sem uma conta de usuário do GitHub). Se você deseja ter um controle mais refinado de sua conta pessoal, pode gerar um “token de acesso pessoal” para ler e gravar informações privilegiadas armazenadas em sua conta pessoal do GitHub. Se você estiver escrevendo um aplicativo de terceiros, destinado a ser usado por outros usuários que não você, um token OAuth do referido usuário é o que seu aplicativo exigirá.
Mas, como você pode ver, muitas informações úteis podem ser acessadas sem a criação de nenhum token.
3. Resposta
A resposta é retornada do servidor da API GitHub e é armazenada na variável chamada response. Toda a resposta pode ser lida de várias maneiras, conforme documentado aqui. Solicitamos explicitamente o conteúdo do tipo JSON do GitHub, portanto, processaremos a solicitação, como se fosse JSON. Para fazer isso, chamamos o método json () do módulo de solicitações, que irá decodificá-lo em objetos nativos do Python, como dicionários e listas.
Você pode ver as chaves sendo anexadas ao arquivo authorized_keys neste loop for:
para mim em resposta.json ():authorised_keys_file.escrever (i ['chave'] + '\ n')
Se você imprimir a resposta.objeto json (), você notará que é uma lista Python com dicionários Python como membros. Cada dicionário tem uma chave chamada 'chave' com sua chave SSH pública como valor para essa chave. Portanto, você pode anexar esses valores um por um ao seu arquivo authorized_keys. E agora você pode facilmente entrar no seu servidor por SSH a partir de qualquer computador que tenha qualquer uma das chaves SSH privadas correspondentes a uma das chaves públicas que acabamos de anexar.
Explorando mais longe
Muito trabalho com APIs envolve uma inspeção cuidadosa da documentação da API em si, mais do que escrever linhas de código. No caso do GitHub, a documentação é uma das melhores do setor. Mas ler documentos de API e fazer chamadas de API usando Python é bastante desinteressante como uma atividade autônoma.
Antes de prosseguir, eu recomendo que você crie uma tarefa que gostaria de realizar usando Python em sua conta do GitHub. Em seguida, tente implementá-lo lendo apenas a documentação oficial fornecida pelo Python, suas bibliotecas dependentes e GitHub. Isso também o ajudará a adotar uma mentalidade mais saudável, onde você entende o que está acontecendo dentro do seu código e melhora-o gradualmente ao longo do tempo.
