GitHub REST API 快速入门

了解如何开始使用 GitHub REST API。

本文内容

简介

本文介绍如何使用 GitHub CLI、curl 或 JavaScript 快速开始使用 GitHub REST API。有关更详细的指南，请参阅“REST API 入门”。

在命令行中使用 GitHub CLI

GitHub CLI 是从命令行使用 GitHub REST API 的最简单方法。

  1. 在 macOS、Windows 或 Linux 上安装 GitHub CLI。有关更多信息，请参阅 GitHub CLI 存储库中的 安装。

  2. 通过从终端运行此命令对 GitHub 进行身份验证。

    gh auth login

  3. 按照屏幕上的提示进行操作。

    当您选择 HTTPS 作为 Git 操作的首选协议并回答询问是否希望使用 GitHub 凭据对 Git 进行身份验证的提示时，“是”，GitHub CLI 会自动为您存储 Git 凭据。这非常有用，因为它允许您使用 Git 命令（如 git push 和 git pull），而无需设置单独的凭据管理器或使用 SSH。

  4. 使用 GitHub CLI api 子命令（后跟路径）发出请求。使用 --method 或 -X 标志指定方法。有关更多信息，请参阅 GitHub CLI api 文档。

    此示例向“获取 Octocat”端点发出请求，该端点使用 GET 方法和 /octocat 路径。有关此端点的完整参考文档，请参阅“元数据的 REST API 端点”。

    Shell
    gh api /octocat --method GET

在 GitHub Actions 中使用 GitHub CLI

你也可以在 GitHub Actions 工作流中使用 GitHub CLI。有关详细信息，请参阅“在工作流中使用 GitHub CLI”。

使用访问令牌进行身份验证

不要使用 gh auth login 命令，而是将访问令牌作为名为 GH_TOKEN 的环境变量传递。GitHub 建议你使用内置的 GITHUB_TOKEN，而不是创建令牌。如果这不可行，请将令牌存储为机密，并在下面的示例中用机密名称替换 GITHUB_TOKEN。有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

以下示例工作流使用“列出存储库问题”端点，并请求 octocat/Spoon-Knife 存储库中的问题列表。

YAML
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 应用进行身份验证

如果你使用 GitHub 应用进行身份验证，则可以在工作流中创建安装访问令牌

  1. 将 GitHub 应用的 ID 存储为配置变量。在以下示例中，用 APP_ID 替换配置变量的名称。你可以在应用的设置页面或通过 API 找到应用 ID。有关详细信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的详细信息，请参阅“变量”。

  2. 为你的应用生成一个私钥。将生成的文件内容存储为一个秘密。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为秘密的名称。有关更多信息，请参阅“管理 GitHub 应用的私钥”。有关秘密的更多信息，请参阅“在 GitHub Actions 中使用秘密”。

  3. 添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如

    YAML
    
on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        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

你可以在 JavaScript 脚本中使用 Octokit.js 与 GitHub REST API 进行交互。有关更多信息，请参阅“使用 REST API 和 JavaScript 编写脚本”。

  1. 创建一个访问令牌。例如，创建一个个人访问令牌或 GitHub 应用用户访问令牌。你将使用此令牌对你的请求进行身份验证，因此你应该为其提供访问该端点所需的任何范围或权限。有关更多信息，请参阅“对 REST API 进行身份验证”或“识别和授权 GitHub 应用的用户”。

    警告：将你的访问令牌视为密码。

    为了保护你的令牌安全，你可以将你的令牌存储为一个秘密，并通过 GitHub Actions 运行你的脚本。有关更多信息，请参阅“在 GitHub Actions 中使用 Octokit.js”部分。

    你还可以将你的令牌存储为 Codespaces 秘密，并在 Codespaces 中运行你的脚本。有关更多信息，请参阅“管理 Codespaces 的加密秘密”。

    如果这些选项不可行，请考虑使用其他 CLI 服务来安全地存储你的令牌。

  2. 安装 octokit。例如，npm install octokit。有关安装或加载 octokit 的其他方法，请参阅 Octokit.js 自述文件。

  3. 在脚本中导入octokit。例如，import { Octokit } from "octokit";。有关导入octokit的其他方法，请参阅Octokit.js 自述文件。

  4. 使用令牌创建Octokit实例。将YOUR-TOKEN替换为你的令牌。

    JavaScript
    const octokit = new Octokit({ 
  auth: 'YOUR-TOKEN'
});

  5. 使用octokit.request执行请求。将 HTTP 方法和路径作为第一个参数发送。在对象中指定任何路径、查询和正文参数作为第二个参数。有关参数的更多信息，请参阅“REST API 入门”。

    例如，在以下请求中，HTTP 方法为GET，路径为/repos/{owner}/{repo}/issues，参数为owner: "octocat"和repo: "Spoon-Knife"。

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

在 GitHub Actions 中使用 Octokit.js

你还可以执行 GitHub Actions 工作流中的 JavaScript 脚本。有关更多信息，请参阅“GitHub Actions 的工作流语法”。

使用访问令牌进行身份验证

GitHub 建议你使用内置的GITHUB_TOKEN，而不是创建令牌。如果这不可行，请将你的令牌存储为机密，并将以下示例中的GITHUB_TOKEN替换为你的机密名称。有关GITHUB_TOKEN的更多信息，请参阅“自动令牌身份验证”。有关机密的更多信息，请参阅“在 GitHub Actions 中使用机密”。

以下示例工作流

  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:
      issues: read
    steps:
      - name: Check out repo content
        uses: actions/checkout@v4

      - 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 脚本。

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 应用进行身份验证

如果你使用 GitHub 应用进行身份验证，则可以在工作流中创建安装访问令牌

  1. 将 GitHub 应用的 ID 存储为配置变量。在以下示例中，将APP_ID替换为配置变量的名称。你可以在应用的设置页面或通过应用 API 找到应用 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的更多信息，请参阅“变量”。

  2. 为你的应用生成一个私钥。将生成的文件内容存储为一个秘密。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为秘密的名称。有关更多信息，请参阅“管理 GitHub 应用的私钥”。有关秘密的更多信息，请参阅“在 GitHub Actions 中使用秘密”。

  3. 添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如

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

      - 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@v1
        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

注意：如果你想从命令行发出 API 请求，GitHub 建议你使用 GitHub CLI，它简化了身份验证和请求。有关使用 GitHub CLI 入门 REST API 的更多信息，请参阅本文的 GitHub CLI 版本。

  1. 如果你的机器上尚未安装 curl，请安装它。要检查 curl 是否已安装，请在命令行中执行 curl --version。如果输出提供了有关 curl 版本的信息，则表示已安装 curl。如果你收到类似于 command not found: curl 的消息，则需要下载并安装 curl。有关更多信息，请参阅 curl 项目下载页面。

  2. 创建访问令牌。例如，创建个人访问令牌或 GitHub App 用户访问令牌。你将使用此令牌对你的请求进行身份验证，因此你应为其授予访问端点所需的任何范围或权限。有关更多信息，请参阅“向 REST API 进行身份验证”。

    警告：将你的访问令牌视为密码。

    为了保护你的令牌安全，你可以将你的令牌存储为 Codespaces 密钥，并通过 Codespaces 使用命令行。有关更多信息，请参阅“管理 Codespaces 的加密密钥”。

    你还可以使用 GitHub CLI 代替 curl。GitHub CLI 将为你处理身份验证。有关更多信息，请参阅此页面的 GitHub CLI 版本。

    如果这些选项不可行，请考虑使用其他 CLI 服务来安全地存储你的令牌。

  3. 使用 curl 命令发出你的请求。在 Authorization 标头中传递你的令牌。将 YOUR-TOKEN 替换为你的令牌。

    Shell
    curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

    注意：在大多数情况下，你可以使用 Authorization: Bearer 或 Authorization: token 传递令牌。但是，如果你要传递 JSON Web 令牌 (JWT)，则必须使用 Authorization: Bearer。

在 GitHub Actions 中使用 curl 命令

你还可以在你 GitHub Actions 工作流中使用 curl 命令。

使用访问令牌进行身份验证

GitHub 建议你使用内置的GITHUB_TOKEN，而不是创建令牌。如果这不可行，请将你的令牌存储为机密，并将以下示例中的GITHUB_TOKEN替换为你的机密名称。有关GITHUB_TOKEN的更多信息，请参阅“自动令牌身份验证”。有关机密的更多信息，请参阅“在 GitHub Actions 中使用机密”。

YAML
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 应用进行身份验证

如果你使用 GitHub 应用进行身份验证，则可以在工作流中创建安装访问令牌

  1. 将 GitHub 应用的 ID 存储为配置变量。在以下示例中，将APP_ID替换为配置变量的名称。你可以在应用的设置页面或通过应用 API 找到应用 ID。有关更多信息，请参阅“GitHub 应用的 REST API 端点”。有关配置变量的更多信息，请参阅“变量”。

  2. 为你的应用生成私钥。将生成的文件的内容存储为密钥。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为密钥的名称。有关更多信息，请参阅“管理 GitHub Apps 的私钥”。有关存储密钥的更多信息，请参阅“在 GitHub Actions 中使用密钥”。

  3. 添加一个步骤来生成令牌，并使用该令牌代替 GITHUB_TOKEN。请注意，此令牌将在 60 分钟后过期。例如

    YAML
    
on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate-token
        uses: actions/create-github-app-token@v1
        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 入门”。