octokit.rb下载octokit.rb源代码下载

Octokit

请注意，我们最近将其重命名为main 4-stable分支。如果您在本地更改Octokit的代码，这可能会影响您。有关更多详细信息以及重新配置您本地克隆以获取新的分支名称的步骤，请查看此帖子。

GitHub API的Ruby Toolkit。

升级？在撞到新的主要版本之前，请检查升级指南。

哲学
安装
提出要求
1. 其他查询参数
消耗资源
访问HTTP响应
处理错误
验证
1. 基本身份验证
2. Oauth访问令牌
3. 两因素身份验证
4. 使用.netrc文件
5. 应用程序身份验证
6. github应用
默认结果per_page
分页
1. 自动分页
与GitHub Enterprise合作
与github企业中的github.com API互动
与GitHub企业管理API互动
与GitHub企业管理控制台API互动
SSL连接错误
配置和默认值
1. 配置模块默认值
2. 使用ENV变量
3. 超时
HyperMedia剂
1. Octokit中的HyperMedia
2. URI模板
3. 完整的HyperMedia Experience™
升级指南
1. 从1.xx升级
高级用法
1. 调试
2. 缓存
在Octokit.rb上黑客
1. 行为守则
2. 跑步和编写新测试
支持的红宝石版本
版本控制
提出重复请求
执照

哲学

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集合，以更容易获得超媒体支持。

访问HTTP响应

虽然大多数方法返回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访问令牌

OAuth访问令牌提供了使用您的用户名和密码的两个主要好处：

可撤销的访问。访问令牌可以被撤销，只能删除该令牌的访问，而无需更改任何地方。
有限的访问。访问令牌具有访问范围，可以使API资源更加详细。例如，您可以授予第三方访问您的GIST，而不是私人存储库。

要与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>" } )

使用.netrc文件

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'

github应用

Octokit.rb还使用GitHub应用程序支持身份验证，该应用需要生成的JWT令牌。

 client = Octokit :: Client . new ( :bearer_token => "<your jwt token>" )
client . app
# => about GitHub App info

默认结果per_page

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 ，并试图不超越您的费率限制，但您可能想使用自定义模式来穿越大列表。

与GitHub Enterprise合作

有了一些设置，您也可以将OctOkit与GitHub Enterprise实例一起使用。

与github企业中的github.com API互动

要与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企业管理API互动

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 . new

与GitHub企业管理控制台API互动

GitHub企业管理控制台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

SSL连接错误

首先设置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

使用ENV变量

{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的超时模块，该模块可以软管您的服务器。以下是一些资源以获取有关此信息的更多信息：

Ruby中最古老的错误 - 为什么RACK ::超时可能会软管您的服务器
超时：Ruby是最危险的API
红宝石超时的最终指南

HyperMedia剂

从版本2.0开始，OCTOKIT具有超媒体的启用。在引擎盖下，{octokit ::客户端}使用了在法拉第建立的HyperMedia客户端Sawyer。

Octokit中的HyperMedia

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] 。

URI模板

您可能会注意到许多链接关系都有可变的占位符。 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

完整的HyperMedia Experience™

如果您想将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 。
对Ruby <2.0的支持。
增加了对新企业仅API的支持。
增加了对存储库重定向的支持。

版本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方法。

从1.xx升级

版本2.0包括一个完全重写的Client工厂，该工厂现在根据唯一的配置选项对客户端实例进行记忆。破坏变化还包括：

:oauth_token现在:access_token
:auto_traversal现在:auto_paginate
Hashie::Mash已被删除。响应现在返回一个Sawyer::Resource对象。这种新类型的行为主要像红宝石Hash ，但并不能完全支持Hashie::Mash API。
在适当的情况下提出了两种新的客户错误类型： Octokit::TooManyRequests和Octokit::TooManyLoginAttempts
现在从v1.x中找到search_*方法，在legacy_search_*
对NETRC的支持需要您的Gemfile或Gemspec中的NetRC Gem。
DateTime字段现在是正确的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.rb上黑客

如果您想在本地攻击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`	从集成产生的私钥的文件路径。

由于我们会定期刷新录音带，因此在编写新规格时请记住一些观点。

规格应该是愿意的。规格期间进行的HTTP调用应该可以一遍又一遍地运行。这意味着如果该名称必须是唯一的，则在创建已知资源之前删除已知资源。
规格应能够以随机顺序运行。如果规格取决于另一个资源作为固定装置，请确保在规格范围内创建的固定装置，而不是依赖以前的规格来创建所需的数据。
不依赖身份验证的用户信息。而不是在资源中断言实际值，而是尝试断言键的存在或响应是一个数组。我们正在测试客户，而不是API。

支持的红宝石版本

该图书馆旨在支持并针对以下Ruby实现进行测试：

红宝石2.7
红宝石3.0
红宝石3.1
红宝石3.2
红宝石3.3

如果这些红宝石版本中的某种内容不起作用，那是一个错误。

该库可能会在其他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

特此免费授予获得此软件副本和相关文档文件副本（“软件”）的任何人，以无限制处理该软件，包括无限制的使用权，复制，复制，修改，合并，合并，发布，分发，分发，分发，订婚，和/或允许软件的副本，并允许对以下条件提供以下条件，以下是以下条件。

上述版权通知和此许可通知应包含在软件的所有副本或大量部分中。

该软件是“原样”提供的，没有任何形式的明示或暗示保证，包括但不限于适销性，特定目的的适用性和非侵权的保证。在任何情况下，作者或版权持有人都不应对任何索赔，损害赔偿或其他责任责任，无论是在合同，侵权的诉讼中还是其他责任，是由软件，使用或与软件中的使用或其他交易有关的。

展开

octokit.rb