# GitHub REST API のクイック スタート
GitHub REST API の使用を開始する方法について説明します。
## はじめに
この記事では、GitHub、`curl`、または JavaScript を使用して、GitHub CLI REST API の使用をすばやく開始する方法について説明します。 さらに詳しいガイドについては、「[REST API を使用した作業の開始](/ja/rest/guides/getting-started-with-the-rest-api)」を参照してください。
## コマンド ラインでの GitHub CLI の使用
GitHub CLI は、コマンド ラインから GitHub REST API を使用する方法として最も簡単です。
1. macOS、Windows、または Linux に GitHub CLI をインストールします。 詳細については、GitHub CLI リポジトリ内での[インストール](https://github.com/cli/cli?ref_product=cli\&ref_type=engagement\&ref_style=text#installation)を参照してください。
2. GitHub に対して認証を行うには、ターミナルから次のコマンドを実行します。
```shell
gh auth login
```
3. 認証を行う場所を選びます。
* GitHub にある GitHub.com にアクセスする場合は、**\[GitHub.com]** を選びます。
* 別のドメインにある GitHub にアクセスする場合は、**\[Other]** を選んでから、ホスト名を入力します (例: `octocorp.ghe.com`)。
4. 画面上の残りのプロンプトに従います。
GitHub CLI は、Git 操作の優先プロトコルとして HTTPS を選択すると自動的に Git 資格情報を格納し、GitHub 資格情報で Git に対して認証するかどうかを尋ねるプロンプトに対して "はい" と答えます。 これは、別の資格情報マネージャーを設定したり、SSH を使用したりすることなく、`git push`、`git pull` などの Git コマンドを使用できるので便利です。
5. GitHub CLI `api` サブコマンドを指定し、続けてパスを入力して要求を行います。 メソッドを指定するには、`--method` または `-X` フラグを使用します。 詳しくは、[GitHub CLI`api` のドキュメント](https://cli.github.com/manual/gh_api)を参照してください。
この例では、メソッド `GET` とパス `/octocat` を使用する "Get Octocat" エンドポイントに要求を行います。 このエンドポイントの完全なリファレンス ドキュメントについては、「[メタデータ用 REST API エンドポイント](/ja/rest/meta/meta#get-octocat)」を参照してください。
```shell copy
gh api /octocat --method GET
```
## GitHub CLI での GitHub Actions の使用
GitHub CLI ワークフローでは、GitHub Actions を使用することもできます。 詳しくは、「[ワークフローでの GitHub CLI の使用](/ja/actions/using-workflows/using-github-cli-in-workflows)」をご覧ください。
### アクセス トークンを使用した認証
`gh auth login` コマンドを使用するのでなく、アクセス トークンを `GH_TOKEN` という環境変数として渡します。 GitHub では、トークンを作成するのでなく組み込みの `GITHUB_TOKEN` を使用することをお勧めしています。 これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で `GITHUB_TOKEN` を実際のシークレットの名前に置き換えます。
`GITHUB_TOKEN` の詳細については、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/actions/security-guides/automatic-token-authentication)」を参照してください。 シークレットの詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
次のワークフロー例では、[\[List repository issues\]](/ja/rest/issues/issues#list-repository-issues) エンドポイントを使用し、`octocat/Spoon-Knife` リポジトリ内の issue の一覧を要求します。
```yaml copy
on:
workflow_dispatch:
jobs:
use_api:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
```
### GitHub App による認証
GitHub App を使用して認証する場合は、ワークフロー内にインストール アクセス トークンを作成します。
1. GitHub App の ID を構成変数として保存します。 以下の例で、`APP_ID` を構成変数の名前に置き換えます。 アプリ ID は、アプリの設定ページで、あるいは API を通じて確認できます。 詳しくは、「[GitHub Apps用 REST API エンドポイント](/ja/rest/apps/apps#get-an-app)」をご覧ください。 構成オプションの詳細については、「[変数に情報を格納する](/ja/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)」を参照してください。
2. アプリケーションの秘密鍵を生成してください。 作成されたファイルの内容をシークレットとして保存します。 (`-----BEGIN RSA PRIVATE KEY-----` および `-----END RSA PRIVATE KEY-----` を含め、ファイルの内容全体を保存します)。以下の例では、`APP_PEM` をシークレットの名前に置き換えます。 詳しくは、「[GitHub アプリの秘密キーの管理](/ja/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)」をご覧ください。 シークレットの詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
3. トークンを生成するステップを追加し、`GITHUB_TOKEN` ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してください。 例:
```yaml copy
on:
workflow_dispatch:
jobs:
track_pr:
runs-on: ubuntu-latest
steps:
- name: Generate token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.APP_PEM }}
- name: Use API
env:
GH_TOKEN: ${{ steps.generate-token.outputs.token }}
run: |
gh api https://api.github.com/repos/octocat/Spoon-Knife/issues
```
## Octokit.js の使用
Octokit.js を使用すれば、JavaScript スクリプト内で GitHub REST API とやりとりすることができます。 詳細については、「[REST API と JavaScript を使用したスクリプト](/ja/rest/guides/scripting-with-the-rest-api-and-javascript)」を参照してください。
1. アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザー アクセス トークンを作成します。 このトークンを使用して要求を認証するため、そのエンドポイントへのアクセスに必要なスコープまたはアクセス許可を付与する必要があります。 詳細については、「[REST API に対する認証](/ja/rest/overview/authenticating-to-the-rest-api) または [ GitHub Apps のユーザーの識別と承認](/ja/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)を参照してください。
> \[!WARNING]
> アクセス トークンは、パスワードと同様に扱います。
>
> トークンを安全な状態に保つには、ご利用のトークンをシークレットとして格納し、GitHub Actions を介してスクリプトを実行します。 詳細については、「[GitHub Actions での Octokit.js の使用](#using-octokitjs-in-github-actions)」セクションを参照してください。
ご利用のトークンを Codespaces シークレットとして格納し、スクリプトを Codespaces で実行することもできます。 詳細については、「[Codespaces の暗号化されたシークレットを管理する](/ja/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)」を参照してください。
> これらのオプションを使用できない場合は、別の CLI サービスを使用してトークンを安全に格納することを検討してください。
2. `octokit`をインストールする。 たとえば、「 `npm install octokit` 」のように入力します。
`octokit` をインストールまたは読み込むための他の方法については、[Octokit.js の README](https://github.com/octokit/octokit.js/#readme) を参照してください。
3. スクリプトで `octokit` をインポートします。 たとえば、「 `import { Octokit } from "octokit";` 」のように入力します。 その他の `octokit` のインポート方法については、[Octokit.js の README](https://github.com/octokit/octokit.js/#readme) を参照してください。
4. トークンで `Octokit` のインスタンスを作成します。`YOUR-TOKEN` はトークンに置き換えます。
```javascript copy
const octokit = new Octokit({
auth: 'YOUR-TOKEN'
});
```
5. `octokit.request` を使用して、要求を実行します。 HTTP メソッドとパスを最初の引数として送信します。 オブジェクト内のパス、クエリ、および本文のパラメーターを 2 番目の引数として指定します。 パラメーターの詳細については、「[REST API を使用した作業の開始](/ja/rest/guides/getting-started-with-the-rest-api#using-parameters)」を参照してください。
たとえば、次の要求では、HTTP メソッドは `GET`、パスは `/repos/{owner}/{repo}/issues`、パラメーターは `owner: "octocat"` と `repo: "Spoon-Knife"` です。
```javascript copy
await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "Spoon-Knife",
});
```
## GitHub Actions での Octokit.js の使用
また、GitHub Actions ワークフローで JavaScript スクリプトを実行することもできます。 詳しくは、「[GitHub Actions のワークフロー構文](/ja/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun)」をご覧ください。
### アクセス トークンを使用した認証
GitHub では、トークンを作成するのでなく組み込みの `GITHUB_TOKEN` を使用することをお勧めしています。 これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で `GITHUB_TOKEN` を実際のシークレットの名前に置き換えます。
`GITHUB_TOKEN` の詳細については、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/actions/security-guides/automatic-token-authentication)」を参照してください。 シークレットの詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
次のワークフロー例を参照してください。
1. リポジトリのコンテンツをチェックアウトする
2. Node.js を設定する
3. `octokit` をインストールする
4. `GITHUB_TOKEN` の値を、`TOKEN` と呼ばれる環境変数として格納し、`.github/actions-scripts/use-the-api.mjs` を実行する。これにより、その環境変数に `process.env.TOKEN` としてアクセスできます。
```yaml
on:
workflow_dispatch:
jobs:
use_api_via_script:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- name: Check out repo content
uses: actions/checkout@v6
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '16.17.0'
cache: npm
- name: Install dependencies
run: npm install octokit
- name: Run script
run: |
node .github/actions-scripts/use-the-api.mjs
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
ファイル パス `.github/actions-scripts/use-the-api.mjs` を含む JavaScript スクリプトの例を次に示します。
```javascript
import { Octokit } from "octokit"
const octokit = new Octokit({
auth: process.env.TOKEN
});
try {
const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "octocat",
repo: "Spoon-Knife",
});
const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})
console.log(titleAndAuthor)
} catch (error) {
console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}
```
### GitHub App による認証
GitHub App を使用して認証する場合は、ワークフロー内にインストール アクセス トークンを作成します。
1. GitHub App の ID を構成変数として保存します。 以下の例で、`APP_ID` を構成変数の名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳しくは、「[GitHub Apps用 REST API エンドポイント](/ja/rest/apps/apps#get-an-app)」をご覧ください。 構成オプションの詳細については、「[変数に情報を格納する](/ja/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)」を参照してください。
2. アプリケーションの秘密鍵を生成してください。 作成されたファイルの内容をシークレットとして保存します。 (`-----BEGIN RSA PRIVATE KEY-----` および `-----END RSA PRIVATE KEY-----` を含め、ファイルの内容全体を保存します)。以下の例では、`APP_PEM` をシークレットの名前に置き換えます。 詳しくは、「[GitHub アプリの秘密キーの管理](/ja/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)」をご覧ください。 シークレットの詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
3. トークンを生成するステップを追加し、`GITHUB_TOKEN` ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してください。 次に例を示します。
```yaml
on:
workflow_dispatch:
jobs:
use_api_via_script:
runs-on: ubuntu-latest
steps:
- name: Check out repo content
uses: actions/checkout@v6
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '16.17.0'
cache: npm
- name: Install dependencies
run: npm install octokit
- name: Generate token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.APP_PEM }}
- name: Run script
run: |
node .github/actions-scripts/use-the-api.mjs
env:
TOKEN: ${{ steps.generate-token.outputs.token }}
```
## コマンド ラインで `curl` を使用する
> \[!NOTE]
> コマンド ラインから API 要求を行う場合、GitHub では、GitHub CLI を使用することをお勧めします。これにより、認証と要求が簡略化されます。 GitHub CLI を使用して REST API の使用を開始する方法について詳しくは、この記事の GitHub CLI バージョンを参照してください。
1. `curl` がまだコンピューターにインストールされていない場合は、インストールします。
`curl` がインストールされているかどうかを確認するには、コマンド ラインで `curl --version` を実行します。 出力が `curl` のバージョンに関する情報であれば、`curl` がインストールされているということです。
`command not found: curl` のようなメッセージが表示された場合は、`curl` をダウンロードしてインストールする必要があります。 詳しくは、[curl プロジェクトのダウンロードに関するページ](https://curl.se/download.html)を参照してください。
2. アクセス トークンを作成します。 たとえば、personal access token または GitHub App のユーザー アクセス トークンを作成します。 このトークンを使用して要求を認証するため、エンドポイントへのアクセスに必要なスコープまたはアクセス許可を付与する必要があります。 詳しくは、「[REST API に対する認証](/ja/rest/overview/authenticating-to-the-rest-api)」をご覧ください。
> \[!WARNING]
> アクセス トークンは、パスワードと同様に扱います。
>
> トークンを安全な状態に保つには、トークンを Codespaces シークレットとして格納し、Codespaces を介してコマンド ラインを使用します。 詳細については、「[Codespaces の暗号化されたシークレットを管理する](/ja/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)」を参照してください。
> `curl` ではなく GitHub CLI を使用することもできます。 認証は GitHub CLI によって自動的に処理されます。 詳しくは、このページの GitHub CLI バージョンを参照してください。
>
> これらのオプションを使用できない場合は、別の CLI サービスを使用してトークンを安全に格納することを検討してください。
3. `curl` コマンドを使用して要求を行います。
`Authorization` ヘッダーにトークンを渡してください。
`YOUR-TOKEN` をトークンに置き換えます。
```shell copy
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"
```
> \[!NOTE]
> ほとんどの場合は、`Authorization: Bearer` または `Authorization: token` を使用してトークンを渡すことができます。 ただし、JSON Web トークン (JWT) を渡す場合は、`Authorization: Bearer` を使用する必要があります。
## GitHub Actions での `curl` コマンドの使用
GitHub Actions ワークフローでも `curl` コマンドを使用できます。
### アクセス トークンを使用した認証
GitHub では、トークンを作成するのでなく組み込みの `GITHUB_TOKEN` を使用することをお勧めしています。 これができない場合は、ご利用のトークンをシークレットとして格納し、次の例で `GITHUB_TOKEN` を実際のシークレットの名前に置き換えます。
`GITHUB_TOKEN` の詳細については、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/actions/security-guides/automatic-token-authentication)」を参照してください。 シークレットの詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
```yaml copy
on:
workflow_dispatch:
jobs:
use_api:
runs-on: ubuntu-latest
permissions:
issues: read
steps:
- env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $GH_TOKEN"
```
### GitHub App による認証
GitHub App を使用して認証する場合は、ワークフロー内にインストール アクセス トークンを作成します。
1. GitHub App の ID を構成変数として保存します。 以下の例で、`APP_ID` を構成変数の名前に置き換えます。 アプリケーションIDは、アプリケーションの設定ページで、あるいはアプリケーションのAPIを通じて確認できます。 詳しくは、「[GitHub Apps用 REST API エンドポイント](/ja/rest/apps/apps#get-an-app)」をご覧ください。 構成オプションの詳細については、「[変数に情報を格納する](/ja/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)」を参照してください。
2. アプリケーションの秘密鍵を生成してください。 作成されたファイルの内容をシークレットとして保存します。 (`-----BEGIN RSA PRIVATE KEY-----` および `-----END RSA PRIVATE KEY-----` を含め、ファイルの内容全体を保存します)。以下の例では、`APP_PEM` をシークレットの名前に置き換えます。 詳しくは、「[GitHub アプリの秘密キーの管理](/ja/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)」をご覧ください。 シークレットの保管の詳細については、「[GitHub Actions でのシークレットの使用](/ja/actions/security-guides/encrypted-secrets)」を参照してください。
3. トークンを生成するステップを追加し、`GITHUB_TOKEN` ではなくそのトークンを使用します。 このトークンは 60 分後に期限切れになるので注意してください。 例:
```yaml copy
on:
workflow_dispatch:
jobs:
use_api:
runs-on: ubuntu-latest
steps:
- name: Generate token
id: generate-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ vars.APP_ID }}
private-key: ${{ secrets.APP_PEM }}
- name: Use API
env:
GH_TOKEN: ${{ steps.generate-token.outputs.token }}
run: |
curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer $GH_TOKEN"
```
## 次のステップ
詳しいガイドについては、「[REST API の概要](/ja/rest/guides/getting-started-with-the-rest-api)」を参照してください。