octokit.rb
v9.2.0
Note que nous avons récemment renommé la branche
4-stableàmain. Cela pourrait vous affecter si vous apportez des modifications au code d'Octokit localement. Pour plus de détails et pour les étapes pour reconfigurer votre clone local pour le nouveau nom de la branche, consultez cet article.
Ruby Toolkit pour l'API GitHub.
Mise à niveau? Vérifiez le guide de mise à niveau avant de passer à une nouvelle version majeure.
Les emballages API devraient refléter les idiomes de la langue dans laquelle ils ont été écrits. Octokit.rb enveloppe l'API GitHub dans un client API plat qui suit les conventions Ruby et nécessite peu de connaissances sur le repos. La plupart des méthodes ont des arguments de position pour les entrées requises et un hachage d'options pour les paramètres, en-têtes ou autres options facultatifs:
client = Octokit :: Client . new
# Fetch a README with Accept header for HTML format
client . readme 'al3x/sovereign' , :accept => 'application/vnd.github.html' Installer via Rubygems
gem install octokit
... ou ajouter à votre gemfile
gem "octokit"
Accédez à la bibliothèque en Ruby:
require 'octokit'
Les méthodes API sont disponibles en tant que méthodes d'instance client.
# Provide authentication credentials
client = Octokit :: Client . new ( :access_token => 'personal_access_token' )
# You can still use the username/password syntax by replacing the password value with your PAT.
# client = Octokit::Client.new(:login => 'defunkt', :password => 'personal_access_token')
# Fetch the current user
client . userLors de la réussite des paramètres supplémentaires pour obtenir une demande basée sur la syntaxe suivante:
# query: { parameter_name: 'value' }
# Example: Get repository listing by owner in ascending order
client . repos ( { } , query : { type : 'owner' , sort : 'asc' } )
# Example: Get contents of a repository by ref
# https://api.github.com/repos/octokit/octokit.rb/contents/path/to/file.rb?ref=some-other-branch
client . contents ( 'octokit/octokit.rb' , path : 'path/to/file.rb' , query : { ref : 'some-other-branch' } ) La plupart des méthodes renvoient un objet Resource qui fournit une notation de points et un accès [] pour les champs renvoyés dans la réponse de l'API.
client = Octokit :: Client . new
# Fetch a user
user = client . user 'jbarnette'
puts user . name
# => "John Barnette"
puts user . fields
# => <Set: {:login, :id, :gravatar_id, :type, :name, :company, :blog, :location, :email, :hireable, :bio, :public_repos, :followers, :following, :created_at, :updated_at, :public_gists}>
puts user [ :company ]
# => "GitHub"
user . rels [ :gists ] . href
# => "https://api.github.com/users/jbarnette/gists" Remarque: Les champs d'URL sont utilisés dans une collection .rels distincte pour un support d'hypermédia plus facile.
Bien que la plupart des méthodes renvoient un objet Resource ou un booléen, vous pouvez parfois avoir besoin d'accéder aux en-têtes de réponse HTTP bruts. Vous pouvez accéder à la dernière réponse HTTP avec Client#last_response :
user = client . user 'andrewpthorp'
response = client . last_response
etag = response . headers [ :etag ] Lorsque l'API renvoie une réponse d'erreur, Octokit soulèvera une exception Ruby.
Une gamme d'exceptions différentes peut être augmentée en fonction de l'erreur renvoyée par l'API - par exemple:
400 Bad Request mènera à une erreur Octokit::BadRequest403 Forbidden avec un message "Taux limité dépassé" mènera à une erreur Octokit::TooManyRequests Toutes les différentes classes d'exception héritent d' Octokit::Error et exposent le #response_status , #response_headers et #response_body . Pour les erreurs de validation, #errors renverra un Array de Hash avec les informations détaillées renvoyées par l'API.
Octokit prend en charge les différentes méthodes d'authentification prises en charge par l'API GitHub:
L'utilisation de votre nom d'utilisateur GitHub et de votre mot de passe est le moyen le plus simple de commencer à faire des demandes authentifiées:
client = Octokit :: Client . new ( :login => 'defunkt' , :password => 'c0d3b4ssssss!' )
user = client . user
user . login
# => "defunkt"Bien que l'authentification de base vous permette de commencer rapidement, les jetons d'accès OAuth sont le moyen préféré d'authentifier au nom des utilisateurs.
Les jetons d'accès OAuth offrent deux avantages principaux sur l'utilisation de votre nom d'utilisateur et de votre mot de passe:
Pour utiliser un jeton d'accès avec le client Octokit, passez votre jeton dans le paramètre :access_token Options au lieu de votre nom d'utilisateur et de votre mot de passe:
client = Octokit :: Client . new ( :access_token => "<your 40 char token>" )
user = client . user
user . login
# => "defunkt"Vous pouvez créer des jetons d'accès via les paramètres de votre compte GitHub.
L'authentification à deux facteurs apporte une sécurité ajoutée au compte en exigeant plus d'informations pour se connecter.
L'utilisation d'authentification à deux facteurs pour les appels API est aussi simple que d'ajouter l'en-tête requise qu'une option:
client = Octokit :: Client . new
:login => 'defunkt' ,
:password => 'c0d3b4ssssss!'
user = client . user ( "defunkt" , :headers => { "X-GitHub-OTP" => "<your 2FA token>" } ) Octokit prend en charge la lecture des informations d'identification d'un fichier NERRC (défautant à ~/.netrc ). Compte tenu de ces lignes dans votre NETRC:
machine api.github.com
login defunkt
password c0d3b4ssssss!
Vous pouvez désormais créer un client avec ces informations d'identification:
client = Octokit :: Client . new ( :netrc => true )
client . login
# => "defunkt"Mais je veux utiliser OAuth, dites-vous. Étant donné que l'API GitHub prend en charge l'utilisation d'un jeton OAuth comme mot de passe de base, vous pouvez totalement:
machine api.github.com
login defunkt
password <your 40 char token>
Remarque: la prise en charge de NERRC nécessite d'ajouter le gemm NetRC à votre gemfile ou .gemspec .
Octokit prend également en charge l'authentification uniquement de l'application à l'aide des informations d'identification du client d'application OAuth. L'utilisation des informations d'identification de demande entraînera des appels API anonymes au nom d'une demande afin de profiter de la limite de taux plus élevée.
client = Octokit :: Client . new
:client_id => "<your 20 char id>" ,
:client_secret => "<your 40 char secret>"
user = client . user 'defunkt'Octokit.rb prend également en charge l'authentification à l'aide d'une application GitHub, qui nécessite un jeton JWT généré.
client = Octokit :: Client . new ( :bearer_token => "<your jwt token>" )
client . app
# => about GitHub App info Les résultats par défaut de l'API GitHub sont 30, si vous souhaitez en ajouter plus, vous devez le faire pendant la configuration d'Octokit.
Octokit :: Client . new ( access_token : "<your 40 char token>" , per_page : 100 ) De nombreuses ressources API GitHub sont paginées. Bien que vous puissiez être tenté de commencer à ajouter :page à vos appels, l'API renvoie les liens vers les pages suivantes, précédentes et dernières pour vous dans l'en-tête de réponse Link en tant que relations de liaison hypermedia.
issues = client . issues 'rails/rails'
issues . concat client . get ( client . last_response . rels [ :next ] . href )Pour les petites listes de ressources, Octokit fournit une pagination automatique. Lorsque cela est activé, les appels à des ressources paginées approfondiront et concaténeront les résultats de chaque page en un seul tableau:
client . auto_paginate = true
issues = client . issues 'rails/rails'
issues . length
# => 702Vous pouvez également activer la pagination automatique pour toutes les instances du client octokit:
Octokit . configure do | c |
c . auto_paginate = true
end Remarque: Bien que la pagination automatique d'Octokit définisse la taille de la page sur le maximum 100 et cherchera à ne pas dépasser votre limite de taux, vous souhaitez probablement utiliser un modèle personnalisé pour traverser les grandes listes.
Avec un peu de configuration, vous pouvez également utiliser Octokit avec votre instance GitHub Enterprise.
Pour interagir avec les API GitHub.com "régulière" dans GitHub Enterprise, configurez simplement l' api_endpoint pour correspondre à votre nom d'hôte. Par exemple:
Octokit . configure do | c |
c . api_endpoint = "https://<hostname>/api/v3/"
end
client = Octokit :: Client . new ( :access_token => "<your 40 char token>" ) Les API d'administration GitHub Enterprise sont sous un client différent: EnterpriseAdminClient . Vous devrez avoir un compte administrateur afin d'utiliser ces API.
admin_client = Octokit :: EnterpriseAdminClient . new (
:access_token => "<your 40 char token>" ,
:api_endpoint => "https://<hostname>/api/v3/"
)
# or
Octokit . configure do | c |
c . api_endpoint = "https://<hostname>/api/v3/"
c . access_token = "<your 40 char token>"
end
admin_client = Octokit . enterprise_admin_client . new Les API de la console de gestion de GitHub Enterprise sont également sous un client distinct: EnterpriseManagementConsoleClient . Pour l'utiliser, vous devrez fournir à la fois votre mot de passe de console de gestion ainsi que le point de terminaison de votre console de gestion. Ceci est différent du point de terminaison de l'API fourni ci-dessus.
management_console_client = Octokit :: EnterpriseManagementConsoleClient . new (
:management_console_password => "secret" ,
:management_console_endpoint = "https://hostname:8633"
)
# or
Octokit . configure do | c |
c . management_console_endpoint = "https://hostname:8633"
c . management_console_password = "secret"
end
management_console_client = Octokit . enterprise_management_console_client . newVous devrez peut-être désactiver temporairement SSL tout en configurant d'abord votre installation GitHub Enterprise. Vous pouvez le faire avec la configuration suivante:
client . connection_options [ :ssl ] = { :verify => false } N'oubliez pas de tourner :verify true , car il est important pour une communication sécurisée.
Alors que Octokit::Client accepte une gamme d'options lors de la création d'une nouvelle instance client, l'API de configuration d'Octokit vous permet de définir vos options de configuration au niveau du module. Ceci est particulièrement pratique si vous créez un certain nombre d'instances clients en fonction de certaines valeurs par défaut partagées. La modification des options affecte uniquement les nouvelles instances et ne modifiera pas les instances Octokit::Client existantes créées avec les options précédentes.
Chaque attribut écrit dans {octokit :: Configurable} peut être défini un à la fois:
Octokit . api_endpoint = 'http://api.github.dev'
Octokit . web_endpoint = 'http://github.dev'ou en lot:
Octokit . configure do | c |
c . api_endpoint = 'http://api.github.dev'
c . web_endpoint = 'http://github.dev'
endLes valeurs de configuration par défaut sont spécifiées dans {octokit :: par défaut}. De nombreux attributs rechercheront une valeur par défaut de l'env avant de renvoyer par défaut d'Octokit.
# Given $OCTOKIT_API_ENDPOINT is "http://api.github.dev"
client . api_endpoint
# => "http://api.github.dev" Les avertissements de dépréciation et les points de terminaison de l'API dans les avertissements d'aperçu du développement sont imprimés sur stdout par défaut, ceux-ci peuvent être désactivés en définissant le env OCTOKIT_SILENT=true .
Par défaut, Octokit ne dérange pas les demandes de réseau. Pour définir un délai d'expiration, transmettez les paramètres de délai d'expiration de Faraday sur le paramètre connection_options d'Octokit.
Octokit . configure do | c |
c . api_endpoint = ENV . fetch ( 'GITHUB_API_ENDPOINT' , 'https://api.github.com/' )
c . connection_options = {
request : {
open_timeout : 5 ,
timeout : 5
}
}
endVous devez définir un délai d'expiration afin d'éviter le module de délai d'expiration de Ruby, qui peut arroser votre serveur. Voici quelques ressources pour plus d'informations à ce sujet:
À partir de la version 2.0, Octokit est compatible sur l'hypermedia. Sous le capot, {Octokit :: Client} utilise Sawyer, un client Hypermedia construit sur Faraday.
Les ressources renvoyées par les méthodes d'Octokit contiennent non seulement des données mais des relations de liaison hypermedia:
user = client . user 'technoweenie'
# Get the repos rel, returned from the API
# as repos_url in the resource
user . rels [ :repos ] . href
# => "https://api.github.com/users/technoweenie/repos"
repos = user . rels [ :repos ] . get . data
repos . last . name
# => "faraday-zeromq" Lors du traitement des réponses de l'API, tous les attributs *_url sont abordés dans la collection de relations de liaison. Tout attribut url devient .rels[:self] .
Vous remarquez peut-être que de nombreuses relations de liens ont des espaces réservés variables. Octokit prend en charge les modèles URI pour l'expansion paramétrée d'URI:
repo = client . repo 'pengwynn/pingwynn'
rel = repo . rels [ :issues ]
# => #<Sawyer::Relation: issues: get https://api.github.com/repos/pengwynn/pingwynn/issues{/number}>
# Get a page of issues
rel . get . data
# Get issue #2
rel . get ( :uri => { :number => 2 } ) . dataSi vous souhaitez utiliser Octokit comme client API Hypermedia pur, vous pouvez commencer à la racine de l'API et suivre les relations de liaison à partir de là:
root = client . root
root . rels [ :repository ] . get :uri => { :owner => "octokit" , :repo => "octokit.rb" }
root . rels [ :user_repositories ] . get :uri => { :user => "octokit" } ,
:query => { :type => "owner" }Octokit 3.0 vise à être axé sur l'hypermédia, en supprimant la construction de l'URL interne actuellement utilisée dans tout le client.
Version 4.0
state dans les options de méthode.La version 3.0 comprend quelques modifications de rupture lors de la mise à niveau de v2.xx:
Le type de support par défaut est maintenant v3 au lieu de beta . Si vous devez demander l'ancien type de support, vous pouvez définir le type de support par défaut pour le client:
Octokit . default_media_type = "application/vnd.github.beta+json"ou par remarque
client . emails ( :accept => "application/vnd.github.beta+json" ) La méthode Octokit::Client#create_download a été supprimée.
La version 2.0 comprend une usine Client entièrement réécrite qui mémorise désormais les instances client basées sur des options de configuration uniques. Les changements de rupture incluent également:
:oauth_token est maintenant :access_token:auto_traversal est maintenant :auto_paginateHashie::Mash a été supprimé. Les réponses renvoient désormais un objet Sawyer::Resource . Ce nouveau type se comporte principalement comme un Hash de rubis, mais ne soutient pas pleinement l'API Hashie::Mash .Octokit::TooManyRequests et Octokit::TooManyLoginAttemptssearch_* de v1.x se trouvent maintenant sur legacy_search_*DateTime appropriés. Les versions précédentes ont sorti des champs DateTime sous forme d'objets «String». Étant donné qu'Octokit emploie Faraday sous le capot, un certain comportement peut être étendu via le middleware.
Souvent, il est utile de savoir ce que fait Octokit sous le capot. Vous pouvez ajouter un bûcheron au middleware qui vous permet de jeter un œil au trafic HTTP sous-jacent:
stack = Faraday :: RackBuilder . new do | builder |
builder . use Faraday :: Retry :: Middleware , exceptions : Faraday :: Retry :: Middleware :: DEFAULT_EXCEPTIONS + [ Octokit :: ServerError ] # or Faraday::Request::Retry for Faraday < 2.0
builder . use Octokit :: Middleware :: FollowRedirects
builder . use Octokit :: Response :: RaiseError
builder . use Octokit :: Response :: FeedParser
builder . response :logger do | logger |
logger . filter ( /(Authorization: "(token|Bearer) )( w +)/ , '1[REMOVED]' )
end
builder . adapter Faraday . default_adapter
end
Octokit . middleware = stack
client = Octokit :: Client . new
client . user 'pengwynn' I, [2013-08-22T15:54:38.583300 #88227] INFO -- : get https://api.github.com/users/pengwynn
D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
User-Agent: "Octokit Ruby Gem 2.0.0.rc4"
I, [2013-08-22T15:54:38.843313 #88227] INFO -- Status: 200
D, [2013-08-22T15:54:38.843459 #88227] DEBUG -- response: server: "GitHub.com"
date: "Thu, 22 Aug 2013 20:54:40 GMT"
content-type: "application/json; charset=utf-8"
transfer-encoding: "chunked"
connection: "close"
status: "200 OK"
x-ratelimit-limit: "60"
x-ratelimit-remaining: "39"
x-ratelimit-reset: "1377205443"
...
Voir le Faraday Readme pour plus de magie du middleware.
Si vous souhaitez augmenter les performances, étirer votre limite de taux d'API ou éviter de payer la taxe Hypermedia, vous pouvez utiliser le cache Faraday HTTP.
Ajoutez le joyau à votre gemfile
gem 'faraday-http-cache'
Ensuite, construisez votre propre middleware Faraday:
stack = Faraday :: RackBuilder . new do | builder |
builder . use Faraday :: HttpCache , serializer : Marshal , shared_cache : false
builder . use Octokit :: Response :: RaiseError
builder . adapter Faraday . default_adapter
end
Octokit . middleware = stack Une fois configuré, le middleware stockera les réponses dans le cache en fonction de l'empreinte digitale ETAG et dessera les réponses pour les futures réponses 304 pour la même ressource. Voir le projet Readme pour une utilisation avancée.
Si vous souhaitez pirater Octokit localement, nous essayons de faire du bootstrap le projet aussi indolore que possible. Pour commencer à pirater, cloner et courir:
script/bootstrap
Cela installera les dépendances du projet et vous fera fonctionner. Si vous voulez exécuter une console Ruby pour piquer sur Octokit, vous pouvez en lancer un avec:
script/console
L'utilisation des scripts dans ./script au lieu de bundle exec rspec , bundle console , etc. garantit que vos dépendances sont à jour.
Nous voulons que les communautés Octokit.rb et les plus grandes octokit soient ouvertes et accueillantes. Veuillez lire et suivre à la fois en esprit et en lettre de conduite.
Octokit utilise le magnétoscope pour enregistrer et lire les luminaires de l'API pendant les essais. Ces cassettes (luminaires) font partie du projet GIT dans le dossier spec/cassettes . Si vous n'enregistrez pas de nouvelles cassettes, vous pouvez exécuter les spécifications avec des cassettes existantes avec:
script/test
Octokit utilise des variables environnementales pour le stockage des informations d'identification utilisées dans les tests. Si vous testez un point de terminaison de l'API qui ne nécessite pas d'authentification, vous pouvez vous échapper sans aucune configuration supplémentaire. Pour la plupart, les tests utilisent un client authentifié, en utilisant un jeton stocké dans ENV['OCTOKIT_TEST_GITHUB_TOKEN'] . Il existe plusieurs méthodes d'authentification différentes utilisées dans l'API. Voici la liste complète des variables environnementales configurables pour tester Octokit:
| Variable Env | Description |
|---|---|
OCTOKIT_TEST_GITHUB_LOGIN | Nom de connexion GitHub (de préférence un créé spécifiquement pour les tests contre). |
OCTOKIT_TEST_GITHUB_PASSWORD | Mot de passe pour le test de connexion GitHub. |
OCTOKIT_TEST_GITHUB_TOKEN | Jeton d'accès personnel pour le test de connexion GitHub. |
OCTOKIT_TEST_GITHUB_CLIENT_ID | Testez l'ID du client de l'application OAuth. |
OCTOKIT_TEST_GITHUB_CLIENT_SECRET | Testez le secret du client de la demande OAuth. |
OCTOKIT_TEST_GITHUB_REPOSITORY | Test du référentiel pour effectuer des actions destructrices contre, cela ne devrait être défini sur aucun référentiel d'importance. Créé automatiquement par la suite de tests si par défaut non existant : api-sandbox |
OCTOKIT_TEST_GITHUB_ORGANIZATION | Organisation de test. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN | Nom de connexion GitHub Enterprise. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN | Token GitHub Enterprise. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD | Mot de passe de la console de gestion d'entreprise GitHub. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT | GitHub Enterprise Hostname. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT | GitHub Enterprise Management Console Endpoint. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_ENDPOINT | GitHub Enterprise Server GHES Gérer le point de terminaison. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_USERNAME | GitHub Enterprise Server GHES Gérer le nom d'utilisateur. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_PASSWORD | GitHub Enterprise Server GHES Gérer le mot de passe. |
OCTOKIT_TEST_GITHUB_INTEGRATION | Intégration GitHub appartenant à votre organisation de test. |
OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION | Installation de l'intégration GitHub spécifiée ci-dessus. |
OCTOKIT_TEST_INTEGRATION_PEM_KEY | Chemin de fichier vers la clé privée générée à partir de votre intégration. |
Étant donné que nous rafraîchons périodiquement nos cassettes, veuillez garder à l'esprit certains points lors de la rédaction de nouvelles spécifications.
Cette bibliothèque vise à soutenir et est testée par rapport aux implémentations Ruby suivantes:
Si quelque chose ne fonctionne pas sur l'une de ces versions Ruby, c'est un bug.
Cette bibliothèque peut fonctionner par inadvertance (ou semble fonctionner) sur d'autres implémentations Ruby, mais le support ne sera fourni que pour les versions énumérées ci-dessus.
Si vous souhaitez que cette bibliothèque prenne en charge une autre version Ruby, vous pouvez vous porter volontaire pour être mainteneur. Être un responsable consiste à s'assurer que tous les tests s'exécutent et transmettent cette implémentation. Lorsque quelque chose rompt votre implémentation, vous serez responsable de fournir des correctifs en temps opportun. Si des problèmes critiques pour une implémentation particulière existent au moment d'une version majeure, la prise en charge de cette version Ruby peut être supprimée.
Cette bibliothèque vise à adhérer au versioning sémantique 2.0.0. Les violations de ce programme doivent être signalées comme des bogues. Plus précisément, si une version mineure ou patch est publiée qui rompt la compatibilité en arrière, cette version doit être immédiatement arrachée et / ou une nouvelle version devrait être immédiatement publiée qui restaure la compatibilité. La rupture de modifications de l'API publique ne sera introduite qu'avec de nouvelles versions majeures. À la suite de cette politique, vous pouvez (et devriez) spécifier une dépendance à ce joyau en utilisant la contrainte de version pessimiste avec deux chiffres de précision. Par exemple:
spec.add_dependency 'octokit', '~> 3.0'
Les modifications apportées entre les versions peuvent être vues sur la page des versions du projet.
Dans la plupart des cas, il serait préférable d'utiliser des webhooks, mais parfois les webhooks ne fournissent pas toutes les informations nécessaires. Dans les cas où l'on pourrait avoir besoin de sonder pour les progrès ou de réessayer une demande d'échec, nous avons conçu Octopoller. Octopoller est un micro-gem parfait pour faire des demandes de répétition.
Octopoller . poll ( timeout : 15 . seconds ) do
begin
client . request_progress # ex. request a long running job's status
rescue Error
:re_poll
end
endCeci est utile lors de la demande de progrès d'un travail de longue date (ex. Demander des progrès d'une importation d'une source).
Copyright (C) 2009-2014 Wynn Pays-Bas, Adam Stacoviak, Erik Michaels-Ober
L'autorisation est accordée gratuitement à toute personne qui obtient une copie de ce logiciel et des fichiers de documentation associés (le "logiciel"), pour traiter le logiciel sans restriction, y compris sans limiter les droits d'utilisation, de copie, de modification, de fusion, de publication, de distribution, de sublince et / ou de vendre des copies des conditions suivantes.
L'avis de droit d'auteur ci-dessus et le présent avis d'autorisation sont inclus dans toutes les copies ou des parties substantielles du logiciel.
Le logiciel est fourni "tel quel", sans garantie d'aucune sorte, express ou implicite, y compris, mais sans s'y limiter, les garanties de qualité marchande, d'adéquation à un usage particulier et de non-contrefaçon. En aucun cas, les auteurs ou les titulaires de droits d'auteur ne seront pas responsables de toute réclamation, dommage ou autre responsabilité, que ce soit dans une action de contrat, de délit ou autre, découlant de, ou en relation avec le logiciel ou l'utilisation ou d'autres transactions dans le logiciel.
