注释 API

极狐GitLab 的 Notes API 管理附加到极狐GitLab 内容的评论和系统记录。Notes API：

• 创建和修改议题、合并请求、史诗、代码片段和提交中的评论。
• 检索有关对象更改的系统生成的备注。
• 提供排序和分页选项。
• 通过机密和内部标志控制可见性。
• 支持速率限制以防止滥用。

一些系统生成的备注被跟踪为单独的资源事件：

• 资源标签事件
• 资源状态事件
• 资源里程碑事件
• 资源权重事件
• 资源迭代事件

默认情况下，由于 API 结果是分页的，GET 请求一次返回 20 个结果。有关更多信息，请参见分页。

资源事件#

一些系统备注不属于此 API，但被记录为单独的事件：

• 资源标签事件
• 资源状态事件
• 资源里程碑事件
• 资源权重事件
• 资源迭代事件

备注分页#

默认情况下，由于 API 结果是分页的，GET 请求一次返回 20 个结果。

阅读更多关于分页。

速率限制#

为了帮助避免滥用，您可以限制用户每分钟的 Create 请求数量。参见备注速率限制。

议题#

列出项目议题备注#

获取单个议题的所有备注列表。

plaintext
GET /projects/:id/issues/:issue_iid/notes
GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at

json
1[
2  {
3    "id": 302,
4    "body": "closed",
5    "author": {
6      "id": 1,
7      "username": "pipin",
8      "email": "admin@example.com",
9      "name": "Pip",
10      "state": "active",
11      "created_at": "2013-09-30T13:46:01Z"
12    },
13    "created_at": "2013-10-02T09:22:45Z",
14    "updated_at": "2013-10-02T10:22:45Z",
15    "system": true,
16    "noteable_id": 377,
17    "noteable_type": "Issue",
18    "project_id": 5,
19    "noteable_iid": 377,
20    "resolvable": false,
21    "confidential": false,
22    "internal": false,
23    "imported": false,
24    "imported_from": "none"
25  },
26  {
27    "id": 305,
28    "body": "Text of the comment\r\n",
29    "author": {
30      "id": 1,
31      "username": "pipin",
32      "email": "admin@example.com",
33      "name": "Pip",
34      "state": "active",
35      "created_at": "2013-09-30T13:46:01Z"
36    },
37    "created_at": "2013-10-02T09:56:03Z",
38    "updated_at": "2013-10-02T09:56:03Z",
39    "system": true,
40    "noteable_id": 121,
41    "noteable_type": "Issue",
42    "project_id": 5,
43    "noteable_iid": 121,
44    "resolvable": false,
45    "confidential": true,
46    "internal": true,
47    "imported": false,
48    "imported_from": "none"
49  }
50]

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"

获取单个议题备注#

返回特定项目议题的单个备注。

plaintext
GET /projects/:id/issues/:issue_iid/notes/:note_id

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"

创建新的议题备注#

为单个项目议题创建新的备注。

plaintext
POST /projects/:id/issues/:issue_iid/notes

参数：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"

修改现有的议题备注#

修改现有议题的备注。

plaintext
PUT /projects/:id/issues/:issue_iid/notes/:note_id

参数：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636?body=note"

删除议题备注#

删除现有议题的备注。

plaintext
DELETE /projects/:id/issues/:issue_iid/notes/:note_id

参数：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636"

代码片段#

代码片段备注 API 适用于项目级别的代码片段，而不是个人代码片段。

列出所有代码片段备注#

获取单个代码片段的所有备注列表。代码片段备注是用户可以发布到代码片段的评论。

plaintext
GET /projects/:id/snippets/:snippet_id/notes
GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"

获取单个代码片段备注#

返回给定代码片段的单个备注。

plaintext
GET /projects/:id/snippets/:snippet_id/notes/:note_id

参数：

json
1{
2  "id": 302,
3  "body": "closed",
4  "author": {
5    "id": 1,
6    "username": "pipin",
7    "email": "admin@example.com",
8    "name": "Pip",
9    "state": "active",
10    "created_at": "2013-09-30T13:46:01Z"
11  },
12  "created_at": "2013-10-02T09:22:45Z",
13  "updated_at": "2013-10-02T10:22:45Z",
14  "system": true,
15  "noteable_id": 377,
16  "noteable_type": "Issue",
17  "project_id": 5,
18  "noteable_iid": 377,
19  "resolvable": false,
20  "confidential": false,
21  "internal": false,
22  "imported": false,
23  "imported_from": "none"
24}

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"

创建新的代码片段备注#

为单个代码片段创建新的备注。代码片段备注是用户对代码片段的评论。如果创建的备注主体仅包含表情符号反应，极狐GitLab 将返回此对象。

plaintext
POST /projects/:id/snippets/:snippet_id/notes

参数：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"

修改现有的代码片段备注#

修改现有代码片段的备注。

plaintext
PUT /projects/:id/snippets/:snippet_id/notes/:note_id

参数：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/1659?body=note"

删除代码片段备注#

删除现有代码片段的备注。

plaintext
DELETE /projects/:id/snippets/:snippet_id/notes/:note_id

参数：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659"

合并请求#

列出所有合并请求备注#

获取单个合并请求的所有备注列表。

plaintext
GET /projects/:id/merge_requests/:merge_request_iid/notes
GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=updated_at

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes"

获取单个合并请求备注#

返回给定合并请求的单个备注。

plaintext
GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id

参数：

json
1{
2  "id": 301,
3  "body": "Comment for MR",
4  "author": {
5    "id": 1,
6    "username": "pipin",
7    "email": "admin@example.com",
8    "name": "Pip",
9    "state": "active",
10    "created_at": "2013-09-30T13:46:01Z"
11  },
12  "created_at": "2013-10-02T08:57:14Z",
13  "updated_at": "2013-10-02T08:57:14Z",
14  "system": false,
15  "noteable_id": 2,
16  "noteable_type": "MergeRequest",
17  "project_id": 5,
18  "noteable_iid": 2,
19  "resolvable": false,
20  "confidential": false,
21  "internal": false
22}

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1"

创建新的合并请求备注#

为单个合并请求创建新的备注。备注不附加到合并请求中的特定行。有关更精细控制的其他方法，请参见提交 API 中的提交评论和讨论 API 中的在合并请求差异中创建新的线程。如果创建的备注主体仅包含表情符号反应，极狐GitLab 将返回此对象。

plaintext
POST /projects/:id/merge_requests/:merge_request_iid/notes

参数：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"

修改现有的合并请求备注#

修改现有合并请求的备注。

plaintext
PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id

参数：

shell
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"

删除合并请求备注#

删除现有合并请求的备注。

plaintext
DELETE /projects/:id/merge_requests/:merge_request_iid/notes/:note_id

参数：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"

史诗#

列出所有史诗备注#

获取单个史诗的所有备注列表。史诗备注是用户可以发布到史诗的评论。

plaintext
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"

获取单个史诗备注#

返回给定史诗的单个备注。

plaintext
GET /groups/:id/epics/:epic_id/notes/:note_id

参数：

json
1{
2  "id": 302,
3  "body": "Epic note",
4  "author": {
5    "id": 1,
6    "username": "pipin",
7    "email": "admin@example.com",
8    "name": "Pip",
9    "state": "active",
10    "created_at": "2013-09-30T13:46:01Z"
11  },
12  "created_at": "2013-10-02T09:22:45Z",
13  "updated_at": "2013-10-02T10:22:45Z",
14  "system": true,
15  "noteable_id": 11,
16  "noteable_type": "Epic",
17  "project_id": 5,
18  "noteable_iid": 11,
19  "resolvable": false,
20  "confidential": false,
21  "internal": false,
22  "imported": false,
23  "imported_from": "none"
24}

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"

创建新的史诗备注#

为单个史诗创建新的备注。史诗备注是用户可以发布到史诗的评论。如果创建的备注主体仅包含表情符号反应，极狐GitLab 将返回此对象。

plaintext
POST /groups/:id/epics/:epic_id/notes

参数：

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes?body=note"

修改现有的史诗备注#

修改现有史诗的备注。

plaintext
PUT /groups/:id/epics/:epic_id/notes/:note_id

参数：

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1?body=note"

删除史诗备注#

删除现有史诗的备注。

plaintext
DELETE /groups/:id/epics/:epic_id/notes/:note_id

参数：

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"