Découverte de ressources pour un utilisateur

Lorsque vous effectuez des demandes authentifiées auprès de l’API GitHub, les applications doivent souvent récupérer les dépôts et les organisations de l’utilisateur actuel. Dans ce guide, nous allons expliquer comment découvrir de manière fiable ces ressources.

Pour interagir avec l’API GitHub, nous allons utiliser Octokit.rb. Vous trouverez le code source complet de ce projet dans le dépôt platform-samples.

Mise en route

Si vous ne l’avez pas déjà fait, vous devez lire le guide Principes de base de l’authentification avant d’utiliser les exemples ci-dessous. Les exemples ci-dessous supposent que vous avez inscrit une OAuth app et que votre application a un jeton OAuth pour un utilisateur.

Découvrir les dépôts auxquels votre application peut accéder pour un utilisateur

En plus d’avoir ses propres dépôts personnels, un utilisateur peut collaborer aux dépôts détenus par d’autres utilisateurs et organisations. Collectivement, il s’agit des dépôts pour lesquels l’utilisateur dispose d’un accès privilégié : soit il s’agit d’un dépôt privé pour lequel l’utilisateur dispose d’un accès en lecture ou en écriture, soit il s’agit d’un dépôt public ou interne pour lequel l’utilisateur dispose d’un accès en écriture.

Les étendues OAuth et les stratégies d’application d’organisation déterminent les dépôts auxquels votre application peut accéder pour un utilisateur. Utilisez le workflow ci-dessous pour découvrir ces dépôts.

Comme toujours, nous aurons d’abord besoin de la bibliothèque Ruby Octokit.rb de GitHub. Ensuite, nous allons configurer Octokit.rb pour gérer automatiquement la pagination. Pour plus d’informations sur la pagination, consultez Utilisation de la pagination dans l’API REST.

require 'octokit'

Octokit.auto_paginate = true

Ensuite, nous allons passer le jeton OAuth de notre application pour un utilisateur donné :

# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!!
# Instead, set and test environment variables, like below.
client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"]

Ensuite, nous sommes prêts à récupérer les dépôts auxquels notre application peut accéder pour l’utilisateur :

client.repositories.each do |repository|
  full_name = repository[:full_name]
  has_push_access = repository[:permissions][:push]

  access_type = if has_push_access
                  "write"
                else
                  "read-only"
                end

  puts "User has #{access_type} access to #{full_name}."
end

Découvrir les organisations auxquelles votre application peut accéder pour un utilisateur

Les applications peuvent effectuer toutes sortes de tâches liées à l’organisation pour un utilisateur. Pour effectuer ces tâches, l’application a besoin d’une autorisation OAuth avec un niveau d’autorisation suffisant. Par exemple, l’étendue read:org vous permet de lister les équipes, et l’étendue user vous permet de publiciser l’appartenance de l’utilisateur à l’organisation. Une fois qu’un utilisateur a accordé une ou plusieurs de ces étendues à votre application, vous êtes prêt à récupérer les organisations de l’utilisateur.

Comme nous l’avons fait lors de la découverte des dépôts ci-dessus, nous allons commencer par exiger la bibliothèque Ruby Octokit.rb de GitHub et la configurer de sorte qu’elle se charge de la pagination pour nous. Pour plus d’informations sur la pagination, consultez Utilisation de la pagination dans l’API REST.

require 'octokit'

Octokit.auto_paginate = true

Ensuite, nous allons passer le jeton OAuth d’un utilisateur donnépour notre application afin d’initialiser notre client API :

# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!!
# Instead, set and test environment variables, like below.
client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"]

Ensuite, nous pouvons lister les organisations auxquelles notre application peut accéder pour l’utilisateur :

client.organizations.each do |organization|
  puts "User belongs to the #{organization[:login]} organization."
end

Retourner toutes les appartenances de l’utilisateur à l’organisation

Si vous avez lu les documents dans leur intégralité, vous avez peut-être noté une méthode d’API qui permet de lister les appartenances d’un utilisateur à une organisation publique. La plupart des applications doivent éviter cette méthode d’API. Cette méthode retourne uniquement les appartenances de l’utilisateur à une organisation publique, et non ses appartenances à une organisation privée.

En tant qu’application, vous souhaitez généralement toutes les organisations de l’utilisateur auxquelles vous êtes autorisé à accéder. Le workflow ci-dessus vous le permettra.