請注意,我們最近將其重命名為
main4-stable分支。如果您在本地更改Octokit的代碼,這可能會影響您。有關更多詳細信息以及重新配置您本地克隆以獲取新的分支名稱的步驟,請查看此帖子。
GitHub API的Ruby Toolkit。
升級?在撞到新的主要版本之前,請檢查升級指南。
API包裝器應反映出他們寫的語言的成語。 octokit.rb將github api包裝在遵循紅寶石公約的平坦API客戶端中,幾乎不需要休息。大多數方法都具有所需輸入的位置參數,並且用於可選參數,標題或其他選項的選項:
client = Octokit :: Client . new
# Fetch a README with Accept header for HTML format
client . readme 'al3x/sovereign' , :accept => 'application/vnd.github.html' 通過紅寶石安裝
gem install octokit
...或添加到您的Gemfile
gem "octokit"
訪問Ruby的庫:
require 'octokit'
API方法可作為客戶端實例方法可用。
# 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 . user傳遞其他參數以獲取基於請求時,請使用以下語法:
# 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' } ) 大多數方法返回一個Resource對象,該對象提供了DOT表示法和[]返回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"注意:將URL字段淘汰為單獨的.rels集合,以更容易獲得超媒體支持。
雖然大多數方法返回Resource對像或布爾值,但有時您可能需要訪問RAW HTTP響應標頭。您可以使用Client#last_response訪問最後的HTTP響應:
user = client . user 'andrewpthorp'
response = client . last_response
etag = response . headers [ :etag ] 當API返回錯誤響應時,OCTOKIT將提出Ruby例外。
可以根據API返回的錯誤來提高一系列不同的例外 - 例如:
400 Bad Request響應將導致Octokit::BadRequest錯誤403 Forbidden錯誤的“限制限制”消息將導致Octokit::TooManyRequests錯誤所有不同的異常類都從Octokit::Error繼承,並公開#response_status , #response_headers和#response_body 。對於驗證錯誤, #errors將返回Array Hash ,並帶有API返回的詳細信息。
OCTOKIT支持GitHub API支持的各種身份驗證方法:
使用您的github用戶名和密碼是開始提出身份驗證請求的最簡單方法:
client = Octokit :: Client . new ( :login => 'defunkt' , :password => 'c0d3b4ssssss!' )
user = client . user
user . login
# => "defunkt"儘管基本身份驗證使您可以快速開始,但OAuth訪問令牌是代表用戶身份驗證的首選方法。
OAuth訪問令牌提供了使用您的用戶名和密碼的兩個主要好處:
要與Octokit客戶端一起使用訪問令牌,請在以下方面傳遞您的令牌:access_token選項參數代替您的用戶名和密碼:
client = Octokit :: Client . new ( :access_token => "<your 40 char token>" )
user = client . user
user . login
# => "defunkt"您可以通過github帳戶設置創建訪問令牌。
兩因素身份驗證通過需要更多信息才能登錄為帳戶增加安全性。
對API調用使用兩因素身份驗證就像將所需的標頭添加作為選項一樣簡單:
client = Octokit :: Client . new
:login => 'defunkt' ,
:password => 'c0d3b4ssssss!'
user = client . user ( "defunkt" , :headers => { "X-GitHub-OTP" => "<your 2FA token>" } )OCTOKIT支持從NETRC文件(默認為~/.netrc )中讀取憑據。鑑於您的NetRC中的這些行:
machine api.github.com
login defunkt
password c0d3b4ssssss!
您現在可以使用這些憑據來創建一個客戶:
client = Octokit :: Client . new ( :netrc => true )
client . login
# => "defunkt"但是我想用你說的oauth 。由於GitHub API支持使用OAuth代幣作為基本密碼,因此您完全可以:
machine api.github.com
login defunkt
password <your 40 char token>
注意:對NETRC的支持需要將NetRC GEM添加到您的Gemfile或.gemspec中。
OCTOKIT還支持使用OAUTH應用程序客戶憑證的僅使用應用程序的身份驗證。使用應用程序憑據將導致代表應用程序進行匿名API調用,以利用更高的利率限制。
client = Octokit :: Client . new
:client_id => "<your 20 char id>" ,
:client_secret => "<your 40 char secret>"
user = client . user 'defunkt'Octokit.rb還使用GitHub應用程序支持身份驗證,該應用需要生成的JWT令牌。
client = Octokit :: Client . new ( :bearer_token => "<your jwt token>" )
client . app
# => about GitHub App info GitHub API的默認結果為30,如果您想添加更多信息,則必須在Octokit配置期間這樣做。
Octokit :: Client . new ( access_token : "<your 40 char token>" , per_page : 100 ) 許多GitHub API資源都在分頁。雖然您可能很想開始添加:page參數,但API將鏈接返回到Link響應標頭的下一個,上一個和最後一個頁面作為HyperMedia鏈接關係。
issues = client . issues 'rails/rails'
issues . concat client . get ( client . last_response . rels [ :next ] . href )對於小型資源列表,Octokit提供自動分頁。啟用此操作後,分頁資源的呼叫將獲取並將每個頁面的結果加成一個單個數組:
client . auto_paginate = true
issues = client . issues 'rails/rails'
issues . length
# => 702您還可以為所有OCTOKIT客戶端實例啟用自動分頁:
Octokit . configure do | c |
c . auto_paginate = true
end注意:雖然Octokit自動分頁將頁面大小設置為最多100 ,並試圖不超越您的費率限制,但您可能想使用自定義模式來穿越大列表。
有了一些設置,您也可以將OctOkit與GitHub Enterprise實例一起使用。
要與GitHub Enterprise中的“常規” GitHub.com API進行交互,只需配置api_endpoint即可匹配主機名。例如:
Octokit . configure do | c |
c . api_endpoint = "https://<hostname>/api/v3/"
end
client = Octokit :: Client . new ( :access_token => "<your 40 char token>" )GitHub Enterprise Admin API在另一個客戶端下: EnterpriseAdminClient 。您需要擁有一個管理員帳戶才能使用這些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 . newGitHub企業管理控制台API也位於單獨的客戶端: EnterpriseManagementConsoleClient 。為了使用它,您需要同時提供管理控制台密碼以及管理控制台的端點。這與上面提供的API端點不同。
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 . new首先設置GitHub Enterprise安裝時,您可能需要暫時禁用SSL。您可以通過以下配置來執行此操作:
client . connection_options [ :ssl ] = { :verify => false }請記住轉彎:verify回到true ,因為這對於安全通信很重要。
當創建新客戶端實例時, Octokit::Client會接受一系列選項,而octokit的配置API允許您在模塊級別設置配置選項。如果您基於某些共享默認值創建許多客戶端實例,這將特別方便。更改選項僅影響新實例,不會修改使用以前的選項創建的現有Octokit::Client實例。
{octokit ::可配置}中的每個可寫屬性都可以一次設置一個:
Octokit . api_endpoint = 'http://api.github.dev'
Octokit . web_endpoint = 'http://github.dev'或分批:
Octokit . configure do | c |
c . api_endpoint = 'http://api.github.dev'
c . web_endpoint = 'http://github.dev'
end{octokit :: default}中指定默認配置值。在返回OctOkit的默認值之前,許多屬性會從env中尋找默認值。
# Given $OCTOKIT_API_ENDPOINT is "http://api.github.dev"
client . api_endpoint
# => "http://api.github.dev"默認情況下,可以通過設置ENC OCTOKIT_SILENT=true來將其打印到開發預覽警告中的棄用警告和API端點。
默認情況下,Octokit不超時網絡請求。要設置超時,請將Faraday超時設置傳遞到Octokit的connection_options設置。
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
}
}
end您應該設置超時,以避免Ruby的超時模塊,該模塊可以軟管您的服務器。以下是一些資源以獲取有關此信息的更多信息:
從版本2.0開始,OCTOKIT具有超媒體的啟用。在引擎蓋下,{octokit ::客戶端}使用了在法拉第建立的HyperMedia客戶端Sawyer。
OCTOKIT方法返回的資源不僅包含數據,還包含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"處理API響應時,所有*_url屬性都將被淘汰到鏈接關係集合中。任何url屬性變為.rels[:self] 。
您可能會注意到許多鏈接關係都有可變的佔位符。 OCTOKIT支持用於參數化URI擴展的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 } ) . data如果您想將OctOkit用作純HyperMedia API客戶端,則可以從API root開始並從那裡遵循鏈接關係:
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的目標是以超媒體為導向,以刪除當前在客戶中使用的內部URL構造。
版本4.0
state 。版本3.0包括從v2.xx升級時進行的幾個打破更改:
默認媒體類型現在為v3而不是beta 。如果需要請求舊的媒體類型,則可以為客戶端設置默認媒體類型:
Octokit . default_media_type = "application/vnd.github.beta+json"或每次要求
client . emails ( :accept => "application/vnd.github.beta+json" )已刪除了長期播放的Octokit::Client#create_download方法。
版本2.0包括一個完全重寫的Client工廠,該工廠現在根據唯一的配置選項對客戶端實例進行記憶。破壞變化還包括:
:oauth_token現在:access_token:auto_traversal現在:auto_paginateHashie::Mash已被刪除。響應現在返回一個Sawyer::Resource對象。這種新類型的行為主要像紅寶石Hash ,但並不能完全支持Hashie::Mash API。Octokit::TooManyRequests和Octokit::TooManyLoginAttemptssearch_*方法,在legacy_search_*DateTime對象。以前的版本將DateTime字段作為“字符串”對象輸出。 由於Octokit在引擎蓋下使用法拉第,因此可以通過中間件擴展某些行為。
通常,它有助於知道Octokit在引擎蓋下做什麼。您可以將記錄儀添加到中間件中,使您能夠窺視基礎的HTTP流量:
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"
...
有關更多中間件魔術,請參見Faraday Readme。
如果您想提高性能,擴展API速率限製或避免繳納HyperMedia稅,則可以使用Faraday HTTP緩存。
將寶石添加到您的Gemfile
gem 'faraday-http-cache'
接下來,構建自己的法拉第中間件:
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一旦配置,中間件將基於ETAG指紋存儲在緩存中,並將其備份為將來的304響應,以獲得相同的資源。有關高級用法,請參見項目README。
如果您想在本地攻擊Octokit,我們會嘗試使該項目盡可能無痛。要開始黑客,克隆並運行:
script/bootstrap
這將安裝項目依賴關係並讓您啟動並運行。如果您想運行一個紅寶石控制台在Octokit上戳,則可以使用一個:
script/console
使用./script中的腳本代替bundle exec rspec , bundle console等。確保您的依賴項是最新的。
我們希望OCTOKIT.RB和較大的Octokit社區都能開放和歡迎環境。請閱讀並遵循精神和字母行為準則。
OCTOKIT在測試運行期間使用VCR記錄和播放API固定裝置。這些盒式盒(固定裝置)是spec/cassettes文件夾中GIT項目的一部分。如果您不錄製新盒式盒式盒子,則可以使用現有盒式盒子運行規格:
script/test
OCTOKIT使用環境變量來存儲用於測試的憑據。如果您正在測試不需要身份驗證的API端點,則無需任何其他配置即可擺脫。在大多數情況下,測試使用經過身份驗證的客戶端,使用存儲在ENV['OCTOKIT_TEST_GITHUB_TOKEN']中的令牌。 API上使用了幾種不同的身份驗證方法。這是用於測試OCTOKIT的可配置環境變量的完整列表:
| env變量 | 描述 |
|---|---|
OCTOKIT_TEST_GITHUB_LOGIN | GitHub登錄名(最好是專門用於測試的名稱)。 |
OCTOKIT_TEST_GITHUB_PASSWORD | 測試GITHUB登錄的密碼。 |
OCTOKIT_TEST_GITHUB_TOKEN | 個人訪問令牌用於測試GITHUB登錄。 |
OCTOKIT_TEST_GITHUB_CLIENT_ID | 測試OAUTH應用程序客戶端ID。 |
OCTOKIT_TEST_GITHUB_CLIENT_SECRET | 測試OAuth應用程序客戶秘密。 |
OCTOKIT_TEST_GITHUB_REPOSITORY | 測試存儲庫要對其執行破壞性動作,不應將其設置為任何重要的存儲庫。如果不存在默認值,則由測試套件自動創建: api-sandbox |
OCTOKIT_TEST_GITHUB_ORGANIZATION | 測試組織。 |
OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN | github企業登錄名。 |
OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN | Github企業令牌。 |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD | GitHub企業管理控制台密碼。 |
OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT | GitHub Enterprise主機名。 |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT | GitHub企業管理控制台端點。 |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_ENDPOINT | github企業服務器GHE管理端點。 |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_USERNAME | GitHub企業服務器GHES管理用戶名。 |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_PASSWORD | GitHub Enterprise Server GHES管理密碼。 |
OCTOKIT_TEST_GITHUB_INTEGRATION | 您的測試組織擁有的GitHub集成。 |
OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION | 上述GitHub集成的安裝。 |
OCTOKIT_TEST_INTEGRATION_PEM_KEY | 從集成產生的私鑰的文件路徑。 |
由於我們會定期刷新錄音帶,因此在編寫新規格時請記住一些觀點。
該圖書館旨在支持並針對以下Ruby實現進行測試:
如果這些紅寶石版本中的某種內容不起作用,那是一個錯誤。
該庫可能會在其他Ruby實施方面無意間(或似乎似乎都在起作用),但只能為上述版本提供支持。
如果您希望此庫支持另一個Ruby版本,則可以自願成為維護者。成為維護者需要確保所有測試進行並通過該實現。當您的實施破壞時,您將負責及時提供補丁。如果在重大版本時存在特定實施的關鍵問題,則可以放棄對Ruby版本的支持。
該庫旨在遵守語義版本2.0.0。違反該計劃的行為應報告為錯誤。具體而言,如果釋放了向後兼容的次要版本或補丁版本,則應立即將該版本劃定和/或新版本應立即釋放以恢復兼容性。只有新的主要版本才能引入對公共API的破壞更改。由於此策略,您可以(並且應該)使用帶有兩個精度數字的悲觀版本約束來指定對此GEM的依賴。例如:
spec.add_dependency 'octokit', '~> 3.0'
版本之間的更改可以在項目發布頁面上看到。
在大多數情況下,最好使用Webhooks,但是有時Webhooks並不能提供所需的所有信息。在可能需要進行投票以進行進度或重試失敗請求的情況下,我們設計了章魚。 Octopoller是一種微寶石,非常適合發出重複請求。
Octopoller . poll ( timeout : 15 . seconds ) do
begin
client . request_progress # ex. request a long running job's status
rescue Error
:re_poll
end
end當提出長期運行的作業進度的請求時,這很有用(Ex。請求源導入的進度)。
版權(C)2009-2014 Wynn荷蘭,Adam Stacoviak,Erik Michaels-ober
特此免費授予獲得此軟件副本和相關文檔文件副本(“軟件”)的任何人,以無限制處理該軟件,包括無限制的使用權,複製,複製,修改,合併,合併,發布,分發,分發,分發,訂婚,和/或允許軟件的副本,並允許對以下條件提供以下條件,以下是以下條件。
上述版權通知和此許可通知應包含在軟件的所有副本或大量部分中。
該軟件是“原樣”提供的,沒有任何形式的明示或暗示保證,包括但不限於適銷性,特定目的的適用性和非侵權的保證。在任何情況下,作者或版權持有人都不應對任何索賠,損害賠償或其他責任責任,無論是在合同,侵權的訴訟中還是其他責任,是由軟件,使用或與軟件中的使用或其他交易有關的。