注:内容附件 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。
步骤 3.应用程序将收到带有操作 created
的 content_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
id
和 repository
full_name
字段以使用 REST API 创建内容附件。 您还需要 installation
id
以验证为 GitHub 应用程序安装设施。
注:要在预览期间访问 内容附件 API,您必须在 Accept
� �头中提供自定义媒体类型:
application/vnd.github.corsair-preview+json
警告: 在预览期间,API 可能会更改,恕不另行通知。 预览功能不支持用于生产。 如果遇到任何问题,请联系 您的网站管理员。
body
参数可包含 Markdown:
curl -X POST \
http(s)://[hostname]/api/v3/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()"
}'
有关创建和安装令牌的更多信息,请参阅“验证为 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" "http(s)://[hostname]/api/v3/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 应用程序,请按照以下步骤操作:
-
打开您创建的项目,自定义
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
-
将此代� �添� 到
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()' }) }) }
-
在本地运行 GitHub 应用程序。 导航到
http://localhost:3000
, 然后单击 Register GitHub App(注册 GitHub 应用程序)按钮: -
在测试仓库中安装应用程序。
-
在测试仓库中创建议题。
-
将注释添� 到您打开的议题,包括您在
app.yml
文件中配置的 URL。 -
查看议题注释,您将看到如下所示的更新: