在应用程序中使用 GitHub API

简介

本指南将帮助您构建 GitHub 应用程序并在服务器上运行它。 您构建的应用程序将为在安装该应用程序的仓库中所有打开的新议题添加标签。

此项目将引导您完成以下工作：

• 编程应用程序以侦听事件
• 使用 Octokit. rb 库执行 REST API 操作

一旦完成了这些步骤，您就可以使用整套 GitHub API 开发其他类型的集成。

基本要求

您可能会发现对以下内容有基本的了解很有帮助：

• GitHub 应用程序
• Web 挂钩
• Ruby 编程语言
• REST API
• Sinatra

但是，任何经验水平都能跟上步伐。 我们会一路提供所需信息的链接。

在开始之前，您需要执行以下操作：

1. 克隆在应用程序中使用 GitHub API 仓库。

   $ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git

   在目录中，您将找到包含本快速入门将要使用的模板代码的 template_server.rb 文件以及包含已完成项目代码的 server.rb 文件。

2. 按照“设置开发环境”快速入门中的步骤来配置和运行 template_server.rb 应用程序服务器。 如果您以前完成了设置开发环境以外的其他 GitHub 应用程序快速入门，您应该注册一个新 GitHub 应用程序并启动一个新 Smee 通道以用于本快速入门。

   本快速入门包含与设置开发环境快速入门相同的 template_server.rb 代码。 注：遵循设置开发环境快速入门的同时，请确保使用在应用程序中使用 GitHub API 仓库中包含的项目文件。

   如果在设置模板 GitHub 应用程序时遇到问题，请参阅疑难解答部分。

构建应用程序

现在您已经熟悉了 template_server.rb 代码，您将创建可将 needs-response 标签自动添加到安装该应用程序的仓库中所有已打开议题的代码。

template_server.rb 文件包含尚未自定义的应用程序模板代码。 在本文件中，您将看到一些用于处理 web 挂钩事件的占位符代码，以及用于初始化 Octokit.rb 客户端的一些其他代码。

以下是创建第一个 GitHub 应用程序要完成的步骤：

1. 更新应用程序权限
2. 添加事件处理
3. 创建新标签
4. 添加标签处理

步骤 1. 更新应用程序权限

如果您在首次注册应用程序时接受了默认权限，则意味着您的应用程序无法访问大多数资源。 对于此示例，您的应用程序将需要读取议题和写入标签的权限。

要更新应用程序的权限：

1. 从应用程序设置页面选择应用程序，然后单击边栏中的 Permissions & Webhooks（权限和 web 挂钩）。
2. 在“Permissions（权限）”部分，找到“Issues（议题）”，然后在其旁边的“Access（访问权限）”下拉列表中选择 Read & write（读取和写入）。 说明中表示，此选项将授予对议题和标签的访问权限，而这正是您所需要的。
3. 在“Subscribe to events（订阅事件）”部分，选择 Issues（议题）以订阅事件。
4. 单击页面底部的 Save changes（保存更改）。
5. 如果您已经在您的帐户上安装了应用程序，请检查您的电子邮件并按照链接接受新的权限。 每次更改应用程序的权限或 web 挂钩时，安装应用程序的用户（包括您自己）都需要在更改生效之前接受新权限。 您也可以通过导航到安装页面并单击应用程序旁边的“Configure（配置）”来接受新的权限。 您将在页面顶部看到一个横幅，让您知道应用程序正在请求不同的权限。 单击“Details（详细信息）”，然后单击“Accept new permissions（接受新权限）”。

太好了！ 您的应用程序现在有权限执行所需的任务。 现在，您可以添加代码使其正常工作。

步骤 2. 添加事件处理

应用程序需要做的第一件事是侦听打开的新议题。 现在您已订阅 Issues（议题）事件，您将开始接收 issues web 挂钩，它在某些与议题相关的操作发生时触发。 您可以根据要在代码中执行的特定操作来过滤此事件类型。

GitHub 将 web 挂钩有效负载作为 POST 请求发送。 因为您已将 Smee web 挂钩有效负载转发到 http://localhost/event_handler:3000，因此您的服务器将在 post '/event_handler' 路由中接收 POST 请求有效负载。

您在前提条件部分中下载的 template_server.rb 文件中已包括空 post '/event_handler' 路由。 空路由如下所示：

  post '/event_handler' do

    # # # # # # # # # # # #
    # ADD YOUR CODE HERE  #
    # # # # # # # # # # # #

    200 # success status
  end

通过添加以下代码，使用此路由来处理 issues 事件：

case request.env['HTTP_X_GITHUB_EVENT']
when 'issues'
  if @payload['action'] === 'opened'
    handle_issue_opened_event(@payload)
  end
end

GitHub 发送的每个事件都包含一个名为 HTTP_X_GITHUB_EVENT 的请求标头，它指示 POST 请求中的事件类型。 现在，您只关注 issues 事件类型。 每个事件都有一个附加的 action 字段，它指示触发事件的操作类型。 对于 issues，action 字段可以是 assigned、unassigned、labeled、unlabeled、opened、edited、milestoned、demilestoned、closed 或 reopened。

要测试事件处理程序，请尝试添加临时辅助方法。 稍后将在添加标签处理时进行更新。 现在，在代码的 helpers do 部分添加以下代码。 您可以将新方法放在其他任何辅助方法的上方或下方。 顺序无关紧要。

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

此方法接收 JSON 格式的事件有效负载作为参数。 这意味着您可以解析方法中的有效负载并深入挖掘所需的任何特定数据。 您可能会发现在某个时候检查整个有效负载很有帮助：尝试将 logger.debug 'An issue was opened! 更改为 logger.debug payload。 您看到的有效负载结构应该与 issues web 挂钩事件文档中显示的结构相匹配。

太好了！ 是时候测试更改了。

在浏览器中，访问安装应用程序的仓库。 在此仓库中打开一个新议题。 此议题可以谈论您喜欢的任何事情。 它仅用于测试。

回头查看终端时，您应该会在输出中看到一条消息：An issue was opened! 恭喜！ 您已将事件处理程序添加到应用程序中。 💪

步骤 3. 创建新标签

好，您的应用程序在有议题被打开时会告诉您。 现在，您希望它将标签 needs-response 添加到安装该应用程序的仓库中任何新打开的议题。

将标签添加到任何位置之前，您需要在仓库中创建自定义标签。 只需要这样做一次。 就本指南而言，请在 GitHub 上手动创建标签。 在仓库中，依次单击 Issues（议题）、Labels（标签），然后单击 New label（新建标签）。 将新标签命名为 needs-response。

现在，标签有了，您可以对应用程序进行编程，以使用 REST API 将标签添加到任何新打开的议题中。

步骤 4. 添加标签处理

恭喜！您来到了最后一步：向应用程序添加标签处理。 要完成此任务，您需要使用 Octokit.rb Ruby 库。

在 Octokit.rb 文档中，找到标签方法列表。 您要使用的方法是 add_labels_to_an_issue。

回到 template_server.rb，找到您以前定义的方法：

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

add_labels_to_an_issue 文档显示您需要向此方法传递三个参数：

• 仓库（"owner/name" 格式的字符串）
• 议题编号（整数）
• 标签（数组）

您可以解析有效负载以获取仓库和议题编号。 由于标签名称始终相同 (needs-response)，因此可以在标签数组中作为硬编码字符串传递它。 将这些片段放在一起，更新后的方法可能如下所示：

# When an issue is opened, add a label
def handle_issue_opened_event(payload)
  repo = payload['repository']['full_name']
  issue_number = payload['issue']['number']
  @installation_client.add_labels_to_an_issue(repo, issue_number, ['needs-response'])
end

尝试在测试仓库中打开一个新议题，看看会发生什么！ 如果没有任何反应，请尝试刷新。

在终端中看不到太多信息，但是您应该看到机器人用户已向该议题添加了标签。

如果是，恭喜！ 您已成功构建了一个可正常工作的应用程序！ 🎉

您可以在应用程序模板仓库的 server.rb 中查看最终代码。

有关接下来可以做什么的想法，请参阅“后续步骤”。

疑难解答

以下是一些常见问题和一些建议的解决方案。 如果您遇到任何其他问题，可以在 GitHub API 开发和支持论坛 中寻求帮助或建议。

• 问：我的服务器没有侦听事件！ Smee 客户端在终端窗口中运行，我通过打开新议题在 GitHub.com 上发送事件，但是在运行服务器的终端窗口中没有看到任何输出。

  答：您的应用程序设置中可能没有正确的 Smee 域。 访问应用程序设置页面，然后双击“使用 GitHub 注册新应用程序”中显示的的字段。 确保这些字段中的域与您在“启动新的 Smee 通道”中的 smee -u <unique_channel> 命令中使用的域相匹配。

• 问：我的应用程序无法正常工作！ 我打开了一个新议题，但是即使刷新后也没有给它添加标签。

  答：请确保满足以下所有条件：

  • 您在打开议题的仓库中安装了应用程序。
  • 您的 Smee 客户端正在终端窗口中运行。
  • 您的 web 服务器能够在其他终端窗口中无错误运行。
  • 您的应用程序具有对议题的读取和写入权限并且订阅了议题事件。
  • 您在更新权限后检查了电子邮件并接受了新权限。

结论

完成本指南后，您已了解开发 GitHub 应用程序的基本构建块！ 回顾一下：

• 编程应用程序以侦听事件
• 使用 Octokit. rb 库执行 REST API 操作

后续步骤

以下是有关接下来可以做什么的一些想法：

• 使用 GraphQL 重写应用程序！
• 使用 Probot 在 Node.js 中重写应用程序！
• 让应用程序检查议题上是否存在 needs-response 标签，如果否，则添加它。
• 当机器人成功添加标签时，在终端中显示消息。 （提示：将 needs-response 标签 ID 与有效负载中的标签 ID 进行比较，以作为显示消息的条件，这样只有在添加相关标签时才显示消息。）
• 向应用程序添加登录页面并为它连接 Sinatra 路由。
• 将代码移动到托管服务器（如 Heroku）。 不要忘记使用新域更新应用程序设置。
• 在 GitHub API 开发和支持论坛