Erstellen einer CLI mit einer GitHub-App

Einführung

In diesem Tutorial wird veranschaulicht, wie du eine Befehlszeilenschnittstelle (Command Line Interface, CLI) erstellst, die von einer GitHub App unterstützt wird, und wie du mithilfe des Geräteflusses ein Benutzerzugriffstoken für die App generierst.

Die CLI verfügt über drei Befehle:

help: Gibt die Verwendungsanweisungen aus.
login: Generiert ein Benutzerzugriffstoken, das die App verwenden kann, um API-Anforderungen im Namen von Benutzer*innen zu senden.
whoami: Gibt Informationen zum angemeldeten Benutzer oder zur angemeldeten Benutzerin zurück.

In diesem Tutorial wird Ruby verwendet, aber du kannst mit einer beliebigen Programmiersprache eine CLI schreiben und den Gerätefluss verwenden, um ein Benutzerzugriffstoken zu generieren.

Informationen zu Gerätefluss und Benutzerzugriffstoken

Die CLI verwendet den Gerätefluss, um Benutzerinnen zu authentifizieren und ein Benutzerzugriffstoken zu generieren. Anschließend kann die CLI das Benutzerzugriffstoken verwenden, um API-Anforderungen im Namen der authentifizierten Benutzerinnen zu senden.

Deine App muss ein Benutzerzugriffstoken verwenden, wenn du die Aktionen der App einemr Benutzerin zuordnen möchtest. Weitere Informationen findest du unter Authentifizieren mit einer GitHub-App im Namen von Benutzer*innen.

Es gibt zwei Möglichkeiten, ein Benutzerzugriffstoken für eine GitHub App zu generieren: Webanwendungsfluss und Gerätefluss. Wenn deine App monitorlos ist oder keinen Zugriff auf eine Weboberfläche hat, solltest du den Gerätefluss verwenden, um ein Benutzerzugriffstoken zu generieren. Beispielsweise sollten CLI-Tools, einfache Raspberry Pi-Geräte und Desktopanwendungen den Gerätefluss verwenden. Wenn deine App Zugriff auf eine Weboberfläche hat, solltest du stattdessen den Webanwendungsfluss verwenden. Weitere Informationen findest du unter Generieren eines Benutzerzugriffstokens für eine GitHub-App und unter Erstellen der Schaltfläche „Mit GitHub anmelden“ mit einer GitHub-App.

Voraussetzungen

In diesem Tutorial wird davon ausgegangen, dass du bereits eine GitHub App registriert hast. Weitere Informationen zum Registrieren einer GitHub App findest du unter Registrieren einer GitHub-App.

Bevor du dieses Tutorial ausführst, musst du den Gerätefluss für deine App aktivieren. Weitere Informationen zum Aktivieren des Geräteflusses für deine App findest du unter Ändern einer GitHub-App-Registrierung.

Dieses Tutorial setzt Grundkenntnisse in Ruby voraus. Weitere Informationen findest du unter Ruby.

Abrufen der Client-ID

Du benötigst die Client-ID deiner App, um ein Benutzerzugriffstoken über den Gerätefluss zu generieren.

Klicke auf GitHub in der oberen rechten Ecke einer beliebigen Seite auf dein Profilfoto.
Navigiere zu den Einstellungen für dein Konto.
- Klicken Sie bei einer App, die zu einem persönlichen Konto gehört, auf Einstellungen.
- Für eine App im Besitz einer Organisation:
  1. Klicke auf Deine Organisationen.
  2. Klicke dann rechts neben der Organisation auf Einstellungen.
Klicke auf der linken Seitenleiste auf Entwicklereinstellungen.
Klicke auf der linken Randleiste auf GitHub Apps .
Wähle neben der GitHub App, die du verwenden möchtest, Bearbeiten aus.
Suche auf der Einstellungsseite der App nach der Client-ID für deine App. Du benötigst sie später in diesem Tutorial. Beachte, dass sich die Client-ID von der App-ID unterscheidet.

Schreiben der CLI

Diese Schritte führen dich durch das Erstellen einer CLI und die Verwendung des Geräteflusses, um ein Benutzerzugriffstoken zu erhalten. Den endgültigen Code findest du im vollständigen Codebeispiel.

Einrichten

Erstelle eine Ruby-Datei, die den Code enthält, mit dem ein Benutzerzugriffstoken generiert wird. In diesem Tutorial wird die Datei mit app_cli.rb benannt.
Führe in deinem Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, den folgenden Befehl aus, um app_cli.rb ausführbar zu machen:
Text
```
chmod +x app_cli.rb
```
```
chmod +x app_cli.rb
```
Füge oben in app_cli.rb die folgende Zeile hinzu, um anzugeben, dass der Ruby-Interpreter zum Ausführen des Skripts verwendet werden soll:
Ruby
```
#!/usr/bin/env ruby
```
```
#!/usr/bin/env ruby
```
Füge oben in app_cli.rb nach #!/usr/bin/env ruby die folgenden Abhängigkeiten hinzu:
Ruby
```
require "net/http"
require "json"
require "uri"
require "fileutils"
```
```
require "net/http"
require "json"
require "uri"
require "fileutils"
```
Diese sind alle Teil der Ruby-Standardbibliothek, sodass du keine Gems installieren musst.

Füge die folgende main-Funktion hinzu, die als Einstiegspunkt dient. Die Funktion enthält eine case-Anweisung zum Ausführen unterschiedlicher Aktionen, abhängig vom angegebenen Befehl. Du erweiterst diese case-Anweisung später.

Ruby

def main
  case ARGV[0]
  when "help"
    puts "`help` is not yet defined"
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command `#{ARGV[0]}`"
  end
end

def main
  case ARGV[0]
  when "help"
    puts "`help` is not yet defined"
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command `#{ARGV[0]}`"
  end
end

Füge unten in der Datei die folgende Zeile hinzu, um die Einstiegspunktfunktion aufzurufen. Dieser Funktionsaufruf sollte unten in der Datei verbleiben, wenn du dieser Datei später im Tutorial weitere Funktionen hinzufügst.
Ruby
```
main
```
```
main
```

Überprüfe optional den Fortschritt:

app_cli.rb sieht jetzt so aus:

Ruby

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

def main
  case ARGV[0]
  when "help"
    puts "`help` is not yet defined"
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command `#{ARGV[0]}`"
  end
end

main

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

def main
  case ARGV[0]
  when "help"
    puts "`help` is not yet defined"
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command `#{ARGV[0]}`"
  end
end

main

Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb help aus. Die folgende Ausgabe sollte angezeigt werden:

`help` is not yet defined

Du kannst dein Skript auch ohne einen Befehl oder mit einem nicht behandelten Befehl testen. ./app_cli.rb create-issue sollte beispielsweise Folgendes ausgeben:

Unknown command `create-issue`

Hinzufügen eines `help`-Befehls

Füge app_cli.rb die folgende help-Funktion hinzu. Derzeit gibt die help-Funktion eine Zeile aus, um Benutzer*innen mitzuteilen, dass diese CLI einen Befehl („help“) akzeptiert. Du erweiterst diese help-Funktion später.
Ruby
```
def help
  puts "usage: app_cli <help>"
end
```
```
def help
  puts "usage: app_cli <help>"
end
```

Aktualisiere die main-Funktion, um die help-Funktion aufzurufen, wenn der help-Befehl ausgegeben wird:

Ruby

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

Überprüfe optional den Fortschritt:

app_cli.rb sieht jetzt wie folgt aus. Die Reihenfolge der Funktionen spielt keine Rolle, solange sich der main-Funktionsaufruf am Ende der Datei befindet.

Ruby

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

def help
  puts "usage: app_cli <help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

main

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

def help
  puts "usage: app_cli <help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    puts "`login` is not yet defined"
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

main

Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb help aus. Die folgende Ausgabe sollte angezeigt werden:

usage: app_cli <help>

Der login-Befehl führt den Gerätefluss aus, um ein Benutzerzugriffstoken abzurufen. Weitere Informationen findest du unter Generieren eines Benutzerzugriffstokens für eine GitHub-App.

Füge im oberen Bereich der Datei nach den require-Anweisungen die Client-ID (CLIENT_ID) deiner GitHub App als Konstante in app_cli.rb hinzu. Weitere Informationen zum Ermitteln der Client-ID deiner App findest du unter Abrufen der Client-ID. Ersetze YOUR_CLIENT_ID durch die Client-ID deiner App:
Ruby
```
CLIENT_ID="YOUR_CLIENT_ID"
```
```
CLIENT_ID="YOUR_CLIENT_ID"
```

Füge app_cli.rb die folgende parse_response-Funktion hinzu. Diese Funktion analysiert eine Antwort der GitHub-REST-API. Wenn der Antwortstatus 200 OK oder 201 Created lautet, gibt die Funktion den analysierten Antworttext zurück. Andernfalls gibt die Funktion die Antwort und den Text aus und beendet das Programm.

Ruby

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  else
    puts response
    puts response.body
    exit 1
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  else
    puts response
    puts response.body
    exit 1
  end
end

Füge app_cli.rb die folgende request_device_code-Funktion hinzu. Diese Funktion sendet eine POST-Anforderung an http(s)://HOSTNAME/login/device/code und gibt die Antwort zurück.

Ruby

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

Füge app_cli.rb die folgende request_token-Funktion hinzu. Diese Funktion sendet eine POST-Anforderung an http(s)://HOSTNAME/login/oauth/access_token und gibt die Antwort zurück.

Ruby

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

Füge app_cli.rb die folgende poll_for_token-Funktion hinzu. Diese Funktion ruft http(s)://HOSTNAME/login/oauth/access_token im angegebenen Intervall ab, bis GitHub mit dem Parameter access_token anstelle des Parameters error antwortet. Anschließend schreibt sie das Benutzerzugriffstoken in eine Datei und schränkt die Berechtigungen für die Datei ein.

Ruby

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

Füge die folgende login-Funktion hinzu.

Diese Funktion bewirkt Folgendes:

Aufrufen der Funktion request_device_code und Abrufen der Parameter verification_uri, user_code, device_code und interval aus der Antwort
Auffordern der Benutzer*innen, user_code aus dem vorherigen Schritt einzugeben
Aufrufen von poll_for_token, um ein Zugriffstoken von GitHub abzufragen
Informieren der Benutzer*innen, dass die Authentifizierung erfolgreich war

Ruby

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

Aktualisiere die main-Funktion, um die login-Funktion aufzurufen, wenn der login-Befehl ausgegeben wird:

Ruby

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

Aktualisiere die help-Funktion so, dass sie den login-Befehl enthält:

Ruby

def help
  puts "usage: app_cli <login | help>"
end

def help
  puts "usage: app_cli <login | help>"
end

Überprüfe optional den Fortschritt:

app_cli.rb sieht nun in etwa wie folgt aus, wobei YOUR_CLIENT_ID die Client-ID deiner App ist. Die Reihenfolge der Funktionen spielt keine Rolle, solange sich der main-Funktionsaufruf am Ende der Datei befindet.

Ruby

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

CLIENT_ID="YOUR_CLIENT_ID"

def help
  puts "usage: app_cli <login | help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  else
    puts response
    puts response.body
    exit 1
  end
end

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

main

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

CLIENT_ID="YOUR_CLIENT_ID"

def help
  puts "usage: app_cli <login | help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    puts "`whoami` is not yet defined"
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  else
    puts response
    puts response.body
    exit 1
  end
end

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

main

Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb login aus. Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden. Der Code unterscheidet sich jedes Mal:
```
Please visit: http(s)://HOSTNAME/login/device
and enter code: CA86-8D94
```
Navigiere in deinem Browser zu http(s)://HOSTNAME/login/device, gib den Code aus dem vorherigen Schritt ein, und klicke dann auf Weiter.
Auf GitHub sollte eine Seite mit der Aufforderung zum Autorisieren deiner App angezeigt werden. Klicke auf die Schaltfläche „Autorisieren“.
In deinem Terminal sollte jetzt „Erfolgreich authentifiziert!“ angezeigt werden.

Hinzufügen eines `whoami`-Befehls

Nachdem deine App nun ein Benutzerzugriffstoken generieren kann, kannst du API-Anforderungen im Namen von Benutzer*innen ausführen. Füge einen whoami-Befehl hinzu, um den Benutzernamen des authentifizierten Benutzers oder der authentifizierten Benutzerin abzurufen.

Füge app_cli.rb die folgende whoami-Funktion hinzu. Diese Funktion ruft über den REST-API-Endpunkt /user Informationen zu den Benutzerinnen ab. Sie gibt den Benutzernamen aus, der dem Benutzerzugriffstoken entspricht. Wenn die Datei .token nicht gefunden wurde, werden die Benutzerinnen zum Ausführen der login-Funktion aufgefordert.

Ruby

def whoami
  uri = URI("http(s)://HOSTNAME/api/v3/user")

  begin
    token = File.read("./.token").strip
  rescue Errno::ENOENT => e
    puts "You are not authorized. Run the `login` command."
    exit 1
  end

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    body = {"access_token" => token}.to_json
    headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}

    http.send_request("GET", uri.path, body, headers)
  end

  parsed_response = parse_response(response)
  puts "You are #{parsed_response["login"]}"
end

def whoami
  uri = URI("http(s)://HOSTNAME/api/v3/user")

  begin
    token = File.read("./.token").strip
  rescue Errno::ENOENT => e
    puts "You are not authorized. Run the `login` command."
    exit 1
  end

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    body = {"access_token" => token}.to_json
    headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}

    http.send_request("GET", uri.path, body, headers)
  end

  parsed_response = parse_response(response)
  puts "You are #{parsed_response["login"]}"
end

Aktualisiere die parse_response-Funktion für den Fall, dass das Token abgelaufen ist oder widerrufen wurde. Wenn du nun eine Antwort vom Typ 401 Unauthorized erhältst, fordert die CLI Benutzer*innen auf, den login-Befehl auszuführen.

Ruby

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  when Net::HTTPUnauthorized
    puts "You are not authorized. Run the `login` command."
    exit 1
  else
    puts response
    puts response.body
    exit 1
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  when Net::HTTPUnauthorized
    puts "You are not authorized. Run the `login` command."
    exit 1
  else
    puts response
    puts response.body
    exit 1
  end
end

Aktualisiere die main-Funktion, um die whoami-Funktion aufzurufen, wenn der whoami-Befehl ausgegeben wird:

Ruby

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    whoami
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    whoami
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

Aktualisiere die help-Funktion so, dass sie den whoami-Befehl enthält:

Ruby

def help
  puts "usage: app_cli <login | whoami | help>"
end

def help
  puts "usage: app_cli <login | whoami | help>"
end

Überprüfe deinen Code anhand des vollständigen Codebeispiels im nächsten Abschnitt. Du kannst deinen Code testen, indem du die Schritte im Abschnitt Testen unterhalb des vollständigen Codebeispiels befolgst.

Vollständiges Codebeispiel

Dies ist das vollständige Codebeispiel, das im vorherigen Abschnitt beschrieben wurde. Ersetze YOUR_CLIENT_ID durch die Client-ID deiner App.

Ruby

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

CLIENT_ID="YOUR_CLIENT_ID"

def help
  puts "usage: app_cli <login | whoami | help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    whoami
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  when Net::HTTPUnauthorized
    puts "You are not authorized. Run the `login` command."
    exit 1
  else
    puts response
    puts response.body
    exit 1
  end
end

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

def whoami
  uri = URI("http(s)://HOSTNAME/api/v3/user")

  begin
    token = File.read("./.token").strip
  rescue Errno::ENOENT => e
    puts "You are not authorized. Run the `login` command."
    exit 1
  end

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    body = {"access_token" => token}.to_json
    headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}

    http.send_request("GET", uri.path, body, headers)
  end

  parsed_response = parse_response(response)
  puts "You are #{parsed_response["login"]}"
end

main

#!/usr/bin/env ruby

require "net/http"
require "json"
require "uri"
require "fileutils"

CLIENT_ID="YOUR_CLIENT_ID"

def help
  puts "usage: app_cli <login | whoami | help>"
end

def main
  case ARGV[0]
  when "help"
    help
  when "login"
    login
  when "whoami"
    whoami
  else
    puts "Unknown command #{ARGV[0]}"
  end
end

def parse_response(response)
  case response
  when Net::HTTPOK, Net::HTTPCreated
    JSON.parse(response.body)
  when Net::HTTPUnauthorized
    puts "You are not authorized. Run the `login` command."
    exit 1
  else
    puts response
    puts response.body
    exit 1
  end
end

def request_device_code
  uri = URI("http(s)://HOSTNAME/login/device/code")
  parameters = URI.encode_www_form("client_id" => CLIENT_ID)
  headers = {"Accept" => "application/json"}

  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def request_token(device_code)
  uri = URI("http(s)://HOSTNAME/login/oauth/access_token")
  parameters = URI.encode_www_form({
    "client_id" => CLIENT_ID,
    "device_code" => device_code,
    "grant_type" => "urn:ietf:params:oauth:grant-type:device_code"
  })
  headers = {"Accept" => "application/json"}
  response = Net::HTTP.post(uri, parameters, headers)
  parse_response(response)
end

def poll_for_token(device_code, interval)

  loop do
    response = request_token(device_code)
    error, access_token = response.values_at("error", "access_token")

    if error
      case error
      when "authorization_pending"
        # The user has not yet entered the code.
        # Wait, then poll again.
        sleep interval
        next
      when "slow_down"
        # The app polled too fast.
        # Wait for the interval plus 5 seconds, then poll again.
        sleep interval + 5
        next
      when "expired_token"
        # The `device_code` expired, and the process needs to restart.
        puts "The device code has expired. Please run `login` again."
        exit 1
      when "access_denied"
        # The user cancelled the process. Stop polling.
        puts "Login cancelled by user."
        exit 1
      else
        puts response
        exit 1
      end
    end

    File.write("./.token", access_token)

    # Set the file permissions so that only the file owner can read or modify the file
    FileUtils.chmod(0600, "./.token")

    break
  end
end

def login
  verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval")

  puts "Please visit: #{verification_uri}"
  puts "and enter code: #{user_code}"

  poll_for_token(device_code, interval)

  puts "Successfully authenticated!"
end

def whoami
  uri = URI("http(s)://HOSTNAME/api/v3/user")

  begin
    token = File.read("./.token").strip
  rescue Errno::ENOENT => e
    puts "You are not authorized. Run the `login` command."
    exit 1
  end

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    body = {"access_token" => token}.to_json
    headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"}

    http.send_request("GET", uri.path, body, headers)
  end

  parsed_response = parse_response(response)
  puts "You are #{parsed_response["login"]}"
end

main

Testen

In diesem Tutorial wird davon ausgegangen, dass dein App-Code in einer Datei mit dem Namen app_cli.rb gespeichert ist.

Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb help aus. Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden.
```
usage: app_cli <login | whoami | help>
```
Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb login aus. Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden. Der Code unterscheidet sich jedes Mal:
```
Please visit: http(s)://HOSTNAME/login/device
and enter code: CA86-8D94
```
Navigiere in deinem Browser zu http(s)://HOSTNAME/login/device, gib den Code aus dem vorherigen Schritt ein, und klicke dann auf Weiter.
Auf GitHub sollte eine Seite mit der Aufforderung zum Autorisieren deiner App angezeigt werden. Klicke auf die Schaltfläche „Autorisieren“.
In deinem Terminal sollte jetzt „Erfolgreich authentifiziert!“ angezeigt werden.
Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb whoami aus. Ungefähr folgende Ausgabe sollte angezeigt werden. octocat ist dabei dein Benutzername:
```
You are octocat
```
Öffne die Datei .token in deinem Editor, und ändere das Token. Das Token ist jetzt ungültig.
Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb whoami aus. Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden:
```
You are not authorized. Run the `login` command.
```
Lösche die Datei .token.
Führe im Terminal in dem Verzeichnis, in dem app_cli.rb gespeichert ist, ./app_cli.rb whoami aus. Eine ähnliche Ausgabe wie die folgende sollte angezeigt werden:
```
You are not authorized. Run the `login` command.
```

Nächste Schritte

Anpassen des Codes an die Anforderungen deiner App

In diesem Tutorial wurde gezeigt, wie du eine CLI schreibst, die den Gerätefluss verwendet, um ein Benutzerzugriffstoken zu generieren. Du kannst diese CLI erweitern, um zusätzliche Befehle zu akzeptieren. Du kannst beispielsweise einen create-issue-Befehl hinzufügen, mit dem ein Issue erstellt wird. Denke daran, die Berechtigungen deiner App zu aktualisieren, wenn deine App zusätzliche Berechtigungen für die API-Anforderungen benötigt, die du erstellen möchtest. Weitere Informationen findest du unter Auswählen von Berechtigungen für eine GitHub-App.

Sicheres Speichern von Token

In diesem Tutorial wird ein Benutzerzugriffstoken generiert und in einer lokalen Datei gespeichert. Du solltest diese Datei niemals committen und das Token niemals veröffentlichen.

Abhängig von deinem Gerät kannst du eine andere Methoden zum Speichern des Tokens auswählen. Überprüfe die bewährten Methoden zum Speichern von Token auf deinem Gerät.

Weitere Informationen findest du unter Best Practices beim Erstellen einer GitHub-App.

Bewährte Methode befolgen

Du solltest Best Practices für deine GitHub App befolgen. Weitere Informationen findest du unter Best Practices beim Erstellen einer GitHub-App.

Erstellen einer CLI mit einer GitHub-App

In diesem Artikel