{"meta":{"title":"使用 URL 参数注册GitHub应用","intro":"可以使用 URL 查询参数来帮助其他人通过预先选择的特定配置快速设置新的 GitHub App。","product":"应用","breadcrumbs":[{"href":"/zh/apps","title":"应用"},{"href":"/zh/apps/sharing-github-apps","title":"共享 GitHub Apps"},{"href":"/zh/apps/sharing-github-apps/registering-a-github-app-using-url-parameters","title":"应用查询参数"}],"documentType":"article"},"body":"# 使用 URL 参数注册GitHub应用\n\n可以使用 URL 查询参数来帮助其他人通过预先选择的特定配置快速设置新的 GitHub App。\n\n## 关于用于注册 GitHub Apps\n\n的 URL 参数\n\n可以使用 URL 参数预先选择新 GitHub App 注册的配置设置，并与其他人共享自定义链接。 该链接会让用户转到 GitHub App 注册页面，其中应用设置将根据 URL 中包含的 URL 参数预先填充。\n\n对于希望客户在其个人帐户或组织中设置具有特定规范的应用的集成商，或者对于使用 GitHub Enterprise Server 但无法从 GitHub Marketplace 安装应用的客户，此方法非常有用。\n\n或者，可以创建 GitHub App 清单。 有关详细信息，请参阅“[从manifest文件注册GitHub应用](/zh/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)”。\n\n## 使用查询参数创建自定义配置 URL\n\n若要在个人或组织帐户上为 GitHub App 创建自定义配置 URL，请在以下基 URL 后面添加查询参数。\n\n* 若要在个人帐户上注册应用，请将 URL 参数添加到：`https://github.com/settings/apps/new`\n* 若要在组织帐户上注册应用，请将 URL 参数添加到：`https://github.com/organizations/ORGANIZATION/settings/apps/new`。 将 `ORGANIZATION` 替换为要让客户在其中注册应用的组织的名称。\n\n在应用注册页上，注册应用的人员可以在提交应用之前编辑预先选择的值。 如果没有在 URL 查询字符串中包含所需值（如 `name`）的参数，则注册应用的人员需要在注册该应用之前输入值。\n\n例如，以下 URL 可在个人帐户上注册名为 `octocat-github-app` 的新公共应用。 使用查询参数，URL 可预配置说明和回叫 URL。 此过程还选择 `checks` 的读取和写入权限、使用 `webhook_active` 参数激活 Webhook、订阅 `check_run` 和 `check_suite` 的 Webhook 事件，并选择在安装过程中请求用户授权 (OAuth) 的选项：\n\n```text\nhttps://github.com/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite\n```\n\n## GitHub App 配置参数\n\n可以使用以下查询参数为 GitHub App 注册选择特定配置。 例如，若要将应用命名为“octocat-github-app”，查询字符串将包含 `name=octocat-github-app`。\n\n| 参数名称                       | 类型                 | 说明                                                                                                                                                                                                                                                                               |\n| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`                     | `string`           | GitHub App 的名称。 给应用程序一个清晰简洁的名称。 你的应用不能与现有的 GitHub 用户同名，除非该名称是你自己的用户或组织名称。 当你的集成执行操作时，应用程序名称的缓存版本将显示在用户界面上。                                                                                                                                                                       |\n| `description`              | `string`           | GitHub App 的说明。                                                                                                                                                                                                                                                                  |\n| `url`                      | `string`           | 您的 GitHub App 网站主页的完整 URL。                                                                                                                                                                                                                                                       |\n| `callback_urls`            | `array of strings` | 在用户授权安装后重定向到的完整 URL。 您可以提供最多 10 个回叫 URL。 如果应用需要生成用户访问令牌，则会使用这些 URL。 例如，`callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`。 有关详细信息，请参阅“[关于用户授权回调 URL](/zh/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)”。 |\n| `request_oauth_on_install` | `boolean`          | 如果你的应用使用 OAuth 流授权用户，你可将此选项设置为 `true`，以允许用户在安装应用时授权它，从而省去一个步骤。 如果选择此选项，`setup_url` 将不可用，并且用户将在安装应用后被重定向到 `callback_url`。                                                                                                                                                         |\n| `setup_url`                | `string`           | 在用户安装 GitHub App 后重定向到的完整 URL（如果应用程序在安装之后需要额外设置）。 有关详细信息，请参阅“[关于设置 URL](/zh/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)”。                                                                                                                             |\n| `setup_on_update`          | `boolean`          | 设置为 `true` 可在更新安装后（例如在添加或删除存储库之后）将用户重定向到设置 URL。                                                                                                                                                                                                                                  |\n| `public`                   | `boolean`          | 当 GitHub App 可供公众使用时，设置为 `true`；当它仅供应用的所有者访问时，设置为 `false`。 此参数不适用于由企业拥有的应用。                                                                                                                                                                                                      |\n| `webhook_active`           | `boolean`          | 设置为 `true` 以启用 Webhook。 默认情况下，Webhook 处于禁用状态。                                                                                                                                                                                                                                    |\n| `webhook_url`              | `string`           | 要向其发送 web 挂钩事件有效负载的完整 URL。                                                                                                                                                                                                                                                       |\n| `events`                   | `array of strings` | Webhook 事件。 某些 Webhook 事件需要你对资源有 `read` 或 `write` 权限，才能在注册新 GitHub App 时选择事件。 有关详细信息，请参阅 [GitHub App Webhook 事件](#github-app-webhook-events)一节。 您可以在查询字符串中选择多个事件。 例如，`events[]=public&events[]=label`。                                                                           |\n| `single_file_name`         | `string`           | 这是一种范围狭窄的权限，允许应用程序访问任何仓库中的单个文件。 将 `single_file` 权限设置为 `read` 或 `write` 时，此字段提供 GitHub App 将要管理的单个文件的路径。 如果需要托管多个文件，请参阅下文：`single_file_paths`。                                                                                                                                    |\n| `single_file_paths`        | `array of strings` | 这允许应用程序访问仓库中的最多 10 个指定文件。 将 `single_file` 权限设置为 `read` 或 `write` 时，此数组可存储 GitHub App 将要管理的最多 10 个文件的路径。 这些文件都接收由 `single_file` 设置的相同权限，没有单独的权限。 配置了两个或更多文件时，API 将返回 `multiple_single_files=true`，否则它将返回 `multiple_single_files=false`。                                           |\n\n## GitHub App 权限\n\n您可以使用查询参数来选择 GitHub App 注册的权限。 对于 URL 查询参数，请使用权限名称作为查询参数名称，并将查询值设置为该权限集的可能值之一。\n\n例如，要在 `contents` 的用户界面中选择“读取和写入”权限，查询字符串将包含 `contents=write`。 若要在 `blocking` 的用户界面中选择“只读”权限，查询字符串将包含 `blocking=read`。 若要在 `checks` 的用户界面中选择“No access”，查询字符串将不包含 `checks` 权限。\n\n有关权限和 GitHub Apps\n的详细信息，请参阅“[为GitHub应用选择权限](/zh/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)”。 若要查看可使用权限的列表及其参数化名称，请参阅 [管理个人访问令牌](/zh/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#account-permissions)。\n\n## GitHub App web 挂钩事件\n\n可以使用查询参数启用 GitHub App Webhook，设置 Webhook URL，并订阅应用程序，以在特定事件中接收 Webhook 有效负载。\n\n若要启用 GitHub App Webhook，请在查询字符串中使用 `webhook_active=true`。 若要指定要向其发送 Webhook 事件有效负载的完整 URL，请在查询字符串中使用 `webhook_url`。 要为应用订阅特定 Webhook 有效负载事件，请使用 `events[]` 作为查询参数名称，并将查询值设置为 Webhook 事件的名称。 有关可能的 Webhook 事件以及订阅每个事件所需的 GitHub App 权限的详细信息，请参阅“[Webhook 事件和有效负载](/zh/webhooks-and-events/webhooks/webhook-events-and-payloads)”。\n\n例如，若要订阅 GitHub App 以接收与提交评论相关的活动的 Webhook 有效负载，查询字符串将包含 `&webhook_active=true&webhook_url=https://example.com&events[]=commit_comment`。 请注意，`commit_comment` Webhook 事件要求 GitHub App 至少具有“内容”存储库权限的读取级别访问权限。 因此，查询字符串还应包含一个参数，用于将 `contents` 权限设置为 `read` 或 `write`。 有关详细信息，请参阅 [GitHub 应用权限](#github-app-permissions)。\n\n无法使用查询参数设置 Webhook 密钥的值。 如果应用需要密钥来保护其 Webhook，那么注册应用的人必须在 GitHub UI 中设置密钥的值。\n\n有关 Webhook 和 GitHub Apps\n的详细信息，请参阅《[将 Webhook 与 GitHub 应用配合使用](/zh/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)》。"}