备注 API (BASIC ALL)

备注是对以下内容进行的评论:

  • 代码片段
  • 议题
  • 合并请求
  • 史诗

包括系统备注,它们是关于对象更改的备注(例如,指派人发生了更改,极狐GitLab 会发布系统备注)。

资源事件

  • 状态、里程碑和权重事件引入于极狐GitLab 13.3。
  • 迭代事件引入于极狐GitLab 13.4。

有些系统备注不属于 API,被记录为单独事件:

备注分页

默认情况下,GET 请求一次返回 20 个结果,因为 API 结果是分页的。

阅读更多关于分页的内容。

速率限制

为了避免滥用,您可以为您的用户设置每分钟所能进行的 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 yes ID 或 URL 编码的项目路径
issue_iid integer yes 议题 IID
sort string no 返回以 ascdesc 顺序排序的议题备注。默认为 desc
order_by string no 返回按照 created_atupdated_at 字段排序的议题备注。 默认为 created_at
[
  {
    "id": 302,
    "body": "closed",
    "attachment": null,
    "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
  },
  {
    "id": 305,
    "body": "Text of the comment\r\n",
    "attachment": null,
    "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
  }
]
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes"

获取单个议题备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
issue_iid integer yes 项目议题 IID
note_id integer yes 议题备注 ID
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"

创建新议题备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
issue_iid integer yes 议题 IID
body string yes 备注内容。限制为 1,000,000 个字符
confidential boolean no 废弃:计划在 16.0 中移除并重命名为 internal。备注的私密标记。默认为 False
created_at string no 日期时间字符串,格式为 ISO 8601,且必需在 1970-01-01 之后。例如:2016-03-11T03:45:40Z(需要管理员或项目/群组拥有者权限)
internal boolean no 备注的内部标记。当两个参数都提交时,覆盖 confidential。默认为 False
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
issue_iid integer yes 议题 IID
note_id integer yes 备注 ID
body string no 备注内容。限制为 1,000,000 个字符
confidential boolean no 已废弃: 计划在 16.0 中移除。备注的私密标记。默认为 False
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
issue_iid integer yes 议题 IID
note_id integer yes 备注 ID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
snippet_id integer yes 项目代码片段 ID
sort string no 返回以 ascdesc 顺序排序的代码片段备注。默认为 desc
order_by string no 返回按照 created_atupdated_at 字段排序的代码片段备注。默认为 created_at
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes"

获取单个代码片段备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
snippet_id integer yes 项目代码片段 ID
note_id integer yes 代码片段备注 ID
{
  "id": 302,
  "body": "closed",
  "attachment": null,
  "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
}
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11"

创建新代码片段备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
snippet_id integer yes 代码片段 ID
body string yes 备注内容。限制为 1,000,000 个字符串
created_at string no 日期时间字符串。格式为 ISO 8601。例如:2016-03-11T03:45:40Z(需要管理员或项目/群组拥有者权利)
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
snippet_id integer yes 代码片段 ID
note_id integer yes 代码片段备注 ID
body string yes 备注内容。限制为 1,000,000 个字符
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
snippet_id integer yes 代码片段 ID
note_id integer yes 备注 ID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
merge_request_iid integer yes 项目合并请求 IID
sort string no 返回以 ascdesc 顺序排序的合并请求备注。默认为 desc
order_by string no 返回按照 created_atupdated_at 字段排序的合并请求备注。默认为 created_at
curl --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
merge_request_iid integer yes 项目合并请求 IID
note_id integer yes 合并请求备注 ID
{
  "id": 301,
  "body": "Comment for MR",
  "attachment": null,
  "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>" "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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
merge_request_iid integer yes 项目合并请求 IID
body string yes 备注内容。限制为 1,000,000 个字符
created_at string no 日期时间字符串。格式为 ISO 8601。例如:2016-03-11T03:45:40Z(需要管理员或项目/群组拥有者权限)
merge_request_diff_head_sha string no /merge 快速操作 需要。head 提交的 SHA,确保在发送 API 请求后合并请求未更新

修改现存合并请求备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的项目路径
merge_request_iid integer yes 项目合并请求 IID
note_id integer no 备注 ID
body string yes 备注内容。限制为 1,000,000 个字符
confidential boolean no 已废弃: 计划在 16.0 中移除。备注的私密标记。默认为 False
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的项目路径
merge_request_iid integer yes 合并请求 IID
note_id integer yes 备注 ID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602"

史诗 (PREMIUM ALL)

列出所有史诗备注

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

note史诗备注 API 使用史诗 ID 而不是史诗 IID。如果您使用史诗的 IID,极狐GitLab 将返回 404 错误或其他史诗的备注。它不同于议题备注 API合并请求备注 API
GET /groups/:id/epics/:epic_id/notes
GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的群组路径
epic_id integer yes 群组史诗 ID
sort string no 返回以 ascdesc 顺序排序的史诗备注。默认为 desc
order_by string no 返回按照 created_atupdated_at 字段排序的史诗备注。默认为 created_at
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes"

获取单个史诗备注

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

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

参数:

参数 类型 是否必需 描述
id integer or string yes ID 或 URL 编码的群组路径
epic_id integer yes 史诗 ID
note_id integer yes 备注 ID
{
  "id": 302,
  "body": "Epic note",
  "attachment": null,
  "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
}
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/11/notes/1"

创建新史诗备注

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

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

参数:

参数 类型 是否必需 描述
body string yes 备注内容。限制为 1,000,000 个字符
epic_id integer yes 史诗 ID
id integer or string yes ID 或 URL 编码的群组路径
confidential boolean no 已弃用: 计划在 16.0 中移除,并重命名为 internal。备注的私密标志。默认为 false
internal boolean no 备注的内部标记。提交两个参数时覆盖 confidential。默认为 false
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的群组路径
epic_id integer yes 史诗 ID
note_id integer yes 备注 ID
body string yes 备注内容。限制为 1,000,000 个字符
confidential boolean no 已废弃: 计划在 16.0 中移除。备注的私密标记。默认为 False
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "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 yes ID 或 URL 编码的群组路径
epic_id integer yes 史诗 ID
note_id integer yes 备注 ID
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/epics/52/notes/1659"