octokit.rb
v9.2.0
Обратите внимание, что мы недавно переименовали
4-stableфилиал вmain. Это может повлиять на вас, если вы вносите изменения в код Octokit на локальном уровне. Для получения более подробной информации и для шагов по переконфигурированию вашего локального клона для нового названия филиала, посмотрите этот пост.
Ruby Toolkit для API GitHub.
Обновление? Проверьте руководство по обновлению, прежде чем натолкнуться на новую крупную версию.
Обертки 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' Установите через Rubygems
gem install octokit
... или добавить в свой драгоценный камень
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 объект, который обеспечивает точечные обозначения и [] доступ для полей, возвращаемых в ответе 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 объект или логический, иногда вам может потребоваться доступ к необработанным заголовкам ответов HTTP. Вы можете получить доступ к последнему http -ответу с Client#last_response :
user = client . user 'andrewpthorp'
response = client . last_response
etag = response . headers [ :etag ] Когда API возвращает ответ ошибки, Octokit поднимет исключение Ruby.
Диапазон различных исключений может быть поднят в зависимости от ошибки, возвращаемой API - например:
400 Bad Request приведет к ошибке Octokit::BadRequest403 Forbidden с сообщением «Limited Limited» приведет к ошибке Octokit::TooManyRequests Все различные классы исключений наследуют от Octokit::Error и разоблачают #response_status , #response_headers и #response_body . Для ошибок проверки #errors вернет Array Hash -эс с подробной информацией, возвращенной API.
Octokit поддерживает различные методы аутентификации, поддерживаемые API GitHub:
Использование вашего имени пользователя GitHub и пароля - самый простой способ начать выполнение аутентифицированных запросов:
client = Octokit :: Client . new ( :login => 'defunkt' , :password => 'c0d3b4ssssss!' )
user = client . user
user . login
# => "defunkt"В то время как базовая аутентификация позволяет вам начать работу быстро, токены доступа OAuth являются предпочтительным способом аутентификации от имени пользователей.
OAuth Access Token предоставляют два основных преимущества по сравнению с использованием имени пользователя и пароля:
Чтобы использовать токен доступа с клиентом 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 (Defalling to ~/.netrc ). Учитывая эти строки в вашем NetRC:
machine api.github.com
login defunkt
password c0d3b4ssssss!
Теперь вы можете создать клиента с этими учетными данными:
client = Octokit :: Client . new ( :netrc => true )
client . login
# => "defunkt"Но я хочу использовать OAuth, вы говорите. Поскольку API GitHub поддерживает использование токена OAuth в качестве основного пароля, вы полностью можете:
machine api.github.com
login defunkt
password <your 40 char token>
ПРИМЕЧАНИЕ. Поддержка NetRC требует добавления GEM NetRC в ваш 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 Результаты по умолчанию API GitHub 30, если вы хотите добавить больше, вы должны сделать это во время конфигурации Octokit.
Octokit :: Client . new ( access_token : "<your 40 char token>" , per_page : 100 ) Многие ресурсы GitHub API являются стравшими. В то время как у вас может возникнуть соблазн начать добавлять :page к вашим вызовам, API возвращает ссылки на следующие, предыдущие и последние страницы для вас в заголовке ответа Link в качестве связей с гипермедиа.
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 Auto Pagination установит размер страницы на максимум 100 и стремится не переоценить свой предел ставки, вы, вероятно, хотите использовать пользовательский шаблон для прохождения больших списков.
С небольшой настройкой вы также можете использовать Octokit с вашим экземпляром Github Enterprise.
Чтобы взаимодействовать с «обычными» API github.com в Github Enterprise, просто настройте api_endpoint в соответствии с вашим именем хоста. Например:
Octokit . configure do | c |
c . api_endpoint = "https://<hostname>/api/v3/"
end
client = Octokit :: Client . new ( :access_token => "<your 40 char token>" ) API -интерфейсы Github Enterprise Admin находятся под другим клиентом: 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 API -интерфейсы консоли управления Github Enterprise также находятся под отдельным клиентом: 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. Вы можете сделать это со следующей конфигурацией:
client . connection_options [ :ssl ] = { :verify => false } Не забудьте повернуть :verify вернуть true , так как это важно для безопасного общения.
В то время как Octokit::Client принимает диапазон параметров при создании нового экземпляра клиента, API конфигурации Octokit позволяет установить параметры конфигурации на уровне модуля. Это особенно удобно, если вы создаете ряд экземпляров клиента на основе некоторых общих дефолтов. Изменение параметров влияет только на новые экземпляры и не будет изменять существующие экземпляры 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}. Многие атрибуты будут искать значение по умолчанию из Env, прежде чем вернуть дефолт Octokit.
# Given $OCTOKIT_API_ENDPOINT is "http://api.github.dev"
client . api_endpoint
# => "http://api.github.dev" Предупреждения об испаке и конечные точки API При предварительном просмотре предварительного просмотра печатаются по умолчанию, их можно отключить, установив Env OCTOKIT_SILENT=true .
По умолчанию Octokit не выполняет сетевые запросы на тайм -аут. Чтобы установить тайм -аут, передайте настройки тайм -аута Faraday к настройке Octokit's 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 :: client} использует Sawyer, клиент Hypermedia, построенный на Faraday.
Ресурсы, возвращаемые методами Octokit, содержат не только данные, но и гипермедиа связи:
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 в качестве клиента API Pure Hypermedia, вы можете начать с корня API и перейти оттуда связаны:
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 Object. Этот новый тип ведет в основном как рубиновый Hash , но не полностью поддерживает API Hashie::Mash .Octokit::TooManyRequests и Octokit::TooManyLoginAttemptssearch_* от v1.x теперь найдены на legacy_search_*DateTime . Предыдущие версии, выведенные поля DateTime, как объекты «строки». Поскольку Octokit использует Faraday под капотом, некоторое поведение может быть расширено через промежуточное программное обеспечение.
Часто это помогает узнать, что делает 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 или избежать уплаты налога на гипермедиа, вы можете использовать кэш Faraday HTTP.
Добавьте драгоценный камень в свой драгоценный камень
gem 'faraday-http-cache'
Далее постройте свое собственное промежуточное программное обеспечение 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 После настройки промежуточное программное обеспечение будет хранить ответы в кэше на основе отпечатков пальцев ETAG и обслуживать их для будущих 304 ответов для того же ресурса. Смотрите проект Readme для расширенного использования.
Если вы хотите взломать Octokit на местном уровне, мы стараемся сделать загрузку проекта максимально безболезненным. Чтобы начать взлом, клонировать и бежать:
script/bootstrap
Это установит зависимости проекта и запустит вас. Если вы хотите запустить консоль Ruby, чтобы тыкнуть на Octokit, вы можете запустить один с:
script/console
Использование сценариев в ./script вместо bundle exec rspec , bundle console и т. Д. Убедится, что ваши зависимости будут актуальны.
Мы хотим, чтобы как Octokit.rb, так и более крупные октакит были открытыми и гостеприимными средами. Пожалуйста, прочитайте и следуйте как по духу, так и по письму поведения.
Octokit использует VCR для записи и воспроизведения светильников API во время тестовых прогонов. Эти кассеты (светильники) являются частью проекта GIT в папке spec/cassettes . Если вы не записываете новые кассеты, вы можете запустить спецификации с существующими кассетами:
script/test
Octokit использует переменные окружающей среды для хранения учетных данных, используемых при тестировании. Если вы тестируете конечную точку API, которая не требует аутентификации, вы можете уйти без какой -либо дополнительной конфигурации. По большей части тесты используют аутентифицированный клиент, используя токен, хранящийся в ENV['OCTOKIT_TEST_GITHUB_TOKEN'] . Есть несколько различных методов аутентификации, используемых по всему API. Вот полный список настраиваемых переменных окружающей среды для тестирования Octokit:
| Env Переменная | Описание |
|---|---|
OCTOKIT_TEST_GITHUB_LOGIN | Имя входа в систему GitHub (предпочтительно одно создано специально для тестирования). |
OCTOKIT_TEST_GITHUB_PASSWORD | Пароль для тестирования GitHub Login. |
OCTOKIT_TEST_GITHUB_TOKEN | Персональный токен доступа для входа в тест GitHub. |
OCTOKIT_TEST_GITHUB_CLIENT_ID | Проверьте идентификатор клиента приложения OAuth. |
OCTOKIT_TEST_GITHUB_CLIENT_SECRET | Проверьте секрет клиента oauth. |
OCTOKIT_TEST_GITHUB_REPOSITORY | Испытательный репозиторий для выполнения разрушительных действий против, это не должно быть установлено на какое -либо важное хранилище. Автоматически создается тестовым набором, если не существует по умолчанию: api-sandbox |
OCTOKIT_TEST_GITHUB_ORGANIZATION | Тестовая организация. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_LOGIN | Github Enterprise Имя входа в систему. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_TOKEN | GitHub Enterprise Token. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_PASSWORD | GitHub Enterprise Management Console пароль. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_ENDPOINT | GitHub Enterprise HostName. |
OCTOKIT_TEST_GITHUB_ENTERPRISE_MANAGEMENT_CONSOLE_ENDPOINT | Конечная точка управления GitHub Enterprise. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_ENDPOINT | GitHub Enterprise Server MAGE MANE ENDPOINT. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_USERNAME | GitHub Enterprise Server GHE управляет именем пользователя. |
OCTOKIT_TEST_GITHUB_MANAGE_GHES_PASSWORD | GitHub Enterprise Server MAGE MANE. |
OCTOKIT_TEST_GITHUB_INTEGRATION | Интеграция GitHub, принадлежащая вашей тестовой организации. |
OCTOKIT_TEST_GITHUB_INTEGRATION_INSTALLATION | Установка интеграции GitHub, указанной выше. |
OCTOKIT_TEST_INTEGRATION_PEM_KEY | Файл пути к закрытому ключ, сгенерированной из вашей интеграции. |
Поскольку мы периодически обновляем наши кассеты, пожалуйста, помните о некоторых моментах при написании новых спецификаций.
Эта библиотека направлена на поддержку и проверяется на следующих реализациях Ruby:
Если что -то не работает в одной из этих версий Ruby, это ошибка.
Эта библиотека может непреднамеренно работать (или, кажется, работает) над другими реализациями Ruby, но поддержка будет предоставлена только для версий, перечисленных выше.
Если вы хотите, чтобы эта библиотека поддержала другую версию Ruby, вы можете добровольно стать сопровождающим. Будучи сопровождающим влечет за собой убедиться, что все тесты работают и передают эту реализацию. Когда что -то нарушает вашу реализацию, вы будете нести ответственность за своевременное предоставление патчей. Если критические проблемы для конкретной реализации существуют во время крупного выпуска, поддержка этой версии Ruby может быть отброшена.
Эта библиотека направлена на то, чтобы придерживаться семантических версий 2.0.0. Нарушения этой схемы следует сообщать как ошибки. В частности, если выпускается небольшая версия или патч, которая ломается назад, эта версия должна немедленно вырвать, и/или новая версия должна быть немедленно выпущена, которая восстанавливает совместимость. Разрыв изменения в публичном API будет введена только с новыми крупными версиями. В результате этой политики вы можете (и должны) указать зависимость от этого драгоценного камня, используя ограничение пессимистической версии с двумя цифрами точности. Например:
spec.add_dependency 'octokit', '~> 3.0'
Изменения, внесенные между версиями, можно увидеть на странице «Выпуск проектов».
В большинстве случаев было бы лучше использовать WebHooks, но иногда WebHooks не предоставляют всю необходимую информацию. В тех случаях, когда можно было бы опросить на прогрессе или повторно запроса о сбое, мы разработали Octopoller. 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Это полезно при выполнении запросов на длительный прогресс работы (например, запрашивая прогресс импорта источника).
Copyright (C) 2009-2014 Wynn Netherland, Adam Stacoviak, Erik Michaels-Ober
Настоящим дается разрешение, бесплатно, любому лицу, получающему копию этого программного обеспечения и связанные с ними файлы документации («Программное обеспечение»), чтобы иметь дело в программном обеспечении без ограничений, включая, без ограничения, права на использование, копирование, изменение, объединение, публикацию, распределение, сублиценность и/или продавать копии программного обеспечения и разрешения лиц, на которые программное обеспечение подходит для того, чтобы поступить так, чтобы поступить на следующие условия: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: к следующим условиям: на следующие условия: к следующим условиям: на следующие условия: на следующие условия.
Вышеуказанное уведомление об авторском праве и это уведомление о разрешении должно быть включено во все копии или существенные части программного обеспечения.
Программное обеспечение предоставляется «как есть», без гарантии любого рода, явного или подразумеваемого, включая, помимо прочего, гарантии товарной пригодности, пригодности для определенной цели и несоответствия. Ни в коем случае авторы или владельцы авторских прав не будут нести ответственность за любые претензии, убытки или другую ответственность, будь то в действии контракта, деликт или иным образом, возникающие из или в связи с программным обеспечением или использованием или другими сделками в программном обеспечении.
