Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

GitHub REST API 快速入门

了解如何开始使用 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 而不是你的实例 进行身份验证。

  1. 如果尚未安装 GitHub CLI,请进行安装。 有关安装说明,请参阅 GitHub CLI 存储库

  2. 使用 auth login 子命令向 GitHub CLI 进行身份验证。 有关详细信息,请参阅 GitHub CLI auth login 文档

    gh auth login
  3. 使用 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 进行身份验证,则可以在工作流中创建安装访问令牌:

  1. 将 GitHub App 的 ID 作为机密进行存储。 在以下示例中,将 APP_ID 替换为机密的名称。 可以在应用的设置页面上或通过 API 找到应用 ID。 有关详细信息,请参阅 REST API 文档中的“应用”。 有关机密的详细信息,请参阅“已加密的机密”。

  2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 (存储文件的全部内容,包括 -----BEGIN RSA PRIVATE KEY----------END RSA PRIVATE KEY-----。)在以下示例中,将 APP_PEM 替换为机密的名称。 有关详细信息,请参阅“使用 GitHub Apps 进行身份验证”。

  3. 添加用于生成令牌的步骤,并使用该令牌而不是 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.

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

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

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

    如果无法使用这些选项,请考虑使用其他服务(如 1Password CLI)安全地存储令牌。

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

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

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

    const octokit = new Octokit({
      auth: 'YOUR-TOKEN'
    });
    
  5. 使用 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.

以下示例工作流:

  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@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 进行身份验证,则可以在工作流中创建安装访问令牌:

  1. 将 GitHub App 的 ID 作为机密进行存储。 在以下示例中,将 APP_ID 替换为机密的名称。 您可以在应用的设置页面上或通过应用 API 找到应用 ID。 有关详细信息,请参阅“应用”。 有关机密的详细信息,请参阅“已加密的机密”。

  2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 (存储文件的全部内容,包括 -----BEGIN RSA PRIVATE KEY----------END RSA PRIVATE KEY-----。)在以下示例中,将 APP_PEM 替换为机密的名称。 有关详细信息,请参阅“使用 GitHub Apps 进行身份验证”。

  3. 添加用于生成令牌的步骤,并使用该令牌而不是 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 版本。
  1. 如果计算机上尚未安装 curl,请安装。 若要检查是否安装了 curl,请在命令行中执行 curl --version。 如果输出是有关 curl 版本的信息,则其已安装。 如果收到类似于 command not found: curl 的消息,则需要下载并安装 curl。 有关详细信息,请参阅 curl 项目下载页面

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

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

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

    如果无法使用这些选项,请考虑使用其他服务(如 1Password CLI)安全地存储令牌。

  3. 使用 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: BearerAuthorization: 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 进行身份验证,则可以在工作流中创建安装访问令牌:

  1. 将 GitHub App 的 ID 作为机密进行存储。 在以下示例中,将 APP_ID 替换为机密的名称。 您可以在应用的设置页面上或通过应用 API 找到应用 ID。 有关详细信息,请参阅“应用”。 有关机密的详细信息,请参阅“已加密的机密”。

  2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 (存储文件的全部内容,包括 -----BEGIN RSA PRIVATE KEY----------END RSA PRIVATE KEY-----。)在以下示例中,将 APP_PEM 替换为机密的名称。 有关详细信息,请参阅“使用 GitHub Apps 进行身份验证”。

  3. 添加用于生成令牌的步骤,并使用该令牌而不是 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 入门”。