{"meta":{"title":"GitHub REST API 快速入门","intro":"了解如何开始使用 GitHub REST API。","product":"REST API","breadcrumbs":[{"href":"/zh/rest","title":"REST API"},{"href":"/zh/rest/quickstart","title":"快速入门"}],"documentType":"article"},"body":"# GitHub REST API 快速入门\n\n了解如何开始使用 GitHub REST API。\n\n## 简介\n\n本文介绍如何使用 GitHub、GitHub CLI 或 JavaScript 快速开始使用 `curl` REST API。 有关更详细的指南，请参阅 [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api)。\n\n<div class=\"ghd-tool cli\">\n\n## 使用命令行中的 GitHub CLI\n\nGitHub CLI 是从命令行使用 GitHub REST API 的最简单方法。\n\n1. 在 macOS、Windows 或 Linux 上安装 GitHub CLI。 有关安装说明的详细信息，请参阅 GitHub CLI 存储库中的[安装](https://github.com/cli/cli?ref_product=cli\\&ref_type=engagement\\&ref_style=text#installation)。\n\n2. 若要向 GitHub 进行身份验证，请从终端运行以下命令。\n\n   ```shell\n   gh auth login\n   ```\n\n3. 选择要进行身份验证的位置：\n\n   * 如果通过 GitHub 访问 GitHub.com，请选择“GitHub.com”\\*\\*\\*\\*。\n   * 如果通过其他域访问 GitHub，请选择“其他”，然后输入主机名（例如 \\*\\*\\*\\*）`octocorp.ghe.com`。\n\n4. 按照屏幕上的其余提示操作。\n\n   选择 HTTPS 作为 Git 操作的首选协议时，GitHub CLI 将自动存储 Git 凭据，并对询问是否要使用 GitHub 凭据向 Git 进行身份验证的提示回答“是”。 此操作非常有用，因为这允许直接使用 `git push`、`git pull` 等 Git 命令，无需设置单独的凭据管理器或使用 SSH。\n\n5. 使用 GitHub CLI`api` 子命令发出请求，后面加上路径。 使用 `--method` 或 `-X` 标志指定方法。 有关详细信息，请参阅 [GitHub CLI`api` 文档](https://cli.github.com/manual/gh_api)。\n\n   此示例向使用方法 `GET` 和路径 `/octocat` 的“Get Octocat”终结点发出请求。 有关此终结点的完整参考文档，请参阅 [元数据的 REST API 端点](/zh/rest/meta/meta#get-octocat)。\n\n   ```shell copy\n   gh api /octocat --method GET\n   ```\n\n## 在GitHub CLI中使用GitHub Actions\n\n你也可以在 GitHub CLI 工作流中使用 GitHub Actions。 有关详细信息，请参阅“[在工作流中使用 GitHub CLI](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-github-cli)”。\n\n### 使用访问令牌进行身份验证\n\n不要使用 `gh auth login` 命令，而是将访问令牌作为名为 `GH_TOKEN` 的环境变量进行传递。\nGitHub 建议您使用内置的 `GITHUB_TOKEN`，而不是自行创建令牌。 如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 `GITHUB_TOKEN` 替换为机密的名称。 有关 `GITHUB_TOKEN` 的详细信息，请参阅 [在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token)。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n\n以下示例工作流使用[列出存储库问题](/zh/rest/issues/issues#list-repository-issues)端点，并请求列出中的问题，即 `octocat/Spoon-Knife` 存储库。\n\n```yaml copy\non:\n  workflow_dispatch:\njobs:\n  use_api:\n    runs-on: ubuntu-latest\n    permissions:\n      issues: read\n    steps:\n      - env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n        run: |\n          gh api https://api.github.com/repos/octocat/Spoon-Knife/issues\n```\n\n### 使用GitHub App进行身份验证\n\n如果要使用 a GitHub App进行身份验证，可以在工作流中创建安装访问令牌：\n\n1. 将 GitHub App 的客户端 ID 存储为配置变量。 在下面的示例中，将 `APP_CLIENT_ID` 替换为配置变量的名称。 可以在应用的设置页上或通过 API 查找客户端 ID。 有关详细信息，请参阅“[GitHub Apps 的 REST API 终结点](/zh/rest/apps/apps#get-an-app)”。 有关配置变量的详细信息，请参阅 [在变量中存储信息](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#defining-configuration-variables-for-multiple-workflows)。\n2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 （存储文件的全部内容，包括 `-----BEGIN RSA PRIVATE KEY-----` 和 `-----END RSA PRIVATE KEY-----`。）在以下示例中，将 `APP_PRIVATE_KEY` 替换为机密的名称。 有关详细信息，请参阅“[管理GitHub应用的私钥](/zh/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)”。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n3. 添加用于生成令牌的步骤，并使用该令牌而不是 `GITHUB_TOKEN`。 请注意，此令牌会在 60 分钟后过期。\n   例如：\n\n   ```yaml copy\n   on:\n     workflow_dispatch:\n   jobs:\n     track_pr:\n       runs-on: ubuntu-latest\n       steps:\n         - name: Generate token\n           id: generate-token\n           uses: actions/create-github-app-token@v3\n           with:\n             client-id: ${{ vars.APP_CLIENT_ID }}\n             private-key: ${{ secrets.APP_PRIVATE_KEY }}\n         - name: Use API\n           env:\n             GH_TOKEN: ${{ steps.generate-token.outputs.token }}\n           run: |\n             gh api https://api.github.com/repos/octocat/Spoon-Knife/issues\n   ```\n\n</div>\n\n<div class=\"ghd-tool javascript\">\n\n## 使用 Octokit.js\n\n可以使用 Octokit.js 与 GitHub JavaScript 脚本中的 REST API 进行交互。 有关详细信息，请参阅[使用 REST API 和 JavaScript 编写脚本](/zh/rest/guides/scripting-with-the-rest-api-and-javascript)。\n\n1. 创建访问令牌。 例如，创建personal access token或GitHub App用户访问令牌。 你将使用此令牌对请求进行身份验证，因此应向其授予访问该终结点所需的任何范围或权限。 有关详细信息，请参阅 [对 REST API 进行身份验证](/zh/rest/authentication/authenticating-to-the-rest-api) 或 [Identing and authorizing users for GitHub Apps](/zh/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)。\n\n   > \\[!WARNING]\n   > 将访问令牌看做是密码。\n   >\n   > 若要确保令牌的安全，可以将令牌存储为机密，并通过 GitHub Actions运行脚本。 有关详细信息，请参阅部分中的 [“使用 Octokit.js GitHub Actions](#using-octokitjs-in-github-actions) ”。\n\n   还可以将令牌存储为 Codespaces 机密，并在 Codespaces 中运行脚本。 有关详细信息，请参阅[管理 Codespaces 的加密机密](/zh/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)。\n\n   > 如果无法使用这些选项，请考虑使用其他 CLI 服务安全地存储令牌。\n\n2. 安装 `octokit`。 例如，`npm install octokit`。 有关安装或加载 `octokit` 的其他方式，请参阅 [Octokit.js 自述文件](https://github.com/octokit/octokit.js/#readme)。\n\n3. 在脚本中导入 `octokit`。 例如，`import { Octokit } from \"octokit\";`。 有关导入 `octokit` 的其他方式，请参阅 [Octokit.js 自述文件](https://github.com/octokit/octokit.js/#readme)。\n\n4. 使用令牌创建实例 `Octokit` 。 将 `YOUR-TOKEN` 替换为你的令牌。\n\n   ```javascript copy\n   const octokit = new Octokit({ \n     auth: 'YOUR-TOKEN'\n   });\n   ```\n\n5. 使用 `octokit.request` 执行请求。 将 HTTP 方法和路径作为第一个参数发送。 将对象中的任何路径、查询和正文参数指定为第二个参数。 有关参数的详细信息，请参阅 [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api#parameters)。\n\n   例如，在以下请求中，HTTP 方法是`GET`，路径是`/repos/{owner}/{repo}/issues`，参数是`owner: \"octocat\"`和。`repo: \"Spoon-Knife\"`\n\n   ```javascript copy\n   await octokit.request(\"GET /repos/{owner}/{repo}/issues\", {\n     owner: \"octocat\",\n     repo: \"Spoon-Knife\",\n   });\n   ```\n\n## 在 GitHub Actions 中使用 Octokit.js\n\n您还可以在您的 GitHub Actions 工作流中执行 JavaScript 脚本。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsrun)”。\n\n### 使用访问令牌进行身份验证\n\nGitHub 建议您使用内置的 `GITHUB_TOKEN`，而不是自行创建令牌。 如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 `GITHUB_TOKEN` 替换为机密的名称。 有关 `GITHUB_TOKEN` 的详细信息，请参阅 [在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token)。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n\n以下示例工作流：\n\n1. 检出存储库内容\n2. 设置 Node.js\n3. 安装 `octokit`\n4. 将 `GITHUB_TOKEN` 的值存储为名为 `TOKEN` 的环境变量，并运行 `.github/actions-scripts/use-the-api.mjs`（它可以将该环境变量作为 `process.env.TOKEN` 进行访问）。\n\n```yaml\non:\n  workflow_dispatch:\njobs:\n  use_api_via_script:\n    runs-on: ubuntu-latest\n    permissions:\n      issues: read\n    steps:\n      - name: Check out repo content\n        uses: actions/checkout@v6\n\n      - name: Setup Node\n        uses: actions/setup-node@v7\n        with:\n          node-version: '16.17.0'\n          cache: npm\n\n      - name: Install dependencies\n        run: npm install octokit\n\n      - name: Run script\n        run: |\n          node .github/actions-scripts/use-the-api.mjs\n        env:\n          TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n下面是一个包含文件路径 `.github/actions-scripts/use-the-api.mjs`的示例 JavaScript 脚本。\n\n```javascript\nimport { Octokit } from \"octokit\"\n\nconst octokit = new Octokit({ \n  auth: process.env.TOKEN\n});\n\ntry {\n  const result = await octokit.request(\"GET /repos/{owner}/{repo}/issues\", {\n      owner: \"octocat\",\n      repo: \"Spoon-Knife\",\n    });\n\n  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})\n\n  console.log(titleAndAuthor)\n\n} catch (error) {\n  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)\n}\n```\n\n### 使用GitHub App进行身份验证\n\n如果要使用 a GitHub App进行身份验证，可以在工作流中创建安装访问令牌：\n\n1. 将 GitHub App 的客户端 ID 存储为配置变量。 在下面的示例中，将 `APP_CLIENT_ID` 替换为配置变量的名称。 可以在应用的设置页上或通过应用 API 查找客户端 ID。 有关详细信息，请参阅“[GitHub Apps 的 REST API 终结点](/zh/rest/apps/apps#get-an-app)”。 有关配置变量的详细信息，请参阅 [在变量中存储信息](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#defining-configuration-variables-for-multiple-workflows)。\n2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 （存储文件的全部内容，包括 `-----BEGIN RSA PRIVATE KEY-----` 和 `-----END RSA PRIVATE KEY-----`。）在以下示例中，将 `APP_PRIVATE_KEY` 替换为机密的名称。 有关详细信息，请参阅“[管理GitHub应用的私钥](/zh/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)”。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n3. 添加用于生成令牌的步骤，并使用该令牌而不是 `GITHUB_TOKEN`。 请注意，此令牌会在 60 分钟后过期。 例如：\n\n   ```yaml\n   on:\n     workflow_dispatch:\n   jobs:\n     use_api_via_script:\n       runs-on: ubuntu-latest\n       steps:\n         - name: Check out repo content\n           uses: actions/checkout@v6\n\n         - name: Setup Node\n           uses: actions/setup-node@v7\n           with:\n             node-version: '16.17.0'\n             cache: npm\n\n         - name: Install dependencies\n           run: npm install octokit\n\n         - name: Generate token\n           id: generate-token\n           uses: actions/create-github-app-token@v3\n           with:\n             client-id: ${{ vars.APP_CLIENT_ID }}\n             private-key: ${{ secrets.APP_PRIVATE_KEY }}\n\n         - name: Run script\n           run: |\n             node .github/actions-scripts/use-the-api.mjs\n           env:\n             TOKEN: ${{ steps.generate-token.outputs.token }}\n\n   ```\n\n</div>\n\n<div class=\"ghd-tool curl\">\n\n## 使用命令行中的 `curl`\n\n> \\[!NOTE]\n> 如果要从命令行发出 API 请求， GitHub 建议使用 GitHub CLI，这简化了身份验证和请求。 有关使用 GitHub CLIREST API 入门的详细信息，请参阅 GitHub CLI 本文的版本。\n\n1. 如果计算机上尚未安装 `curl`，请安装。 若要检查是否安装了 `curl`，请在命令行中执行 `curl --version`。 如果输出是有关 `curl` 版本的信息，则表示已安装 `curl`。 如果收到类似于 `command not found: curl` 的消息，则需要下载并安装 `curl`。 有关详细信息，请参阅 [curl 项目下载页面](https://curl.se/download.html)。\n\n2. 创建访问令牌。 例如，创建personal access token或GitHub App用户访问令牌。 使用此令牌对请求进行身份验证，因此应向其授予访问终结点所需的任何范围或权限。 有关详细信息，请参阅“[对 REST API 进行身份验证](/zh/rest/authentication/authenticating-to-the-rest-api)”。\n\n   > \\[!WARNING]\n   > 将访问令牌看做是密码。\n   >\n   > 若要保护令牌安全，可以将令牌存储为 Codespaces 密钥，并通过 Codespaces 使用命令行。 有关详细信息，请参阅[管理 Codespaces 的加密机密](/zh/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)。\n\n   > 也可以使用 GitHub CLI 而非 `curl`。\n   > GitHub CLI 将为你负责身份验证。 有关详细信息，请参阅 GitHub CLI 此页面的版本。\n   >\n   > 如果无法使用这些选项，请考虑使用其他 CLI 服务安全地存储令牌。\n\n3. 使用 `curl` 命令发出请求。 请在 `Authorization` 请求头中传递您的令牌。 将 `YOUR-TOKEN` 替换为你的令牌。\n\n   ```shell copy\n   curl --request GET \\\n   --url \"https://api.github.com/repos/octocat/Spoon-Knife/issues\" \\\n   --header \"Accept: application/vnd.github+json\" \\\n   --header \"Authorization: Bearer YOUR-TOKEN\"\n   ```\n\n   > \\[!NOTE]\n   > 在大多数情况下，可以使用 `Authorization: Bearer` 或 `Authorization: token` 传递令牌。 但是，如果要传递 JSON Web 令牌 (JWT)，则必须使用 `Authorization: Bearer`。\n\n## 在 `curl` 中使用 GitHub Actions 命令\n\n你还可以在`curl`工作流中使用GitHub Actions命令。\n\n### 使用访问令牌进行身份验证\n\nGitHub 建议您使用内置的 `GITHUB_TOKEN`，而不是自行创建令牌。 如果无法执行此操作，请将令牌存储为机密，并将以下示例中的 `GITHUB_TOKEN` 替换为机密的名称。 有关 `GITHUB_TOKEN` 的详细信息，请参阅 [在工作流中使用 GITHUB\\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token)。 有关机密的详细信息，请参阅 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。\n\n```yaml copy\non:\n  workflow_dispatch:\njobs:\n  use_api:\n    runs-on: ubuntu-latest\n    permissions:\n      issues: read\n    steps:\n      - env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n        run: |\n          curl --request GET \\\n          --url \"https://api.github.com/repos/octocat/Spoon-Knife/issues\" \\\n          --header \"Accept: application/vnd.github+json\" \\\n          --header \"Authorization: Bearer $GH_TOKEN\"\n```\n\n### 使用GitHub App进行身份验证\n\n如果要使用 a GitHub App进行身份验证，可以在工作流中创建安装访问令牌：\n\n1. 将 GitHub App 的客户端 ID 存储为配置变量。 在下面的示例中，将 `APP_CLIENT_ID` 替换为配置变量的名称。 可以在应用的设置页上或通过应用 API 查找客户端 ID。 有关详细信息，请参阅“[GitHub Apps 的 REST API 终结点](/zh/rest/apps/apps#get-an-app)”。 有关配置变量的详细信息，请参阅 [在变量中存储信息](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#defining-configuration-variables-for-multiple-workflows)。\n2. 为应用生成私钥。 将所生成文件的内容作为机密进行存储。 （存储文件的全部内容，包括 `-----BEGIN RSA PRIVATE KEY-----` 和 `-----END RSA PRIVATE KEY-----`。）在以下示例中，将 `APP_PRIVATE_KEY` 替换为机密的名称。 有关详细信息，请参阅“[管理GitHub应用的私钥](/zh/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)”。 有关存储机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)”。\n3. 添加用于生成令牌的步骤，并使用该令牌而不是 `GITHUB_TOKEN`。 请注意，此令牌会在 60 分钟后过期。\n   例如：\n\n   ```yaml copy\n   on:\n     workflow_dispatch:\n   jobs:\n     use_api:\n       runs-on: ubuntu-latest\n       steps:\n         - name: Generate token\n           id: generate-token\n           uses: actions/create-github-app-token@v3\n           with:\n             client-id: ${{ vars.APP_CLIENT_ID }}\n             private-key: ${{ secrets.APP_PRIVATE_KEY }}\n\n         - name: Use API\n           env:\n             GH_TOKEN: ${{ steps.generate-token.outputs.token }}\n           run: |\n             curl --request GET \\\n             --url \"https://api.github.com/repos/octocat/Spoon-Knife/issues\" \\\n             --header \"Accept: application/vnd.github+json\" \\\n             --header \"Authorization: Bearer $GH_TOKEN\"\n\n   ```\n\n</div>\n\n## 后续步骤\n\n有关更详细的指南，请参阅 [REST API 入门](/zh/rest/using-the-rest-api/getting-started-with-the-rest-api)。"}