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

JavaScript を使用して要求を行うために、Octokit.js を使用できます。 詳しくは、Octokit.js の README を参照してく� さい。

まず、Octokit のインスタンスを作成します。ベース URL を http(s)://HOSTNAME/api/v3 に設定します。 [hostname] を your GitHub Enterprise Server instanceの名前に置き換えます。

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
});

その後、request メソッドを使用して要求を行います。 HTTP メソッドとパスを最初の引数として渡します。

await octokit.request("GET /octocat", {});

Octokit.js ライブラリで認証するには、Octokit のインスタンスの作成時にトークンを渡すことができます。 YOUR-TOKEN をお使いのトークンに置き換えます。[hostname] をお使いの your GitHub Enterprise Server instanceの名前に置き換えます。

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

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

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

次のワークフロー例を参照してく� さい。

1. リポジトリのコンテンツをチェックアウトする
2. Node.js を設定する
3. octokit をインストールする
4. GITHUB_TOKEN の値を、TOKEN と呼ばれる環境変数として� �納し、.github/actions-scripts/use-the-api.mjs を実行する。これにより、その環境変数に process.env.TOKEN としてアクセスできます。

ワークフローの例:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node .github/actions-scripts/use-the-api.mjs

ファイル パス .github/actions-scripts/use-the-api.mjs を含む JavaScript スクリプトの例:

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN,
});

await octokit.request("GET /octocat", {});

スクリプトを別のファイルに� �納し、ワークフローからスクリプトを実行するのではなく、actions/github-script アクションを使用してスクリプトを実行できます。 詳しくは、actions/github-script README をご覧く� さい。

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

Octokit.js ライブラリでは自動的に Accept: application/vnd.github+json ヘッダーが渡されます。 追� のヘッダーまたは別の Accept ヘッダーを渡すには、headers メソッドに 2 番目の引数として渡されるオブジェクトに request プロパティを追� します。 headers プロパティの値は、キーがヘッダー名で値がヘッダー値のオブジェクトです。 たとえば、値が text/plain の content-type ヘッダーを送信する� �合は次のようになります。

await octokit.request("GET /octocat", {
  headers: {
    "content-type": "text/plain",
  },
});

Octokit.js で要求を行うと、パス パラメーターを含むすべてのパラメーターが、request メソッドの 2 番目の引数としてオブジェクトで渡されます。 octocat/Spoon-Knife リポジトリから issue を取得するには、owner を octocat として、repo を Spoon-Knife として指定します。

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife"
});

Octokit.js で要求を行うと、クエリ パラメーターを含むすべてのパラメーターが、request メソッドの 2 番目の引数としてオブジェクトで渡されます。

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
  sort: "updated",
  direction: "asc",
});

Octokit.js で要求を行うと、本文パラメーターを含むすべてのパラメーターが、request メソッドの 2 番目の引数としてオブジェクトで渡されます。

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  title: "Created with the REST API",
  body: "This is a test issue created by the REST API",
});

Octokit.js で要求を行うと、request メソッドでは promise が返されます。 要求が成功した� �合、promise は、応答のHTTP 状態コード (status) と応答ヘッダー (headers) を含むオブジェクトに解決されます。 エラーが発生した� �合、promise は、応答のHTTP 状態コード (status) と応答ヘッダー (response.headers) を含むオブジェクトに解決されます。

try/catch ブロックを使用して、エラーが発生した� �合にそれをキャッチできます。 たとえば、次のスクリプトの要求が成功した� �合、そのスクリプトでは状態コードと x-ratelimit-remaining ヘッダーの値がログに記録されます。 要求が成功しなかった� �合、スクリプトでは状態コード、x-ratelimit-remaining ヘッダーの値、およびエラー メッセージがログに記録されます。

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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}`)
}

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
});

たとえば、各 issue のタイトルと作成者 ID を取得できます。

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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}`)
}