{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
极狐GitLab 的 Notes API 管理附加到极狐GitLab 内容的评论和系统记录。Notes API:
- 创建和修改议题、合并请求、史诗、代码片段和提交中的评论。
- 检索有关对象更改的系统生成的备注。
- 提供排序和分页选项。
- 通过机密和内部标志控制可见性。
- 支持速率限制以防止滥用。
一些系统生成的备注被跟踪为单独的资源事件:
默认情况下,由于 API 结果是分页的,GET
请求一次返回 20 个结果。有关更多信息,请参见分页。
资源事件
一些系统备注不属于此 API,但被记录为单独的事件:
备注分页
默认情况下,由于 API 结果是分页的,GET
请求一次返回 20 个结果。
阅读更多关于分页。
速率限制
为了帮助避免滥用,您可以限制用户每分钟的 Create
请求数量。参见备注速率限制。
议题
列出项目议题备注
获取单个议题的所有备注列表。
GET /projects/:id/issues/:issue_iid/notes
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
issue_iid |
integer | 是 | 议题的 IID |
sort |
string | 否 | 按 asc 或 desc 顺序返回议题备注。默认是 desc
|
order_by |
string | 否 | 按 created_at 或 updated_at 字段返回议题备注。默认是 created_at
|
[
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
},
{
"id": 305,
"body": "Text of the comment\r\n",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:56:03Z",
"updated_at": "2013-10-02T09:56:03Z",
"system": true,
"noteable_id": 121,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 121,
"resolvable": false,
"confidential": true,
"internal": true,
"imported": false,
"imported_from": "none"
}
]
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"
获取单个议题备注
返回特定项目议题的单个备注。
GET /projects/:id/issues/:issue_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
issue_iid |
integer | 是 | 项目议题的 IID |
note_id |
integer | 是 | 议题备注的 ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
创建新的议题备注
为单个项目议题创建新的备注。
POST /projects/:id/issues/:issue_iid/notes
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
issue_iid |
integer | 是 | 议题的 IID。 |
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
confidential |
boolean | 否 |
已弃用: 计划在极狐GitLab 16.0 中删除并重命名为 internal 。备注的机密标志。默认是 false。 |
internal |
boolean | 否 | 备注的内部标志。当同时提交两个参数时,覆盖 confidential 。默认是 false。 |
created_at |
string | 否 | 日期时间字符串,ISO 8601 格式。必须在 1970-01-01 之后。例如:2016-03-11T03:45:40Z (需要管理员或项目/群组所有者权限) |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
修改现有的议题备注
修改现有议题的备注。
PUT /projects/:id/issues/:issue_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径。 |
issue_iid |
integer | 是 | 议题的 IID。 |
note_id |
integer | 是 | 备注的 ID。 |
body |
string | 否 | 备注的内容。限制为 1,000,000 个字符。 |
confidential |
boolean | 否 | 已弃用: 计划在极狐GitLab 16.0 中删除。备注的机密标志。默认是 false。 |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636?body=note"
删除议题备注
删除现有议题的备注。
DELETE /projects/:id/issues/:issue_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
issue_iid |
integer | 是 | 议题的 IID |
note_id |
integer | 是 | 备注的 ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636"
代码片段
代码片段备注 API 适用于项目级别的代码片段,而不是个人代码片段。
列出所有代码片段备注
获取单个代码片段的所有备注列表。代码片段备注是用户可以发布到代码片段的评论。
GET /projects/:id/snippets/:snippet_id/notes
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
snippet_id |
integer | 是 | 项目代码片段的 ID |
sort |
string | 否 | 按 asc 或 desc 顺序返回代码片段备注。默认是 desc
|
order_by |
string | 否 | 按 created_at 或 updated_at 字段返回代码片段备注。默认是 created_at
|
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"
获取单个代码片段备注
返回给定代码片段的单个备注。
GET /projects/:id/snippets/:snippet_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
snippet_id |
integer | 是 | 项目代码片段的 ID |
note_id |
integer | 是 | 代码片段备注的 ID |
{
"id": 302,
"body": "closed",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 377,
"noteable_type": "Issue",
"project_id": 5,
"noteable_iid": 377,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
}
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"
创建新的代码片段备注
为单个代码片段创建新的备注。代码片段备注是用户对代码片段的评论。如果创建的备注主体仅包含表情符号反应,极狐GitLab 将返回此对象。
POST /projects/:id/snippets/:snippet_id/notes
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
snippet_id |
integer | 是 | 代码片段的 ID |
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
created_at |
string | 否 | 日期时间字符串,ISO 8601 格式。例如:2016-03-11T03:45:40Z (需要管理员或项目/群组所有者权限) |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"
修改现有的代码片段备注
修改现有代码片段的备注。
PUT /projects/:id/snippets/:snippet_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
snippet_id |
integer | 是 | 代码片段的 ID |
note_id |
integer | 是 | 代码片段备注的 ID |
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/1659?body=note"
删除代码片段备注
删除现有代码片段的备注。
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
snippet_id |
integer | 是 | 代码片段的 ID |
note_id |
integer | 是 | 备注的 ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659"
合并请求
列出所有合并请求备注
获取单个合并请求的所有备注列表。
GET /projects/:id/merge_requests/:merge_request_iid/notes
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
merge_request_iid |
integer | 是 | 项目合并请求的 IID |
sort |
string | 否 | 按 asc 或 desc 顺序返回合并请求备注。默认是 desc
|
order_by |
string | 否 | 按 created_at 或 updated_at 字段返回合并请求备注。默认是 created_at
|
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes"
获取单个合并请求备注
返回给定合并请求的单个备注。
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
merge_request_iid |
integer | 是 | 项目合并请求的 IID |
note_id |
integer | 是 | 合并请求备注的 ID |
{
"id": 301,
"body": "Comment for MR",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T08:57:14Z",
"updated_at": "2013-10-02T08:57:14Z",
"system": false,
"noteable_id": 2,
"noteable_type": "MergeRequest",
"project_id": 5,
"noteable_iid": 2,
"resolvable": false,
"confidential": false,
"internal": false
}
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1"
创建新的合并请求备注
为单个合并请求创建新的备注。备注不附加到合并请求中的特定行。有关更精细控制的其他方法,请参见提交 API 中的提交评论和讨论 API 中的在合并请求差异中创建新的线程。如果创建的备注主体仅包含表情符号反应,极狐GitLab 将返回此对象。
POST /projects/:id/merge_requests/:merge_request_iid/notes
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
merge_request_iid |
integer | 是 | 项目合并请求的 IID |
created_at |
string | 否 | 日期时间字符串,ISO 8601 格式。例如:2016-03-11T03:45:40Z (需要管理员或项目/群组所有者权限) |
internal |
boolean | 否 | 备注的内部标志。默认是 false。 |
merge_request_diff_head_sha |
string | 否 |
/merge 快速操作所需的头提交的 SHA,确保在发送 API 请求后合并请求未更新。 |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"
修改现有的合并请求备注
修改现有合并请求的备注。
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
merge_request_iid |
integer | 是 | 项目合并请求的 IID |
note_id |
integer | 否 | 备注的 ID |
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
confidential |
boolean | 否 | 已弃用: 计划在极狐GitLab 16.0 中删除。备注的机密标志。默认是 false。 |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1?body=note"
删除合并请求备注
删除现有合并请求的备注。
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或 URL 编码路径 |
merge_request_iid |
integer | 是 | 合并请求的 IID |
note_id |
integer | 是 | 备注的 ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"
史诗
{{< details >}}
- Tier: Premium, Ultimate
- Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< alert type=”warning” >}}
史诗 REST API 在极狐GitLab 17.0 中已弃用,计划在 API 的 v5 中移除。
{{< /alert >}}
列出所有史诗备注
获取单个史诗的所有备注列表。史诗备注是用户可以发布到史诗的评论。
{{< alert type=”note” >}}
史诗备注 API 使用史诗 ID 而不是史诗 IID。如果使用史诗的 IID,极狐GitLab 将返回 404 错误或错误史诗的备注。与议题备注 API和合并请求备注 API不同。
{{< /alert >}}
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 群组的 ID 或 URL 编码路径 |
epic_id |
integer | 是 | 群组史诗的 ID |
sort |
string | 否 | 按 asc 或 desc 顺序返回史诗备注。默认是 desc
|
order_by |
string | 否 | 按 created_at 或 updated_at 字段返回史诗备注。默认是 created_at
|
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"
获取单个史诗备注
返回给定史诗的单个备注。
GET /groups/:id/epics/:epic_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 群组的 ID 或 URL 编码路径 |
epic_id |
integer | 是 | 史诗的 ID |
note_id |
integer | 是 | 备注的 ID |
{
"id": 302,
"body": "Epic note",
"author": {
"id": 1,
"username": "pipin",
"email": "admin@example.com",
"name": "Pip",
"state": "active",
"created_at": "2013-09-30T13:46:01Z"
},
"created_at": "2013-10-02T09:22:45Z",
"updated_at": "2013-10-02T10:22:45Z",
"system": true,
"noteable_id": 11,
"noteable_type": "Epic",
"project_id": 5,
"noteable_iid": 11,
"resolvable": false,
"confidential": false,
"internal": false,
"imported": false,
"imported_from": "none"
}
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"
创建新的史诗备注
为单个史诗创建新的备注。史诗备注是用户可以发布到史诗的评论。如果创建的备注主体仅包含表情符号反应,极狐GitLab 将返回此对象。
POST /groups/:id/epics/:epic_id/notes
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
epic_id |
integer | 是 | 史诗的 ID |
id |
integer or string | 是 | 群组的 ID 或 URL 编码路径 |
confidential |
boolean | 否 |
已弃用: 计划在极狐GitLab 16.0 中删除并重命名为 internal 。备注的机密标志。默认是 false 。 |
internal |
boolean | 否 | 备注的内部标志。当同时提交两个参数时,覆盖 confidential 。默认是 false 。 |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"
修改现有的史诗备注
修改现有史诗的备注。
PUT /groups/:id/epics/:epic_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 群组的 ID 或 URL 编码路径 |
epic_id |
integer | 是 | 史诗的 ID |
note_id |
integer | 是 | 备注的 ID |
body |
string | 是 | 备注的内容。限制为 1,000,000 个字符。 |
confidential |
boolean | 否 | 已弃用: 计划在极狐GitLab 16.0 中删除。备注的机密标志。默认是 false。 |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1?body=note"
删除史诗备注
删除现有史诗的备注。
DELETE /groups/:id/epics/:epic_id/notes/:note_id
参数:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 群组的 ID 或 URL 编码路径 |
epic_id |
integer | 是 | 史诗的 ID |
note_id |
integer | 是 | 备注的 ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"