我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

使用内容附件

内容附件允许 GitHub 应用程序在 GitHub 中为链接到注册域的 URL 提供更多信息。 GitHub 可渲染应用程序在正文或者议题或拉取请求注释中的 URL 下提供的信息。

本文内容

注:内容附件 API 目前处于公测阶段,仅用于 GitHub 应用程序。 在此期间,功能和要求可能会随时更改。

关于内容附件

GitHub 应用程序可以注册将触发 content_reference 事件的域。 当有人在正文或者议题或拉取请求的注释中包含链接到注册域的 URL 时,应用程序会收到 content_reference web 挂钩。 您可以使用内容附件直观地为添加到议题或拉取请求的 URL 提供更多的上下文或数据。 URL 必须是完全合格的 URL,以 http://https:// 开头。 作为 Markdown 链接一部分的 URL 将被忽略,不会触发 content_reference 事件。

在使用 内容附件 API 之前,您需要为 GitHub 应用程序配置内容引用:

  • 为应用程序提供对“内容引用”的 Read & write 权限。
  • 配置“内容引用”权限时,注册最多 5 个有效且可公开访问的域。 配置内容引用域时不要使用 IP 地址。 您可以注册域名 (example.com) 或子域 (subdomain.example.com)。
  • 让应用程序订阅“内容引用”事件。

将应用程序安装到仓库中后,仓库中包含注册域 URL 的议题或拉取请求注释将生成内容引用事件。 应用程序必须在发布内容引用 URL 后六小时内创建内容附件。

内容附件不会追溯更新 URL。 只有在您根据上述要求配置了应用程序,并且有人在其仓库中安装应用程序之后,它才会更新添加到议题或拉取请求中的 URL。

有关配置 GitHub 应用程序权限和事件订阅所需的步骤,请参阅“创建 GitHub 应用程序”或“编辑 GitHub 应用程序的权限”。

实现内容附件流程

内容附件流程向您显示议题或拉取请求中的 URL、content_reference web 挂钩事件以及使用额外信息更新议题或拉取请求所需调用的 REST API 端点之间的关系。

步骤 1. 使用关于内容附件中的指南设置应用程序。 您也可以根据 Probot 应用程序示例开始使用内容附件。

步骤 2. 将注册域的 URL 添加到议题或拉取请求。 必须使用以 http://https:// 开头的完全合格 URL。

添加到议题的 URL

步骤 3.应用程序将收到带有操作 createdcontent_reference web 挂钩

{
  "action": "created",
  "content_reference": {
    "id": 17,
    "node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
    "reference": "errors.ai"
  },
  "repository": {
    "full_name": "Codertocat/Hello-World",
  },
  "sender": {...},
  "installation": {
    "id": 371641,
    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
  }
}

步骤 4. 应用程序使用 content_reference idrepository full_name 字段以使用 REST API 创建内容附件。 您还需要 installation id 以验证为 GitHub 应用程序安装设施

注:要在预览期间访问 内容附件 API,您必须在 Accept 标头中提供自定义媒体类型

application/vnd.github.corsair-preview+json

警告: 在预览期间,API 可能会更改,恕不另行通知。 预览功能不支持用于生产。 如果遇到任何问题,请联系 您的站点管理员。

body 参数可包含 Markdown:

<pre><code class="hljs language-shell">curl -X POST \
  https://api.github.com/repos/Codertocat/Hello-World/content_references/17/attachments \
  -H 'Accept: application/vnd.github.corsair-preview+json' \
  -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
  -d '{
    "title": "[A-1234] Error found in core/models.py file",
    "body": "You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
}'</code></pre>

有关创建和安装令牌的更多信息,请参阅“验证为 GitHub 应用程序”。

步骤 5. 在拉取请求或议题注释中,您将看到新的内容附件显示在链接下:

附加到议题引用的内容

在 GraphQL 中使用内容附件

我们在 content_reference web 挂钩中提供 node_id,以便您可以在 GraphQL API 中引用 createContentAttachment 突变。

注:要在预览期间访问 内容附件 API,您必须在 Accept 标头中提供自定义媒体类型

application/vnd.github.corsair-preview+json

警告: 在预览期间,API 可能会更改,恕不另行通知。 预览功能不支持用于生产。 如果遇到任何问题,请联系 您的站点管理员。

例如:

mutation {
  createContentAttachment(input: {
    contentReferenceId: "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1",
    title: "[A-1234] Error found in core/models.py file",
    body:"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
  }) {
    contentAttachment {
      ... on ContentAttachment {
        id
        title
        body
      }
    }
  }
}

示例 cURL:

curl -X "POST" "https://api.github.com/graphql" \
     -H 'Authorization: Bearer $INSTALLATION_TOKEN' \
     -H 'Accept: application/vnd.github.corsair-preview+json' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "query": "mutation {\\n  createContentAttachment(input:{contentReferenceId: \\"MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1\\", title:\\"[A-1234] Error found in core/models.py file\\", body:\\"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n\self.save()\\"}) {\\n    contentAttachment {\\n      id,\\n      title,\\n      body\\n    }\\n  }\\n}"
}'

有关 node_id 的更多信息,请参阅“使用全局节点 ID”。

使用 Probot 和 GitHub 应用程序清单的示例

要快速设置可使用 内容附件 API 的 GitHub 应用程序,您可以使用 Probot。 要了解 Probot 如何使用 GitHub 应用程序清单,请参阅“从清单创建 GitHub 应用程序”。

要创建 Probot 应用程序,请按照以下步骤操作:

  1. 生成新的 GitHub 应用程序

  2. 打开您创建的项目,自定义 app.yml 文件中的设置。 订阅 content_reference 事件并启用 content_references 写入权限:

     default_events:
       - content_reference
     # The set of permissions needed by the GitHub App. The format of the object uses
     # the permission name for the key (for example, issues) and the access type for
     # the value (for example, write).
     # Valid values are `read`, `write`, and `none`
     default_permissions:
       content_references: write
    
     content_references:
       - type: domain
         value: errors.ai
       - type: domain
         value: example.org
    
  3. 将此代码添加到 index.js 文件以处理 content_reference 事件并调用 REST API:

    module.exports = app => {
      // Your code here
      app.log('Yay, the app was loaded!')
       app.on('content_reference.created', async context => {
        console.log('Content reference created!', context.payload)
         // Call the "Create a content reference" REST endpoint
        await context.github.request({
          method: 'POST',
          headers: { accept: 'application/vnd.github.corsair-preview+json' },
          url: `/repos/${context.payload.repository.full_name}/content_references/${context.payload.content_reference.id}/attachments`,
          // Parameters
          title: '[A-1234] Error found in core/models.py file',
          body: 'You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\nself.save()'
        })
      })
    }
    
  4. 在本地运行 GitHub 应用程序。 导航到 http://localhost:3000, 然后单击 Register GitHub App(注册 GitHub 应用程序)按钮:

    注册 Probot GitHub 应用程序

  5. 在测试仓库中安装应用程序。

  6. 在测试仓库中创建议题。

  7. 将注释添加到您打开的议题,包括您在 app.yml 文件中配置的 URL。

  8. 查看议题注释,您将看到如下所示的更新:

    附加到议题引用的内容

此文档对您有帮助吗? 隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。