GitHub REST API 快速入门

简介

本文介绍了如何使用 GitHub CLI、curl 或 JavaScript 快速入门 GitHub REST API。欲获取更详细的指南，请参阅 REST API 入门指南。

在命令行中使用 GitHub CLI

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

在 macOS、Windows 或 Linux 上安装 GitHub CLI。有关详细信息，请参阅 GitHub CLI 仓库中的安装。
要对 GitHub 进行身份验证，请在终端中运行以下命令。
```
gh auth login
```
选择要进行身份验证的位置
- 如果你在 GitHub.com 访问 GitHub，请选择 GitHub.com。
- 如果你在其他域名访问 GitHub，请选择 Other，然后输入你的主机名（例如：octocorp.ghe.com）。
按照屏幕上的其余提示操作。

当你选择 HTTPS 作为 Git 操作的首选协议，并在提示是否使用 GitHub 凭据对 Git 进行身份验证时回答“是”，GitHub CLI 会自动为你存储 Git 凭据。这很有用，因为它允许你在无需单独的凭据管理器或使用 SSH 的情况下使用 git push 和 git pull 等 Git 命令。
使用 GitHub CLI 的 api 子命令发起请求，后接路径。使用 --method 或 -X 标志指定请求方法。更多信息请参阅 GitHub CLI api 文档。

本示例向 “获取 Octocat” 接口发起请求，使用 GET 方法和路径 /octocat。该接口的完整参考文档请参阅元数据相关的 REST API 接口。
Shell
```
gh api /octocat --method GET
```
```
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_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

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 应用进行身份验证，您可以在工作流中创建安装访问令牌

将 GitHub 应用的 ID 存储为配置变量。在以下示例中，用配置变量的名称替换 APP_ID。您可以在应用的设置页面或通过 API 找到应用 ID。更多信息请参阅 GitHub 应用的 REST API 接口。关于配置变量的更多信息，请参阅在变量中存储信息。
为您的应用生成私钥。将生成文件的全部内容（包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----）存为密钥。在以下示例中，用密钥名称替换 APP_PEM。更多信息请参阅管理 GitHub 应用的私钥。有关密钥的更多信息，请参阅在 GitHub Actions 中使用密钥。

添加一步以生成令牌，并使用该令牌替代 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@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

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

创建访问令牌。例如，创建个人访问令牌或 GitHub 应用用户访问令牌。您将在请求中使用该令牌进行身份验证，因此应为其授予访问该接口所需的作用域或权限。更多信息请参阅对 REST API 进行身份验证或为 GitHub 应用识别和授权用户。

警告

将访问令牌视作密码。

为了确保令牌安全，您可以将令牌存为密钥并通过 GitHub Actions 运行脚本。更多信息请参阅在 GitHub Actions 中使用 Octokit.js 部分。

您也可以将令牌存为 Codespaces 密钥并在 Codespaces 中运行脚本。更多信息请参阅管理 Codespaces 的加密密钥。

如果上述选项不可行，请考虑使用其他 CLI 服务安全存储令牌。
安装 octokit。例如，npm install octokit。有关其他安装或加载 octokit 的方法，请参阅 Octokit.js README。
在脚本中导入 octokit。例如，import { Octokit } from "octokit";。有关其他导入 octokit 的方式，请参阅 Octokit.js README。

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

JavaScript

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

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

使用 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",
});
```
```
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_TOKEN 进行身份验证。有关密钥的更多信息，请参阅在 GitHub Actions 中使用密钥。

以下示例工作流

检出仓库内容
设置 Node.js 环境
安装 octokit
将 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@v5

      - 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 应用进行身份验证，您可以在工作流中创建安装访问令牌

将 GitHub 应用的 ID 存为配置变量。在以下示例中，用配置变量的名称替换 APP_ID。您可以在应用的设置页面或通过 App API 找到应用 ID。更多信息请参阅 GitHub 应用的 REST API 接口。关于配置变量的更多信息，请参阅在变量中存储信息。
为您的应用生成私钥。将生成文件的全部内容（包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----）存为密钥。在以下示例中，用密钥名称替换 APP_PEM。更多信息请参阅管理 GitHub 应用的私钥。有关密钥的更多信息，请参阅在 GitHub Actions 中使用密钥。

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

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

      - 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`

注意

如果您想在命令行发起 API 请求，GitHub 推荐使用 GitHub CLI，它简化了身份验证和请求。有关使用 GitHub CLI 入门 REST API 的更多信息，请阅本文的 GitHub CLI 版本。

如果您的机器未安装 curl，请先安装。要检查是否已安装 curl，在命令行执行 curl --version。如果输出显示了 curl 的版本信息，则表示已安装。如果出现类似 command not found: curl 的提示，则需要下载并安装 curl。更多信息请参阅 curl 项目下载页面。
创建访问令牌。例如，创建个人访问令牌或 GitHub 应用用户访问令牌。您将在请求中使用该令牌进行身份验证，因此应为其授予访问该接口所需的所有作用域或权限。更多信息请参阅对 REST API 进行身份验证。

警告

将访问令牌视作密码。

为确保令牌安全，您可以将令牌存为 Codespaces 密钥，并通过 Codespaces 使用命令行。更多信息请参阅管理 Codespaces 的加密密钥。

您也可以使用 GitHub CLI 替代 curl。GitHub CLI 会为您处理身份验证。更多信息请参阅本页面的 GitHub CLI 版本。

如果上述选项不可行，请考虑使用其他 CLI 服务安全存储令牌。

使用 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"

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 命令。

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

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"

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 应用进行身份验证，您可以在工作流中创建安装访问令牌

将 GitHub 应用的 ID 存为配置变量。在以下示例中，用配置变量的名称替换 APP_ID。您可以在应用的设置页面或通过 App API 找到应用 ID。更多信息请参阅 GitHub 应用的 REST API 接口。关于配置变量的更多信息，请参阅在变量中存储信息。
为您的应用生成私钥。将生成文件的全部内容（包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----）存为密钥。在以下示例中，用密钥名称替换 APP_PEM。更多信息请参阅管理 GitHub 应用的私钥。有关存储密钥的更多信息，请参阅在 GitHub Actions 中使用密钥。

添加一步以生成令牌，并使用该令牌替代 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@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"

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 入门指南。

工具导航

本文内容

简介

在命令行中使用 GitHub CLI

在 GitHub Actions 中使用 GitHub CLI

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

使用 GitHub 应用进行身份验证

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

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

使用 GitHub 应用进行身份验证

在命令行中使用 `curl`

在 GitHub Actions 中使用 `curl` 命令

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

使用 GitHub 应用进行身份验证

后续步骤