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