# REST API を使用した作業の開始 GitHub REST API の使用方法について説明します。 ## はじめにこの記事では、GitHub、GitHub CLI、または JavaScript で `curl` REST API を使用する方法について説明します。クイックスタートガイドについては、「[GitHub REST API のクイックスタート](/ja/enterprise-server@3.22/rest/quickstart)」を参照してください。

## REST API への要求についてこのセクションでは、API 要求を構成する要素について説明します。 * [HTTP メソッド](#http-method) * [Path](#path) * [Headers](#headers) * [メディアの種類](#media-types) * [認証](#authentication) * [パラメーター](#parameters) REST API に対するすべての要求には、HTTP メソッドとパスが含まれます。 REST API エンドポイントによっては、要求ヘッダー、認証情報、クエリパラメーター、または本文パラメーターも指定する必要があります。 REST API リファレンスドキュメントでは、すべてのエンドポイントの HTTP メソッド、パス、およびパラメーターについて説明します。また、各エンドポイントの要求と応答の例も表示されます。詳しくは、[REST のリファレンスドキュメント](/ja/enterprise-server@3.22/rest)をご覧ください。 ### HTTP メソッドエンドポイントの HTTP メソッドは、特定のリソースに対して実行するアクションの種類を定義します。一般的な HTTP メソッドには `GET`、`POST`、`DELETE`、`PATCH` があります。 REST API リファレンスドキュメントには、すべてのエンドポイントの HTTP メソッドが記載されています。たとえば、[「リポジトリの issue の一覧表示」エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#list-repository-issues)の HTTP メソッドは `GET` です。可能であれば、 GitHub REST API は、各アクションに適切な HTTP メソッドを使用するように努めています。 * `GET`: リソースを取得するために使用します。 * `POST`: リソースを作成するために使用します。 * `PATCH`: リソースのプロパティを更新するために使用されます。 * `PUT`: リソースまたはリソースのコレクションを置き換えるために使用します。 * `DELETE`: リソースを削除するために使用します。 ### パス各エンドポイントにはパスがあります。 REST API リファレンスドキュメントには、すべてのエンドポイントのパスが記載されています。たとえば、["リポジトリの問題の一覧" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#list-repository-issues)は `/repos/{owner}/{repo}/issues` となります。パスの中かっこ `{}` は、指定する必要があるパスパラメーターを示します。パスパラメーターはエンドポイントパスを変更し、要求に必要です。たとえば、["リポジトリの issues の一覧表示" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#list-repository-issues)のパスパラメーターは `{owner}` と `{repo}` になります。 API 要求でこのパスを使用するには、`{repo}` を問題の一覧を要求するリポジトリの名前に置き換え、`{owner}` をリポジトリを所有するアカウントの名前に置き換えます。 ### ヘッダーヘッダーは、要求と必要な応答に関する追加情報を提供します。 GitHub REST API への要求で使用できるヘッダーの例を次に示します。ヘッダーを使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。 #### `Accept` ほとんどのGitHub REST API エンドポイントでは、値が `Accept` の `application/vnd.github+json` ヘッダーを渡す必要があることを指定しています。 `Accept` ヘッダーの値はメディアの種類です。メディアの種類の詳細については、「[メディアの種類](#media-types)」を参照してください。 #### `X-GitHub-Api-Version` このヘッダーを使用して、要求に使用する REST API のバージョンを指定する必要があります。詳しくは、「[API のバージョン](/ja/enterprise-server@3.22/rest/about-the-rest-api/api-versions)」をご覧ください。 ### メディアの種類 1 つ以上のメディアの種類を指定するには、それらを要求の`Accept` ヘッダーに追加します。 `Accept` ヘッダーの詳細については、「[`Accept`](#accept)」を参照してください。メディアの種類は、API から使用するデータの形式を指定します。メディアの種類はリソースに固有であるため、個別に変更したり、他のリソースではサポートされていない形式をサポートしたりできます。各 GitHub REST API エンドポイントのドキュメントでは、サポートされているメディアの種類について説明します。詳細については、「[GitHub REST API のドキュメント](/ja/enterprise-server@3.22/rest)」を参照してください。 GitHub REST API でサポートされる最も一般的なメディアの種類は、`application/vnd.github+json`と`application/json`です。一部のエンドポイントで使用できるカスタムメディアの種類があります。たとえば、[コミット](/ja/enterprise-server@3.22/rest/commits/commits#get-a-commit)と [pull request](/ja/enterprise-server@3.22/rest/pulls/pulls) を管理する REST API では、`diff`、`patch`、`sha` というメディアの種類がサポートされます。 `full`、`raw`、`text`、`html` というメディアの種類は、他のエンドポイントで使用されます。 GitHubのすべてのカスタムメディアの種類は次のようになります。`application/vnd.github.PARAM+json`。ここで、`PARAM`はメディアの種類の名前です。たとえば、`raw` メディアの種類を指定するには、`application/vnd.github.raw+json` を使用します。メディアの種類を使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。 ### 認証多くのエンドポイント操作では、認証が必要であるか、認証されている場合は追加情報が返されます。さらに、認証されている場合は 1 時間あたりの要求を増やすことができます。

要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。トークンを取得するには、いくつかの方法があります。personal access tokenを作成したり、GitHub Appでトークンを生成したり、`GITHUB_TOKEN`ワークフローで組み込みのGitHub Actionsを使用したりできます。詳しくは、「[REST API に対する認証](/ja/enterprise-server@3.22/rest/authentication/authenticating-to-the-rest-api)」をご覧ください。認証トークンを使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。 > \[!NOTE] > トークンを作成しない場合は、 GitHub CLIを使用できます。 > GitHub CLI は認証を行い、アカウントのセキュリティを維持するのに役立ちます。詳細については、[このページのGitHub CLIバージョンを](/ja/enterprise-server@3.22/rest/using-the-rest-api/getting-started-with-the-rest-api?tool=cli)参照してください。 > \[!WARNING] > アクセストークンは、パスワードや他の機密性の高い資格情報を扱うのと同じ方法で扱ってください。詳しくは、「[API 資格情報をセキュリティで保護する](/ja/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure)」をご覧ください。

一部の REST API エンドポイントには認証なしでアクセスできますが、 GitHub CLI は、 `api` サブコマンドを使用して API 要求を行う前に認証する必要があります。 `auth login`に対する認証には、GitHub サブコマンドを使用します。詳細については、「[要求の作成](#making-a-request)」を参照してください。

要求を認証するには、必要なスコープまたはアクセス許可を持つ認証トークンを提供する必要があります。トークンを取得するには、いくつかの方法があります。personal access tokenを作成したり、GitHub Appでトークンを生成したり、`GITHUB_TOKEN`ワークフローで組み込みのGitHub Actionsを使用したりできます。詳しくは、「[REST API に対する認証](/ja/enterprise-server@3.22/rest/authentication/authenticating-to-the-rest-api)」をご覧ください。認証トークンを使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。 > \[!WARNING] > アクセストークンは、パスワードや他の機密性の高い資格情報を扱うのと同じ方法で扱ってください。詳しくは、「[API 資格情報をセキュリティで保護する](/ja/enterprise-server@3.22/rest/authentication/keeping-your-api-credentials-secure)」をご覧ください。

### パラメーター多くの API メソッドでは、要求のパラメーターに追加情報を送信する必要があります。パラメーターには、パスパラメーター、本文パラメーター、クエリパラメーターなど、いくつかの種類があります。 #### パスパラメーターパスパラメーターではエンドポイントパスを変更します。これらは要求に必須です。詳細については、「[Path](#path)」をご覧ください。 #### ボディパラメータ本文パラメーターを使用すると、API に追加のデータを渡すことができます。これらのパラメーターは、エンドポイントに応じて省略可能または必須にすることができます。たとえば、本文パラメーターを使用すると、新しい問題を作成するときに問題のタイトルを指定したり、機能を有効または無効にするときに特定の設定を指定したりできます。各 GitHub REST API エンドポイントのドキュメントでは、それがサポートする本文パラメーターについて説明します。詳細については、「[GitHub REST API のドキュメント](/ja/enterprise-server@3.22/rest)」を参照してください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) では、要求で新しい issue のタイトルを指定する必要があります。また、必要に応じて issue 本文に入力するテキスト、新しい issue に割り当てるユーザー、新しい issue に適用するラベルなど、その他の情報を指定することもできます。本文パラメーターを使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。ボディパラメーターを渡すには、リクエストを認証する必要があります。詳細については、[認証](#authentication)を参照してください。 #### クエリパラメータークエリパラメーターを使用すると、要求に対して返されるデータを制御できます。これらのパラメーターは通常省略可能です。各 GitHub REST API エンドポイントのドキュメントでは、サポートされているクエリパラメーターについて説明します。詳細については、「[GitHub REST API のドキュメント](/ja/enterprise-server@3.22/rest)」を参照してください。たとえば、["パブリックイベントの一覧表示" エンドポイント](/ja/enterprise-server@3.22/rest/activity/events#list-public-events) では、既定で 30 個の issue が返されます。 `per_page` クエリパラメーターを使用すると、30 個ではなく 2 個の issue を返すことができます。 `page` クエリパラメーターを使用して、結果の最初のページのみをフェッチできます。クエリパラメーターを使用する要求の例については、「[要求の作成](#making-a-request)」を参照してください。 ## 要求を行う

このセクションでは、GitHubを使用して、GitHub CLI REST API に対して認証された要求を行う方法について説明します。 ### 1. セットアップ macOS、Windows、または Linux に GitHub CLI をインストールします。詳細については、[](https://github.com/cli/cli#installation) リポジトリへのGitHub CLIを参照してください。 ### 2. 認証 1. GitHubに対する認証を行うには、ターミナルから次のコマンドを実行します。 ```shell gh auth login ``` `--scopes` オプションを使用して、必要なスコープを指定できます。作成したトークンで認証する場合は、`--with-token` オプションを使用できます。詳細については、 [GitHub CLI`auth login` ドキュメントを参照してください](https://cli.github.com/manual/gh_auth_login)。 1. 認証を行う場所を選びます。 * GitHubでGitHub.comにアクセスする場合は、\[**GitHub.com**] を選択します。 * 別のドメイン GitHub にアクセスする場合は、\[ **その他**] を選択し、ホスト名を入力します (例: `octocorp.ghe.com`)。 2. 画面上の残りのプロンプトに従います。 GitHub CLI Git 操作の優先プロトコルとして HTTPS を選択すると、Git 資格情報が自動的に保存され、 GitHub 資格情報を使用して Git に対して認証するかどうかを確認するプロンプトに対して "はい" と答えます。これは、別の資格情報マネージャーを設定したり、SSH を使用したりすることなく、`git push`、`git pull` などの Git コマンドを使用できるので便利です。 ### 3. 要求のエンドポイントの選択 1. 要求を行うエンドポイントを選びます。 GitHubの [REST API ドキュメント](/ja/enterprise-server@3.22/rest)を調べて、GitHubとの対話に使用できるエンドポイントを検出できます。 2. エンドポイントの HTTP メソッドとパスを特定します。これらは要求と共に送信されます。詳細については、「[HTTP メソッド](#http-method)」と「[パス](#path)」を参照してください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) では、HTTP メソッド `POST` とパス `/repos/{owner}/{repo}/issues` が使用されます。 3. 必要なパスパラメーターを特定します。必要なパスパラメーターは、エンドポイントのパスの中かっこ `{}` で囲まれています。各パラメーターのプレースホルダーを目的の値に置き換えます。詳細については、「[Path](#path)」をご覧ください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) ではパス `/repos/{owner}/{repo}/issues` が使用され、パスパラメーターは `{owner}` と `{repo}` になります。 API 要求でこのパスを使用するには、`{repo}` を新しい issue を作成するリポジトリの名前に置き換え、`{owner}` をリポジトリを所有するアカウントの名前に置き換えます。 ### 4. GitHub CLI を使用して要求を行います api 要求を行うには、 GitHub CLI`api` サブコマンドを使用します。詳細については、 [GitHub CLI`api` ドキュメントを参照してください](https://cli.github.com/manual/gh_api)。要求で、次のオプションと値を指定します。 * \*\*--ホスト：\*\*GitHub プラットフォーム間で複数のアカウントに対して認証される場合は、要求を行う場所を指定します。たとえば、 `--hostname octocorp.ghe.com`と指定します。 * **--method** の後に HTTP メソッドとエンドポイントのパスが続きます。詳細については、「[HTTP メソッド](#http-method)」と「[パス](#path)」を参照してください。 * **--header**: * **`Accept`:**`Accept` ヘッダーにメディアの種類を渡します。 `Accept` ヘッダーに複数のメディアの種類を渡すには、メディアの種類をコンマ: `Accept: application/vnd.github+json,application/vnd.github.diff` で区切ります。詳細については、「[`Accept`](#accept)」と「[メディアタイプ](#media-types)」を参照してください。 * **`X-GitHub-Api-Version`:**`X-GitHub-Api-Version` ヘッダーで API バージョンを渡します。詳細については、「[`X-GitHub-Api-Version`](#x-github-api-version)を参照してください。 * **`-f`** または **`-F`** の後に、`key=value` 形式の任意の本文パラメーターまたはクエリパラメーターが続きます。この `-F` オプションを使用して、数値、ブール値、または null のパラメーターを渡します。文字列パラメーターを渡すには、`-f` オプションを使用します。一部のエンドポイントでは、配列のクエリパラメーターが使われます。クエリ文字列で配列を送信するには、配列の項目ごとに 1 回クエリパラメーターを使い、クエリパラメーター名の後に `[]` を追加します。たとえば、2 つのリポジトリ ID の配列を指定するには、`-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID` を使います。要求で本文パラメーターまたはクエリパラメーターを指定する必要がない場合は、このオプションを省略します。詳細については、「[本文パラメーター](#body-parameters)」と「[クエリパラメーター](#query-parameters)」を参照してください。例については、「[本文パラメーターを使用した要求の例](#example-request-using-body-parameters)」と「[クエリパラメーターを使用した要求の例](#example-request-using-query-parameters)」を参照してください。 * \*\*--ホスト：\*\*GitHub プラットフォーム間で複数のアカウントに対して認証される場合は、要求を行う場所を指定します。たとえば、 `--hostname octocorp.ghe.com`と指定します。 #### 要求の例次の要求例では、 ["Get Octocat" エンドポイント](/ja/enterprise-server@3.22/rest/meta/meta#get-octocat) を使用して、octocat を ASCII アートとして返します。 ```shell copy gh api --method GET /octocat \ --header 'Accept: application/vnd.github+json' \ --header "X-GitHub-Api-Version: 2022-11-28" ``` #### クエリパラメーターを使用した要求の例 ["パブリックイベントの一覧表示" エンドポイント](/ja/enterprise-server@3.22/rest/activity/events#list-public-events) では、既定で 30 個の issue が返されます。次の例では、`per_page` クエリパラメーターを使用して 30 個ではなく 2 個の issue を返し、`page` クエリパラメーターを使用して結果の最初のページのみをフェッチします。 ```shell copy gh api --method GET /events -F per_page=2 -F page=1 --header 'Accept: application/vnd.github+json' \ ``` #### 本文パラメーターを使用した要求の例次の例では、["問題の作成" エンドポイントを](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue)使用して、octocat/Spoon-Knife リポジトリa に新しい問題を作成します。 `REPO-NAME`を新しい問題を作成するリポジトリの名前に置き換え、`REPO-OWNER`をリポジトリを所有するアカウントの名前に置き換えます。応答で、問題の `html_url` を見つけて、ブラウザーで問題に移動します。 ```shell copy gh api --method POST /repos/REPO-OWNER/REPO-NAME/issues \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ -f title='Created with the REST API' \ -f body='This is a test issue created by the REST API' \ ```

このセクションでは、GitHubを使用して、`curl` REST API に対して認証された要求を行う方法について説明します。 ### 1. セットアップお使いのコンピューター上に `curl` がインストールされている必要があります。 `curl` が既にインストールされているかどうかを確認するには、コマンドラインで `curl --version` を実行します。 * 出力が `curl` のバージョンに関する情報であれば、`curl` がインストールされているということです。 * `command not found: curl` のようなメッセージが表示された場合は、`curl` がインストールされていないことを意味します。 `curl`をダウンロードしてインストールします。詳しくは、[curl のダウンロードに関するページ](https://curl.se/download.html)を参照してください。 ### 2. 要求のエンドポイントの選択 1. 要求を行うエンドポイントを選びます。 GitHubの [REST API ドキュメント](/ja/enterprise-server@3.22/rest)を調べて、GitHubとの対話に使用できるエンドポイントを検出できます。 2. エンドポイントの HTTP メソッドとパスを特定します。これらは要求と共に送信されます。詳細については、「[HTTP メソッド](#http-method)」と「[パス](#path)」を参照してください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) では、HTTP メソッド `POST` とパス `/repos/{owner}/{repo}/issues` が使用されます。 3. 必要なパスパラメーターを特定します。必要なパスパラメーターは、エンドポイントのパスの中かっこ `{}` で囲まれています。各パラメーターのプレースホルダーを目的の値に置き換えます。詳細については、「[Path](#path)」をご覧ください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) ではパス `/repos/{owner}/{repo}/issues` が使用され、パスパラメーターは `{owner}` と `{repo}` になります。 API 要求でこのパスを使用するには、`{repo}` を新しい issue を作成するリポジトリの名前に置き換え、`{owner}` をリポジトリを所有するアカウントの名前に置き換えます。 ### 3. 認証資格情報の作成要求を認証するためのアクセストークンを作成します。トークンを保存し、複数の要求に使用できます。エンドポイントにアクセスするために必要なスコープまたはアクセス許可をトークンに付与します。このトークンは要求の `Authorization` ヘッダーに含めて送信します。詳細については、[認証](#authentication)を参照してください。 ### 4. `curl` 要求を行う `curl` コマンドを使用して要求を行います。詳細については、[curl のドキュメント](https://curl.se/docs/manpage.html)を参照してください。要求で次のオプションと値を指定します。 * **`--request` または `-X`** の後に、値として HTTP メソッドが続きます。詳細については、「[HTTP メソッド](#http-method)」を参照してください。 * **`--url`** の後に、値として完全なパスが続きます。完全なパスは、GitHub REST API のベース URL (`http(s)://HOSTNAME/api/v3`) とエンドポイントのパス (`http(s)://HOSTNAME/api/v3/PATH`. など) を含む URL です。 `HOSTNAME`をお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 `PATH`をエンドポイントのパスに置き換えます。詳細については、「[Path](#path)」をご覧ください。クエリパラメーターを使用するには、パスの末尾に `?` を追加してから、クエリパラメーターの名前と値を `parameter_name=value` 形式で付加します。複数のクエリパラメーターは `&` で区切ります。クエリ文字列で配列を送信する場合は、配列の項目ごとに 1 回クエリパラメーターを使い、クエリパラメーター名の後に `[]` を追加します。たとえば、2 つのリポジトリ ID の配列を指定するには、`?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID` を使います。詳細については、「[クエリのパラメーター](#query-parameters)」を参照してください。例については、「[クエリパラメーターを使用した要求の例](#example-request-using-query-parameters-1)」を参照してください。 * **`--header` または `-H`:** * **`Accept`:**`Accept` ヘッダーにメディアの種類を渡します。 `Accept` ヘッダーに複数のメディアの種類を渡すには、たとえば、`Accept: application/vnd.github+json,application/vnd.github.diff` というように、メディアの種類をコンマで区切ります。詳細については、「[`Accept`](#accept)」と「[メディアタイプ](#media-types)」を参照してください。 * **`X-GitHub-Api-Version`:**`X-GitHub-Api-Version` ヘッダーで API バージョンを渡します。詳細については、「[`X-GitHub-Api-Version`](#x-github-api-version)を参照してください。 * **`Authorization`:**`Authorization` ヘッダーに認証トークンを渡します。ほとんどの場合は、`Authorization: Bearer` または `Authorization: token` を使用してトークンを渡すことができることにご注意ください。ただし、JSON Web トークン (JWT) を渡す場合は、`Authorization: Bearer` を使用する必要があります。詳細については、[認証](#authentication)を参照してください。 `Authorization` ヘッダーを使用する要求の例については、「[本文パラメーターを使用した要求の例](#example-request-using-body-parameters-1)」を参照してください。 * **`--data` または `-d`** の後に、JSON オブジェクト内の任意の本文パラメーターが続きます。要求で本文パラメーターを指定する必要がない場合は、このオプションを省略します。詳細については、「[本文パラメーター](#body-parameters)」を参照してください。例については、「[本文パラメーターを使用した要求の例](#example-request-using-body-parameters-1)」を参照してください。 #### 要求の例次の要求例では、 ["Get Octocat" エンドポイント](/ja/enterprise-server@3.22/rest/meta/meta#get-octocat) を使用して、octocat を ASCII アートとして返します。 ```shell copy curl --request GET \ --url "https://api.github.com/octocat" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" ``` #### クエリパラメーターを使用した要求の例 ["パブリックイベントの一覧表示" エンドポイント](/ja/enterprise-server@3.22/rest/activity/events#list-public-events) では、既定で 30 個の issue が返されます。次の例では、`per_page` クエリパラメーターを使用して 30 個ではなく 2 個の issue を返し、`page` クエリパラメーターを使用して結果の最初のページのみをフェッチします。 ```shell copy curl --request GET \ --url "http(s)://HOSTNAME/api/v3/events?per_page=2&page=1" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/events ``` #### 本文パラメーターを使用した要求の例次の例では[「イシューの作成」エンドポイントを](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue)使用して、指定されたoctocat/Spoon-Knife `HOSTNAME`をお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 `REPO-NAME`を新しい問題を作成するリポジトリの名前に置き換え、`REPO-OWNER`をリポジトリを所有するアカウントの名前に置き換えます。 `YOUR-TOKEN`は、前の手順で作成した認証トークンに置き換えます。 > \[!NOTE] > fine-grained personal access tokenを使用している場合は、`REPO-OWNER`と`REPO-NAME`を、自分が所有しているリポジトリ、または自分が所属する組織が所有するリポジトリに置き換える必要があります。お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。詳しくは、「[個人用アクセストークンを管理する](/ja/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)」をご覧ください。 ```shell copy curl \ --request POST \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues" \ --header "Accept: application/vnd.github+json" \ --header "X-GitHub-Api-Version: 2022-11-28" \ --header "Authorization: Bearer YOUR-TOKEN" \ --data '{ "title": "Created with the REST API", "body": "This is a test issue created by the REST API" }' ```

このセクションでは、JavaScript GitHubを使用して、[](https://github.com/octokit/octokit.js) REST API に要求を行う方法について説明します。さらに詳しいガイドについては、「[REST API と JavaScript を使用したスクリプト](/ja/enterprise-server@3.22/rest/guides/scripting-with-the-rest-api-and-javascript)」を参照してください。 ### 1. セットアップ次の例に示す Octokit.js ライブラリを使用するには、`octokit` をインストールする必要があります。 * `octokit`をインストールする。たとえば、「 `npm install octokit` 」のように入力します。 `octokit` をインストールまたは読み込むための他の方法については、[Octokit.js の README](https://github.com/octokit/octokit.js/#readme) を参照してください。 ### 2. 要求のエンドポイントの選択 1. 要求を行うエンドポイントを選びます。 GitHubの [REST API ドキュメント](/ja/enterprise-server@3.22/rest)を調べて、GitHubとの対話に使用できるエンドポイントを検出できます。 2. エンドポイントの HTTP メソッドとパスを特定します。これらは要求と共に送信されます。詳細については、「[HTTP メソッド](#http-method)」と「[パス](#path)」を参照してください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) では、HTTP メソッド `POST` とパス `/repos/{owner}/{repo}/issues` が使用されます。 3. 必要なパスパラメーターを特定します。必要なパスパラメーターは、エンドポイントのパスの中かっこ `{}` で囲まれています。各パラメーターのプレースホルダーを目的の値に置き換えます。詳細については、「[Path](#path)」をご覧ください。たとえば、["issue の作成" エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#create-an-issue) ではパス `/repos/{owner}/{repo}/issues` が使用され、パスパラメーターは `{owner}` と `{repo}` になります。 API 要求でこのパスを使用するには、`{repo}` を新しい issue を作成するリポジトリの名前に置き換え、`{owner}` をリポジトリを所有するアカウントの名前に置き換えます。 ### 3. アクセストークンの作成要求を認証するためのアクセストークンを作成します。トークンを保存し、複数の要求に使用できます。エンドポイントにアクセスするために必要なスコープまたはアクセス許可をトークンに付与します。このトークンは要求の `Authorization` ヘッダーに含めて送信します。詳細については、[認証](#authentication)を参照してください。 ### 4. Octokit.js で要求を行う 1. スクリプトで `octokit` をインポートします。たとえば、「 `import { Octokit } from "octokit";` 」のように入力します。その他の `octokit` のインポート方法については、[Octokit.js の README](https://github.com/octokit/octokit.js/#readme) を参照してください。 2. トークンを使用して `Octokit` のインスタンスを作成します。ベース URL を `http(s)://HOSTNAME/api/v3` に設定します。 `HOSTNAME`をお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 `YOUR-TOKEN` を実際のトークンに置き換えます。 ```javascript copy const octokit = new Octokit({ baseUrl: "http(s)://HOSTNAME/api/v3", auth: 'YOUR-TOKEN' }); ``` 3. `octokit.request` を使用して、要求を実行します。 * HTTP メソッドとパスを`request` メソッドの最初の引数として送信します。詳細については、「[HTTP メソッド](#http-method)」と「[パス](#path)」を参照してください。 * オブジェクト内のすべてのパス、クエリ、および本文パラメーターを `request` メソッドの 2 番目の引数として指定します。詳しくは、「[パラメーター](#parameters)」をご覧ください。次の要求例では、HTTP メソッドが `POST`され、パスが `/repos/{owner}/{repo}/issues`され、パスパラメーターが `owner: "REPO-OWNER"` され、 `repo: "REPO-NAME"`され、本文パラメーターが `title: "Created with the REST API"` され、 `body: "This is a test issue created by the REST API"`されます。 `REPO-OWNER`はリポジトリを所有するアカウントの名前に置き換え、`REPO-NAME`はリポジトリの名前に置き換えます。 > \[!NOTE] > fine-grained personal access tokenを使用している場合は、`REPO-OWNER`と`REPO-NAME`を、自分が所有しているリポジトリ、または自分が所属する組織が所有するリポジトリに置き換える必要があります。お使いのトークンは、リポジトリにアクセスできる必要があり、リポジトリの issue に対する読み取りと書き込みのアクセス許可が必要です。詳しくは、「[個人用アクセストークンを管理する](/ja/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)」をご覧ください。 ```javascript copy await octokit.request("POST /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", title: "Created with the REST API", body: "This is a test issue created by the REST API", }); ``` `request` メソッドでは `Accept: application/vnd.github+json` ヘッダーが自動的に渡されます。追加のヘッダーまたは別の `Accept` ヘッダーを渡すには、2 番目の引数として渡されるオブジェクトに `headers` プロパティを追加します。 `headers` プロパティの値は、キーがヘッダー名で値がヘッダー値のオブジェクトです。たとえば、次のコードでは、値が `content-type` の `text/plain` ヘッダーと、値が `X-GitHub-Api-Version` の `2026-03-10` ヘッダーが送信されます。 ```javascript copy await octokit.request("GET /octocat", { headers: { "content-type": "text/plain", "X-GitHub-Api-Version": "2026-03-10", }, }); ```

## 応答の使用要求を行うと、API では、応答状態コードと応答ヘッダー、また場合によっては応答本文が返されます。 ### 応答コードとヘッダーについてすべての要求で、応答の成功を示す HTTP 状態コードが返されます。応答コードについて詳しくは、[MDN HTTP 応答状態コードに関するドキュメント](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)を参照してください。さらに、応答には、応答の詳細を示すヘッダーが含まれます。 `X-`または`x-`で始まるヘッダーは、GitHubカスタムです。たとえば、`x-ratelimit-remaining` と `x-ratelimit-reset` ヘッダーは、一定期間に行うことができる要求の数を示します。

状態コードとヘッダーを表示するには、要求を送信するときに `--include` または `--i` オプションを使用します。たとえば、この要求は、octocat/Spoon-Knife リポジトリで指定a の問題の一覧を取得します。 ```shell gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 --include ``` そして、次のような応答コードとヘッダーが返されます。 ```shell HTTP/2.0 200 OK Access-Control-Allow-Origin: * Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, 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, 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` で、要求が成功したことを示します。

Octokit.js で要求を行うと、`request` メソッドでは promise が返されます。要求が成功した場合、promise は、応答のHTTP 状態コード (`status`) と応答ヘッダー (`headers`) を含むオブジェクトに解決されます。エラーが発生した場合、promise は、応答のHTTP 状態コード (`status`) と応答ヘッダー (`response.headers`) を含むオブジェクトに解決されます。 `try/catch` ブロックを使用して、エラーが発生した場合にそれをキャッチできます。たとえば、次のスクリプトの要求が成功した場合、そのスクリプトでは状態コードと `x-ratelimit-remaining` ヘッダーの値がログに記録されます。要求が成功しなかった場合、スクリプトでは状態コード、`x-ratelimit-remaining` ヘッダーの値、およびエラーメッセージがログに記録されます。次の例では、`REPO-OWNER` をリポジトリを所有するアカウントの名前に置き換え、`REPO-NAME` をリポジトリの名前に置き換えます。 ```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", per_page: 2, }); console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`) } catch (error) { console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`) } ```

状態コードとヘッダーを表示するには、要求を送信するときに `--include` または `--i` オプションを使用します。たとえば、この要求は、octocat/Spoon-Knife リポジトリで指定a の問題の一覧を取得します。 ```shell curl --request GET \ --url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" \ --include ``` そして、次のような応答コードとヘッダーが返されます。 ```shell HTTP/2 200 server: GitHub.com date: Thu, 04 Aug 2022 20:07:51 GMT content-type: application/json; charset=utf-8 cache-control: public, max-age=60, s-maxage=60 vary: Accept, Accept-Encoding, Accept, X-Requested-With etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18" x-github-media-type: github.v3; format=json link: ; rel="next", ; rel="last" access-control-expose-headers: ETag, Link, Location, Retry-After, 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 access-control-allow-origin: * strict-transport-security: max-age=31536000; includeSubdomains; preload x-frame-options: deny x-content-type-options: nosniff x-xss-protection: 0 referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin content-security-policy: default-src 'none' x-ratelimit-limit: 15000 x-ratelimit-remaining: 14996 x-ratelimit-reset: 1659645535 x-ratelimit-resource: core x-ratelimit-used: 4 accept-ranges: bytes content-length: 4936 x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715 ``` この例では、応答コードは `200` で、要求が成功したことを示します。

### 応答本文について多くのエンドポイントで応答本文が返されます。特に指定しない限り、応答本文は JSON 形式となります。空白のフィールドは、省略されずに `null` として含まれます。すべてのタイムスタンプは、 ISO 8601フォーマット: `YYYY-MM-DDTHH:MM:SSZ` の UTC 時間で返されます。必要な情報を指定する GraphQL API とは異なり、REST API では通常、必要以上の情報が返されます。必要に応じて、応答を解析して特定の情報を引き出すことができます。

たとえば、`>` を使用して、応答をファイルにリダイレクトできます。次の例では、`REPO-OWNER` をリポジトリを所有するアカウントの名前に置き換え、`REPO-NAME` をリポジトリの名前に置き換えます。 ```shell copy gh api \ --header 'Accept: application/vnd.github+json' \ --method GET /repos/REPO-OWNER/REPO-NAME/issues \ -F per_page=2 > data.json ``` その後、jq を使用して、各 issue のタイトルと作成者 ID を取得できます。 ```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` 前の 2 つのコマンドでは次のようなものが返されます。 ```json { "title": "Update index.html", "authorID": 10701255 } { "title": "Edit index file", "authorID": 53709285 } ``` jq について詳しくは、[jq のドキュメント](https://stedolan.github.io/jq/)をご覧ください。

たとえば、各 issue のタイトルと作成者 ID を取得できます。次の例では、`REPO-OWNER` をリポジトリを所有するアカウントの名前に置き換え、`REPO-NAME` をリポジトリの名前に置き換えます。 ```javascript copy try { const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { owner: "REPO-OWNER", repo: "REPO-NAME", per_page: 2, }); 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}`) } ```

たとえば、`>` を使用して、応答をファイルにリダイレクトできます。次の例では、 `REPO-OWNER` をリポジトリを所有するアカウントの名前に置き換え、 `REPO-NAME` をリポジトリの名前に置き換えます。 `HOSTNAME`をお使いの GitHub Enterprise Server インスタンスの名前に置き換えます。 ```shell copy curl --request GET \ --url "http(s)://HOSTNAME/api/v3/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer YOUR-TOKEN" > data.json ``` その後、jq を使用して、各 issue のタイトルと作成者 ID を取得できます。 ```shell copy jq '.[] | {title: .title, authorID: .user.id}' data.json ``` 前の 2 つのコマンドでは次のようなものが返されます。 ```json { "title": "Update index.html", "authorID": 10701255 } { "title": "Edit index file", "authorID": 53709285 } ``` jq について詳しくは、[jq のドキュメント](https://stedolan.github.io/jq/)をご覧ください。

#### 詳細表現と概要表現応答には、個々のリソースまたはリソースの一覧のどちらをフェッチするかに応じて、リソースのすべての属性または属性のサブセットのみを含めることができます。 * 特定のリポジトリなどの\_個々のリソース\_をフェッチすると、通常、応答にはそのリソースのすべての属性が含まれます。これは、リソースの「詳細」表現です。 * 複数のリポジトリの一覧など、\_リソースの一覧\_をフェッチすると、応答には各リソースの属性のサブセットのみが含まれます。これは、リソースの「要約」表現です。承認によって、表現に含まれる詳細の内容に影響する場合があることにご注意ください。その理由は、一部の属性は API が提供する計算コストが高いため、 GitHub はそれらの属性を概要表現から除外するためです。これらの属性を取得するには、詳細な表記を取得します。ドキュメントには、各 API メソッドのレスポンス例が記載されています。レスポンス例は、そのメソッドによって返されるすべての属性を示しています。 #### ハイパーメディアすべてのリソースには、他のリソースにリンクしている 1 つ以上の `*_url` プロパティがある場合があります。これらは、適切な API クライアントが自身で URL を構築する必要がないように、明示的な URL を提供することを目的としています。 API クライアントでは、これらを使用することを強くお勧めしています。そうすることで、開発者が将来の API のアップグレードを容易に行うことができます。すべての URL は、適切な [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) URI テンプレートであることが想定されています。その後、[uri\_template](https://github.com/hannesg/uri_template) gem などを使用して、これらのテンプレートを展開できます。 ```ruby >> tmpl = URITemplate.new('/notifications{?since,all,participating}') >> tmpl.expand => "/notifications" >> tmpl.expand all: 1 => "/notifications?all=1" >> tmpl.expand all: 1, participating: 1 => "/notifications?all=1&participating=1" ``` ## レート制限 GitHub REST API では、特定の期間内に行うことができる要求の数が制限されます。レート制限の詳細と、現在のレート制限の状態を確認する方法については、 [REST API のレート制限](/ja/enterprise-server@3.22/rest/using-the-rest-api/rate-limits-for-the-rest-api) を参照してください。 ## 次のステップこの記事では、リポジトリの issue を一覧表示して作成する方法について説明しました。さらに練習する場合は、issue にコメントを付けたり、issue のタイトルを編集したり、issue を閉じてみたりしてください。詳細については、[「issue コメントの作成」](/ja/enterprise-server@3.22/rest/issues/comments#create-an-issue-comment)と[「issue の更新」エンドポイント](/ja/enterprise-server@3.22/rest/issues/issues#update-an-issue)を参照してください。使用できるエンドポイントについて詳しくは、[REST リファレンスドキュメント](/ja/enterprise-server@3.22/rest)を参照してください。