本文介绍如何快速地通过 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 CLIauth login
文档。gh auth login
-
使用
api
子命令发出 API 请求。 有关详细信息,请参阅 GitHub CLIapi
文档。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 入门”。