Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2023-01-18. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい

REST API を使用した作業の開始

GitHub REST API の使用方法について学習します。

GitHub REST API について

この記事では、GitHub CLI、JavaScript、または cURL を使う GitHub REST API の使用方法について説明します。 クイックスタート ガイドについては、「GitHub REST API のクイックスタート」を参照してく� さい。

REST API への要求を行うときは、HTTP メソッドとパスを指定します。 さらに、要求ヘッダーとパス、クエリ、または本文のパラメーターを指定することもできます。 API では、応答状態コードと応答ヘッダー、また� �合によっては応答本文が返されます。

REST API リファレンス ドキュメントでは、すべての操作の HTTP メソッド、パス、およびパラメーターについて説明します。 また、各操作の要求と応答の例も表示されます。 詳しくは、REST のリファレンス ドキュメントをご覧く� さい。

GitHub の API について詳しくは、「GitHub の API について」を参照してく� さい。

要求を行う

要求を行うには、まず HTTP メソッドと、使用する操作のパスを見つけます。 たとえば、"Octocat の取得" 操作では、GET メソッドと /octocat パスが使用されます。 この操作の完全なリファレンス ドキュメントについては、「Octocat の取得」を参照してく� さい。

: GitHub CLI の例のコマンドを使用するには、GitHub CLI をインストールする必要があります。 インストールの手� �については、GitHub CLI リポジトリを参照してく� さい。

ま�  GitHub CLI に対して認証されていない� �合は、要求を行う前に gh auth login サブコマンドを使用して認証する必要があります。 詳しくは、「認証」を参照してく� さい。

GitHub CLI を使用して要求を行うには、パスと共に api サブコマンドを使用します。 メソッドを指定するには、--method または -X フラグを使用します。

gh api /octocat --method GET

認証、パラメーターの送信、応答の使用方法について学習する� �合は、引き続きお読みく� さい。

認証

多くの操作では、認証が必要であるか、認証されている� �合は追� 情� �が返されます。 また、認証されると、1 時間あたりにさらに多くの要求を行うことができます。

一部の REST API 操作には認証なしでアクセスできますが、api サブコマンドを使用するには、GitHub CLI に対して認証を行う必要があります。

トークンについて

トークンを追� することで、要求を認証できます。

個人用に GitHub REST API を使用する� �合は、personal access tokenを作成できます。 この記事で使用する REST API 操作には、personal access tokens。 その他の操作には、異なるスコープ。 personal access tokenの作成について詳しくは、「personal access tokenの作成」をご覧く� さい。

Organization または他のユーザーの代わりに API を使用する� �合、GitHub では、GitHub App の使用が推奨されます。 操作が GitHub Apps で使用できる� �合、その操作の REST リファレンス ドキュメントには "GitHub Apps で動作する" と示されます。 この記事で使用される REST API 操作には、GitHub Apps の issues の読み取りおよび書き込みアクセス許可が必要です。 その他の操作では、異なるアクセス許可が必要な� �合があります。 詳しくは、「GitHub App を作成する」、「GitHub Apps による認証」、「GitHub アプリのユーザーを特定および認可する」を参照してく� さい。

GitHub Actions ワークフローで API を使用する� �合、GitHub では、トークンを作成するのではなく、組み込み GITHUB_TOKEN で認証することが推奨されます。 permissions キーを使用して、GITHUB_TOKEN へのアクセス許可を付与できます。 詳しくは、「自動トークン認証」を参照してく� さい。

認証の例

GitHub CLI では、アクセス トークンを事前に作成する必要はありません。 auth login サブコマンドを使用して、GitHub CLI に対する認証を行います。

gh auth login

--scopes フラグを使用して、必要なスコープを指定できます。 作成したトークンで認証する� �合は、--with-token フラグを使用できます。 詳しくは、GitHub CLI auth login ドキュメントを参照してく� さい。

GitHub Actions の認証例

run キーワードを使用して、GitHub Actions ワークフローで GitHub CLI コマンドを実行することもできます。 詳細については、「GitHub Actions のワークフロー構文」を参照してく� さい。

gh auth login コマンドを使用するのでなく、トークンを GH_TOKEN という環境変数として渡します。 GitHub では、トークンを作成するのではなく、組み込みの GITHUB_TOKEN で認証することが推奨されます。 これができない� �合は、ご利用のトークンをシークレットとして� �納し、次の例で GITHUB_TOKEN を自分のシークレットの名前に置き換えます。 GITHUB_TOKEN について詳しくは、「自動トークン認証」を参照してく� さい。 シークレットについて詳しくは、「暗号化されたシークレット」を参照してく� さい。

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /octocat

ヘッダーの使用

ほとんどの操作では、値が application/vnd.github+jsonAccept ヘッダーを渡す必要があることを指定します。 他の操作では、別の Accept ヘッダーまたは追� のヘッダーを送信する必要があることを指定する� �合があります。

GitHub CLI でヘッダーを送信するには、--header または -H フラグを使用し、その後にヘッダーを key: value 形式で指定します。

gh api --header 'Accept: application/vnd.github+json' --method GET /octocat

パス パラメーターの使用

パス パラメーターでは操作パスを変更します。 たとえば、"リポジトリの issue の一覧表示" パスは /repos/{owner}/{repo}/issues となります。 中かっこ {} は、指定する必要があるパス パラメーターを示します。 この� �合は、リポジトリの所有者と名前を指定する必要があります。 この操作のリファレンス ドキュメントについては、「リポジトリの issue の一覧表示」を参照してく� さい。

注: このコマンドを your GitHub Enterprise Server instanceで動作させるには、octocat/Spoon-Knife を、your GitHub Enterprise Server instanceによって所有されているリポジトリに置き換えます。 それ以外の� �合は、gh auth login コマンドを再実行して、your GitHub Enterprise Server instanceではなく GitHub.com に対して認証を行います。

octocat/Spoon-Knife リポジトリから issue を取得するには、{owner}octocatに、{repo}Spoon-Knife に置き換えます。

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues

この操作では、issue のリストと各 issue に関するデータが返されます。 応答の使用について詳しくは、「応答の使用」セクションを参照してく� さい。

クエリ パラメーターの使用

クエリ パラメーターを使用すると、要求に対して返されるデータを制御できます。 たとえば、クエリ パラメーターを使用すると、応答のページ分割時に返される� �目の数を指定できます。

既定では、"リポジトリの issue の一覧表示" 操作で 30 個の issue が返され、作成日の降� �で並べ替えられます。 per_page パラメーターを使用すると、30 個ではなく 2 個の issue を返すことができます。 sort パラメーターを使用すると、作成日ではなく、最終更新日で issue を並べ替えることができます。 direction パラメーターを使用すると、降� �ではなく昇� �で結果を並べ替えることができます。

GitHub CLI の� �合は、-F フラグを使用して、数値、ブール値、または null 値のパラメーターを渡します。 文字列パラメーターを渡すには、-f を使用します。

: GitHub CLI では現在、配列のパラメーターは受け入れられていません。 詳しくは、こちらの issue を参照してく� さい。

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc

この操作では、issue のリストと各 issue に関するデータが返されます。 応答の使用について詳しくは、「応答の使用」セクションを参照してく� さい。

本文パラメーターの使用

本文パラメーターを使用すると、API に追� のデータを渡すことができます。 たとえば、"issue の作成" 操作では、新しい issue のタイトルを指定する必要があります。 また、issue 本文に配置するテキストなど、他の情� �を指定することもできます。 この操作の完全なリファレンス ドキュメントについては、「issue の作成」を参照してく� さい。

"issue の作成" 操作では、上記の例の "リポジトリの issue の一覧表示" 操作と同じパスが使用されますが、GET メソッドではなく POST メソッドが使用されます。

GitHub CLI の� �合は、-F フラグを使用して、数値、ブール値、または null 値のパラメーターを渡します。 文字列パラメーターを渡すには、-f を使用します。

: GitHub CLI では現在、配列のパラメーターは受け入れられていません。 詳しくは、こちらの issue を参照してく� さい。

gh api --header 'Accept: application/vnd.github+json' --method POST /repos/octocat/Spoon-Knife/issues -f title="Created with the REST API" -f body="This is a test issue created by the REST API"

この操作によって issue が作成され、新しい issue に関するデータが返されます。 応答で、issue の html_url を見つけ、ブラウザーでその issue に移動します。 応答の使用について詳しくは、「応答の使用」セクションを参照してく� さい。

応答の使用

応答コードとヘッダーについて

すべての要求で、応答の成功を示す HTTP 状態コードが返されます。 応答コードについて詳しくは、MDN HTTP 応答状態コードに関するドキュメントを参照してく� さい。

さらに、応答には、応答の詳細を示すヘッダーが含まれます。 X- または x- で始まるものは、GitHub のカスタ�  ヘッダーです。 たとえば、x-ratelimit-remainingx-ratelimit-reset ヘッダーは、一定期間に行うことができる要求の数を示します。

状態コードとヘッダーを表示するには、要求を送信するときに --include または --i フラグを使用します。

たとえば、次の要求があります。

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 --include

次のような応答コードとヘッダーが返されます。

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: ; rel="next", ; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, X-GitHub-OTP, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

この例では、応答コードは 200 で、要求が成功したことを示します。

応答本文について

多くの操作で応答本文が返されます。 特に指定しない限り、応答本文は JSON 形式となります。 たとえば、この要求では、各 issue に関するデータと共に issue のリストが返されます。

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2

必要な情� �を指定する GraphQL API とは異なり、REST API では通常、必要以上の情� �が返されます。 必要に応じて、応答を解析して特定の情� �を引き出すことができます。

たとえば、> を使用して、応答をファイルにリダイレクトできます。

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 > data.json

その後、jq を使用して、各 issue のタイトルと作成者 ID を取得できます。

jq '.[] | {title: .title, authorID: .user.id}' data.json

前の 2 つのコマンドでは次のようなものが返されます。

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

jq について詳しくは、jq のドキュメントjq play を参照してく� さい。

次の手� �

この記事では、リポジトリの issue を一覧表示して作成する方法について説明しました。 さらに練習する� �合は、issue にコメントを付けたり、issue のタイトルを編集したり、issue を閉じてみたりしてく� さい。 これらの操作について詳しくは、「issue コメントの作成」と「issue の更新」を参照してく� さい。

使用できる操作について詳しくは、REST リファレンス ドキュメントを参照してく� さい。