GitHub REST API 快速入门

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

开始使用 GitHub CLI

在命令行中使用 GitHub CLI

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

注意：以下示例适用于 GitHub.com。如果想要尝试使用 GitHub Enterprise Server 的示例，必须将 octocat/Spoon-Knife 替换为你的实例上的存储库。或者，重新运行 gh auth login 命令，向 GitHub.com 而不是你的实例进行身份验证。

如果尚未安装 GitHub CLI，请进行安装。有关安装说明，请参阅 GitHub CLI 存储库。
使用 auth login 子命令向 GitHub CLI 进行身份验证。有关详细信息，请参阅 GitHub CLI auth login 文档。
```
gh auth login
```
使用 api 子命令发出 API 请求。有关详细信息，请参阅 GitHub CLI api 文档。
```
gh api repos/octocat/Spoon-Knife/issues
```

在 GitHub Actions 中使用 GitHub CLI

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

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

注意：以下示例工作流适用于 GitHub.com。如果想要尝试使用 GitHub Enterprise Server 的示例，必须将 octocat/Spoon-Knife 替换为 GitHub Enterprise Server 上的存储库。

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions:
      issues: read
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

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

将 GitHub App 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。可以在应用的设置页面上或通过 API 找到应用 ID。有关详细信息，请参阅 REST API 文档中的“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。

添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

# <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>此工作流使用未经 GitHub 认证的操作。
# <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>它们由第三方提供，并受
# <a name="separate-terms-of-service-privacy-policy-and-support"></a>单独的服务条款、隐私政策和支持
# <a name="documentation"></a>文档。

on:
  workflow_dispatch:
jobs:
  track_pr:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PEM }}

      - name: Use API
        env:
          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
        run: |
          gh api repos/octocat/Spoon-Knife/issues

开始使用 JavaScript

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

使用 Octokit.js

Note: The following example is intended for GitHub.com. If you'd prefer to try the example using GitHub Enterprise Server, you must replace octocat/Spoon-Knife with a repository on your instance. Alternatively, you can create a new Octokit instance without specifying baseURL.

创建访问令牌。例如，创建 personal access token 或 GitHub App 用户到服务器访问令牌。有关详细信息，请参阅“创建 personal access token”或“识别和授权 GitHub 应用的用户”。

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

若要确保令牌安全，可以将令牌存储为机密，并通过 GitHub Actions 运行脚本。有关详细信息，请参阅“在 GitHub Actions 中使用 Octokit.js”部分。

如果无法使用这些选项，请考虑使用其他服务（如 1Password CLI）安全地存储令牌。
安装 octokit。例如，npm install octokit。有关安装或加载 octokit 的其他方式，请参阅 Octokit.js 自述文件。
在脚本中导入 octokit。例如，import { Octokit } from "octokit";。有关导入 octokit 的其他方式，请参阅 Octokit.js 自述文件。
使用密钥创建 Octokit 的实例。将 YOUR-TOKEN 替换为你的令牌。
```
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
});
```
使用 octokit.request 执行请求。将 HTTP 方法和路径作为第一个参数发送。将对象中的任何路径、查询和正文参数指定为第二个参数。例如，在以下请求中，HTTP 方法为 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 的详细信息，请参阅“自动令牌身份验证”。有关机密的详细信息，请参阅“已加密的机密”。

Note: The following example is intended for GitHub.com. If you'd prefer to try the example using GitHub Enterprise Server, you must replace octocat/Spoon-Knife with a repository on your instance. Alternatively, you can create a new Octokit instance without specifying baseURL.

以下示例工作流：

签出存储库内容
设置 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@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        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 App 进行身份验证，则可以在工作流中创建安装访问令牌：

将 GitHub App 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。

添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

# <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>此工作流使用未经 GitHub 认证的操作。
# <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>它们由第三方提供，并受
# <a name="separate-terms-of-service-privacy-policy-and-support"></a>单独的服务条款、隐私政策和支持
# <a name="documentation"></a>文档。

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

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

      - name: Install dependencies
        run: npm install octokit

      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.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`

使用命令行中的 `curl`

注意：

以下示例适用于 GitHub.com。如果想要尝试使用 GitHub Enterprise Server 的示例，必须将 https://api.github.com 替换为 http(s)://HOSTNAME/api/v3，并将 HOSTNAME 替换为 your GitHub Enterprise Server instance 的主机名。此外，还必须将 octocat/Spoon-Knife 替换为 GitHub Enterprise Server 上的存储库。
如果要从命令行发出 API 请求，GitHub 建议使用 GitHub CLI，可以简化身份验证和请求。有关通过 GitHub CLI 开始使用 REST API 的详细信息，请参阅本文的 GitHub CLI 版本。

如果计算机上尚未安装 curl，请安装。若要检查是否安装了 curl，请在命令行中执行 curl --version。如果输出是有关 curl 版本的信息，则其已安装。如果收到类似于 command not found: curl 的消息，则需要下载并安装 curl。有关详细信息，请参阅 curl 项目下载页面。
创建访问令牌。例如，创建 personal access token 或 GitHub App 用户到服务器访问令牌。有关详细信息，请参阅“创建 personal access token”或“识别和授权 GitHub 应用的用户”。

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

还可以使用 GitHub CLI，而不是 curl。 GitHub CLI 会为你处理身份验证。有关详细信息，请参阅此页面的 GitHub CLI 版本。

如果无法使用这些选项，请考虑使用其他服务（如 1Password CLI）安全地存储令牌。
使用 curl 命令发出请求。在 Authorization 标头中传递令牌。将 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 命令。

GitHub 建议使用内置 GITHUB_TOKEN，而不是创建令牌。如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 GITHUB_TOKEN 替换为机密的名称。有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关机密的详细信息，请参阅“已加密的机密”。

注意：以下示例工作流适用于 GitHub.com。如果想要尝试使用 GitHub Enterprise Server 的示例，请注意以下差异。

必须将 https://api.github.com 替换为 http(s)://HOSTNAME/api/v3，并将 HOSTNAME 替换为 your GitHub Enterprise Server instance 的主机名。
必须将 octocat/Spoon-Knife 替换为 GitHub Enterprise Server 上的存储库。

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 的 ID 作为机密进行存储。在以下示例中，将 APP_ID 替换为机密的名称。您可以在应用的设置页面上或通过应用 API 找到应用 ID。有关详细信息，请参阅“应用”。有关机密的详细信息，请参阅“已加密的机密”。
为应用生成私钥。将所生成文件的内容作为机密进行存储。（存储文件的全部内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----。）在以下示例中，将 APP_PEM 替换为机密的名称。有关详细信息，请参阅“使用 GitHub Apps 进行身份验证”。

添加用于生成令牌的步骤，并使用该令牌而不是 GITHUB_TOKEN。请注意，此令牌会在 60 分钟后过期。例如：

# <a name="this-workflow-uses-actions-that-are-not-certified-by-github"></a>此工作流使用未经 GitHub 认证的操作。
# <a name="they-are-provided-by-a-third-party-and-are-governed-by"></a>它们由第三方提供，并受
# <a name="separate-terms-of-service-privacy-policy-and-support"></a>单独的服务条款、隐私政策和支持
# <a name="documentation"></a>文档。

on:
  workflow_dispatch:
jobs:
  use_api:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: tibdex/github-app-token@36464acb844fc53b9b8b2401da68844f6b05ebb0
        with:
          app_id: ${{ secrets.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 REST API 快速入门

In this article

开始使用 GitHub CLI

在命令行中使用 GitHub CLI

在 GitHub Actions 中使用 GitHub CLI

开始使用 JavaScript

使用 Octokit.js

在 GitHub Actions 中使用 Octokit.js

开始使用 curl

使用命令行中的 curl

在 GitHub Actions 中使用 curl 命令

后续步骤

开始使用 `curl`

使用命令行中的 `curl`

在 GitHub Actions 中使用 `curl` 命令