Go to Qiita Advent Calendar 2024 Top
LoginSignup
159
125

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

@syossan27

GithubAPIについて色々とまとめてみた

Posted at

GithubにはAPIがあり、これを使えばGithub上での色々な操作が可能になります。

2016/01/28現在、GithubAPIのVersionはv3であり、これを基にまとめていきます。

GithubAPIを使えば何が出来るの？

さて、APIAPIと言っておりますが実際にGithubAPIを使えば何が出来るのでしょうか？
ザッと出来ることを一部以下に書き出してみます。

  • NotificationsやFeedsの取得
  • Gistの生成・更新・取得・削除
  • Issuesの生成・更新・取得・削除
  • Organizationsの一覧やメンバーの取得
  • Pull Requestの生成・更新・取得・削除
  • Repositoryの生成・更新・取得・削除

などなど。
これはほんの一部なのですが、大方このようなことはAPIを使うことで実現できます。

どうやったらGithubAPIを使えるの？

一部のAPIは何も考慮しなくとも特定のURLにアクセスすることで結果を取得できます。

e.g.
curl -i https://api.github.com/users/defunkt

HTTP/1.1 200 OK
Server: GitHub.com
Date: Sun, 11 Nov 2012 18:43:28 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1352660008
X-GitHub-Media-Type: github.v3
Vary: Accept
Cache-Control: public, max-age=60, s-maxage=60
X-Content-Type-Options: nosniff
Content-Length: 692
Last-Modified: Tue, 30 Oct 2012 18:58:42 GMT

{
  "login": "defunkt",
  "id": 2,
  "url": "https://api.github.com/users/defunkt",
  "html_url": "https://github.com/defunkt",
  ...
}

しかし、このままでは以下の制限を受けることになります。

  • API制限として１時間に60回しかAPIを実行できない
  • 一部のAPIしか使用できない

なので、APIをフルに使えるように 認証 を行います。

認証って？

APIをフルに使うために認証が必要と先ほど説明しましたが、認証方法には３つの方法があります。

基本認証

curl -u "username" https://api.github.com
Enter host password for user 'username':

OAuth2認証（ヘッダー送信ver）

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

OAuth2認証（パラメータ送信ver）

curl https://api.github.com/?access_token=OAUTH-TOKEN

基本的にはこの３つのどれかを用いてAPIを実行することになります。
ただし、Githubとしては基本認証よりもOAuth2認証を勧めています。

参考：https://developer.github.com/v3/auth/

認証した場合のAPI制限は以下のように緩和されます。

  • １時間に5000回、APIを実行できる
  • 全てのAPIが実行できるようになる

ただし、OAuth2認証の場合はscopeの設定によっては実行できないAPIがあります。（scopeについては後ほど説明）

OAuth2認証はどうやって認証させるの？

ここからはOAuth2認証を使ったAPIの実行を説明していきます。

まずは、OAuth2認証の認証方法ですが以下の３種類があります。

  • Webアプリケーションを使った認証
  • Webアプリケーションを使わない認証
  • Personalアクセストークンを使った認証

Webアプリケーションを使った認証

この認証方法は、Githubアカウントを使ったログインでよく見かけているかもしれません。

スクリーンショット_2016-01-28_12_06_53.png

この画面のように、ブラウザ上で認証させる方式ですね。

認証は以下の流れで行われます。
別途、認証用のGithubアプリケーション作成と、認証後のコールバック処理用のサーバが必要になりますのでご注意ください。

  • 認証用URLにアクセスさせる
  • 「Authorize application」を押下してもらう
  • 指定したコールバックURLに各種パラメータが返ってくる
  • パラメータ内のcodeを使いアクセストークンを取得する

これ以後は取得したアクセストークンを用いて、APIを実行する形になります。

この認証方法については@ngs氏のこちらの記事に詳しく書かれています。
GitHub API v3 でリポジトリを作成して、ファイルをコミットする

Webアプリケーションを使わない認証

先ほどの認証とは逆にWebアプリケーションを使わない認証方法もあります。

こちらはとても簡潔でパラメータとともにcurlでPOSTすればいいだけです。
認証用のGithubアプリケーションの作成も必須ではありません。

e.g.
curl -u syossan27 -X POST -d '{"note":"test"}' https://api.github.com/authorizations
パラメータ名 型 説明
scopes array 認証に伴うGithub操作権限の付与設定
note string 必須パラメータ：この認証がどういった理由で行われるかの説明。アプリケーションと紐付けない場合は、ユニークであることが条件
note_url string 別途詳しいnoteが書かれている場合のURL
client_id string 紐付けるGithubアプリケーションのクライアントID
client_secret string 紐付けるGithubアプリケーションのクライアントシークレット
fingerprint string 一人のユーザに対して複数のトークンを生成したい場合に、それぞれのトークンを区別するために使われる値

Githubアプリケーションやサーバの準備無しに使うことが出来るため便利ではあるが、ユーザからは非常に怪しい認証に見えてしまう（ユーザ名とパスワードを入力するので）ため、はWebアプリケーションを使った認証の方がメジャーに使われている。

またユーザが二段階認証を使用している場合、とても面倒な方法を取らないといけないため、そういった意味でもWebアプリケーションを使った認証をGithubは勧めています。

参考：https://developer.github.com/v3/auth/#working-with-two-factor-authentication

Personalアクセストークンを使った認証

GithubにはPersonalアクセストークンというアクセストークンを生成することができます。
OAuth認証で得られたアクセストークンとほとんど違いは無いのですが、アクセストークンを自分で管理出来るという利点と、一部のscopeでの動きが違うという注意点があります。

GithubのSettingの左メニューに Personal access tokens があり、
ここからPersonalアクセストークン画面へ飛べます。
personal1.png

割り当てる権限を設定し、 Generate Button を押下することでPersonalアクセストークンを生成することができます。
personal2.png

参考：Creating an access token for command-line use

OAuth2認証で割り当てられる権限（scope）ってどんなものがあるの？

OAuth2認証ではアプリケーションに対してユーザへの操作権限をそれぞれ割り当てる必要がある。

権限は以下のように分かれている。

権限名 説明
(何も権限を割り当てない場合) パブリック情報の読み取りのみ可能
user ユーザ情報の読み取り/書き込みが可能
この権限はuser:email・user:followを包括する
user:email ユーザのメールアドレスのみ読み取り可能
user:follow 他ユーザのフォロー、アンフォローが可能
public_repo パブリックリポジトリのコード、コミット、コラボレーター、デプロイメントの読み取り/書き込みが可能。
公開リポジトリへスターを付けることも可能に。
repo プライベートリポジトリのコード、コミット、コラボレーター、デプロイメントの読み取り/書き込みが可能。
repo_deployment パブリックリポジトリ、プライベートリポジトリのデプロイメントの操作が可能。このscopeはコードへのアクセスをさせずに、他のユーザ・サービスにデプロイメント操作権限を与えることができる。
repo:status パブリックリポジトリ、プライベートリポジトリのコミットの読み取り/書き込みが可能。このscopeはコードへのアクセスをさせずに、他のユーザ・サービスにコミット操作権限を与えることができる。
delete_repo adminであるリポジトリを削除可能。
notifications ユーザへのお知らせを取得することが可能。repoはnotifications権限も与えます。
gist Gistへの書き込みが可能
read:repo_hook パブリックリポジトリ、プライベートリポジトリのhookの読み取り/pingが可能
write:repo_hook パブリックリポジトリ、プライベートリポジトリのhookの読み取り/書き込み/pingが可能
admin:repo_hook パブリックリポジトリ、プライベートリポジトリのhookの読み取り/書き込み/削除/pingが可能
admin:org_hook Organizationのhookの読み取り/書き込み/削除/pingが可能
__注意：__OAuth2認証で発行されたアクセストークンではOAuthアプリケーションが作成したOrganizationのfookに対して操作が可能になり、Personalアクセストークンの場合はユーザが作成したOrganizationのfookに対して操作が可能になります。
read:org Organization、teams、membershipの読み取りが可能
write:org Organization、membershipの公開・非公開の操作が可能
admin:org Organization、teams、membershipの全操作が可能
read:public_key PublicKeyの読み取りが可能
write:public_key PublicKeyの読み取り/書き込みが可能
admin:public_key PublicKeyの読み取り/書き込み/削除が可能

勿論ではあるが、「あなたの全ての操作権限をこのアプリケーションに割り当てますよ」となると嫌がるユーザもいるので適切な権限の割り当てが必要になります。

関連リンク

GithubAPIリファレンス（執筆途中）

159
125
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
159
125

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?