Phenquestions
Folk på GitHub, og både tredjepartsutviklere, kan umulig håndtere all denne kompleksiteten uten et felles grensesnitt. Dette vanlige grensesnittet er det vi kaller GitHub API. Hvert GitHub-verktøy som en cli, nettgrensesnitt osv. Bruker dette vanlige grensesnittet for å administrere ressurser (ressurser er enheter som arkiver, ssh-nøkler osv.).
I denne opplæringen vil vi lære noen grunnleggende om hvordan man grensesnitt med en API ved hjelp av GitHub API v3 og Python3. Den siste v4 av GitHub API krever at du lærer om GraphQL som resulterer i brattere læringskurve. Så jeg vil holde meg til bare versjon tre som fortsatt er aktiv og ganske populær.
Hvordan snakke med et web-API
Web API-er er det som gjør det mulig for deg å bruke alle tjenestene som tilbys av en webapp, som GitHub, programmatisk ved hjelp av ditt eget språk. For eksempel skal vi bruke Python til vårt brukstilfelle, her. Teknisk sett kan du gjøre alt du gjør på GitHub ved hjelp av API, men vi vil begrense oss til å bare lese allment tilgjengelig informasjon.
Python-programmet ditt vil snakke med en API på samme måte som nettleseren din snakker til et nettsted. Det vil si, hovedsakelig via HTTPS-forespørsler. Disse forespørslene vil inneholde forskjellige 'deler', med utgangspunkt i metoden for forespørselen [GET, POST, PUT, SLETT], selve URL-en, en spørringsstreng, en HTTP-overskrift og en kropp eller en nyttelast. De fleste av disse er valgfrie. Vi må imidlertid oppgi en forespørselsmetode og URL-en som vi ber om.
Hva dette er og hvordan de er representert i en HTTPS-forespørsel, er noe vi ser sakte når vi begynner å skrive Python-skript for å samhandle med GitHub.
Et eksempel
Å legge til SSH-nøkler til en nyopprettet server er alltid en klønete prosess. La oss skrive et Python-skript som vil hente de offentlige SSH-nøklene dine fra GitHub og legge det til autoriserte_keys-filen på en hvilken som helst Linux- eller Unix-server der du kjører dette skriptet. Hvis du ikke vet hvordan du genererer eller bruker SSH-nøkler, er det en utmerket artikkel om hvordan du gjør akkurat det. Jeg antar at du har opprettet og lagt til dine egne offentlige SSH-nøkler til GitHub-kontoen din.
En veldig enkel og naiv Python-implementering for å oppnå oppgaven vi beskrev ovenfor er som vist nedenfor:
importforespørslerimporter os
# Få brukerinngang
unix_user = input ("Skriv inn ditt Unix brukernavn:")
github_user = input ("Skriv inn GitHub-brukernavnet ditt:")
# Forsikre seg om .ssh-katalogen eksisterer og åpner filen authorised_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
hvis ikke os.sti.eksisterer (ssh_dir):
os.makedirs (ssh_dir)
autoriserte_taster_fil = åpne (ssh_dir + 'autoriserte_taster', 'a')
# Sende en forespørsel til GiHub API og lagre svaret i en variabel som heter 'svar'
api_root = "https: // api.github.com "
request_header = 'Godta': 'applikasjon / vnd.github.v3 + json '
svar = forespørsler.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Behandler svaret og legger til nøkler til filen autoriserte nøkler
for jeg som svar.json ():
autoriserte_taster_fil.skriv (i ['nøkkel'] + '\ n')
La oss ignorere Python-filhåndtering og diverse detaljer og se strengt på forespørsel og svar. Først importerte vi forespørselsmodulens importforespørsler, dette biblioteket lar oss ringe API-anrop veldig enkelt. Dette biblioteket er også et av de beste eksemplene på et åpen kildekode-prosjekt gjort riktig. Her er det offisielle nettstedet i tilfelle du vil se nærmere på dokumentene.
Deretter setter vi en variabel api_root.
api_root = "https: // api.github.com "Dette er den vanlige undergrunnen i alle URL-ene som vi skal ringe API-samtaler til. Så i stedet for å skrive “https: // api.github.com ”hver gang vi trenger tilgang til https: // api.github.com / brukere eller https: // api.github.com / brukere /api_root + '/ brukere /' eller api_root + '/ brukere / som vist i kodebiten.
Deretter setter vi overskriften i vår HTTPS-forespørsel, noe som indikerer at svarene er ment for versjon 3 API og skal være JSON-formatert. GitHub respekterer denne topptekstinformasjonen.
1. FÅ forespørsel
Så nå som vi har URL-adressen vår og (en valgfri) topptekstinformasjon lagret i forskjellige variabler, er det på tide å komme med forespørselen.
svar = forespørsler.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Forespørselen er av typen get fordi vi leser offentlig tilgjengelig informasjon fra GitHub. Hvis du skrev noe under GitHub-brukerkontoen din, ville du brukt POST. Tilsvarende er andre metoder ment for andre funksjoner som DELETE er for sletting av ressurser som arkiver.
2. API-endepunkt
API-endepunktet som vi når ut til er:
https: // api.github.com / brukere /Hver GitHub-ressurs har sitt eget API-endepunkt. Dine forespørsler om GET, PUT, SLETT osv. Sendes deretter mot det endepunktet du oppga. Avhengig av tilgangsnivået du har, vil GitHub da enten tillate deg å gå gjennom den forespørselen eller nekte den.
De fleste organisasjoner og brukere på GitHub setter en enorm mengde informasjon som er lesbar og offentlig. For eksempel har min GitHub-brukerkonto et par offentlige depoter og offentlige SSH-nøkler som alle kan lese tilgang (selv uten en GitHub-brukerkonto). Hvis du vil ha en mer detaljert kontroll over din personlige konto, kan du generere et "Personal Access Token" for å lese og skrive privilegert informasjon som er lagret i din personlige GitHub-konto. Hvis du skriver en tredjepartsapplikasjon som er ment å brukes av andre brukere enn deg, er det en OAuth-token av nevnte bruker det applikasjonen din vil kreve.
Men som du kan se, kan du få tilgang til mye nyttig informasjon uten å opprette noe token.
3. Respons
Svaret returneres fra GitHub API-serveren og lagres i variabelen som heter respons. Hele svaret kan leses på flere måter som dokumentert her. Vi ba eksplisitt om innhold av JSON-typen fra GitHub, så vi vil behandle forespørselen, som om det er JSON. For å gjøre dette kaller vi json () -metoden fra forespørselsmodulen som vil dekode den til Python-innfødte objekter som ordbøker og lister.
Du kan se nøklene som legges til filen authorised_keys i denne for loop:
for jeg som svar.json ():autoriserte_taster_fil.skriv (i ['nøkkel'] + '\ n')
Hvis du skriver ut svaret.json () objekt, vil du legge merke til at det er en Python-liste med Python-ordbøker som medlemmer. Hver ordbok har en nøkkel med navnet 'nøkkel' med din offentlige SSH-nøkkel som verdi for den nøkkelen. Så du kan legge til disse verdiene en etter en i din autoriserte_key-fil. Og nå kan du enkelt SSH inn på serveren din fra hvilken som helst datamaskin som har noen av de private SSH-nøklene som tilsvarer en av de offentlige nøklene vi nettopp la til.
Utforske videre
Mye arbeid med API-er innebærer nøye inspeksjon av API-dokumentasjonen i seg selv mer enn å skrive kodelinjer. I tilfelle GitHub er dokumentasjonen en av de fineste i bransjen. Men å lese opp API-dokumenter og ringe API-samtaler ved hjelp av Python er ganske uinteressant som en frittstående aktivitet.
Før du går videre, vil jeg anbefale deg å komme med en oppgave du vil utføre ved hjelp av Python på GitHub-kontoen din. Prøv deretter å implementere den ved å lese bare de offisielle dokumentasjonene som er gitt av Python, dets avhengige biblioteker og GitHub. Dette vil også hjelpe deg med å innføre en sunnere tankegang der du forstår hva som skjer i koden din og forbedre den gradvis over tid.
