代码片段 API

极狐GitLab 的 Snippets API 操作在代码片段上。相关 API 存在于项目代码片段和在存储之间移动代码片段。

代码片段可见性级别#

在极狐GitLab 中，代码片段可以是私有、内部或公共的。您可以通过代码片段中的 visibility 字段进行设置。

代码片段可见性级别的有效值为：

列出当前用户的所有代码片段#

获取当前用户的代码片段列表。

plaintext
GET /snippets

参数：

示例请求：

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

示例响应：

json
1[
2    {
3        "id": 42,
4        "title": "Voluptatem iure ut qui aut et consequatur quaerat.",
5        "file_name": "mclaughlin.rb",
6        "description": null,
7        "visibility": "internal",
8        "imported": false,
9        "imported_from": "none",
10        "author": {
11            "id": 22,
12            "name": "User 0",
13            "username": "user0",
14            "state": "active",
15            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
16            "web_url": "http://example.com/user0"
17        },
18        "updated_at": "2018-09-18T01:12:26.383Z",
19        "created_at": "2018-09-18T01:12:26.383Z",
20        "project_id": null,
21        "web_url": "http://example.com/snippets/42",
22        "raw_url": "http://example.com/snippets/42/raw"
23    },
24    {
25        "id": 41,
26        "title": "Ut praesentium non et atque.",
27        "file_name": "ondrickaemard.rb",
28        "description": null,
29        "visibility": "internal",
30        "imported": false,
31        "imported_from": "none",
32        "author": {
33            "id": 22,
34            "name": "User 0",
35            "username": "user0",
36            "state": "active",
37            "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
38            "web_url": "http://example.com/user0"
39        },
40        "updated_at": "2018-09-18T01:12:26.360Z",
41        "created_at": "2018-09-18T01:12:26.360Z",
42        "project_id": 1,
43        "web_url": "http://example.com/gitlab-org/gitlab-test/snippets/41",
44        "raw_url": "http://example.com/gitlab-org/gitlab-test/snippets/41/raw"
45    }
46]

获取单个代码片段#

获取单个代码片段。

plaintext
GET /snippets/:id

参数：

示例请求：

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

示例响应：

json
1{
2  "id": 1,
3  "title": "test",
4  "file_name": "add.rb",
5  "description": "Ruby test snippet",
6  "visibility": "private",
7  "imported": false,
8  "imported_from": "none",
9  "author": {
10    "id": 1,
11    "username": "john_smith",
12    "email": "john@example.com",
13    "name": "John Smith",
14    "state": "active",
15    "created_at": "2012-05-23T08:00:58Z"
16  },
17  "expires_at": null,
18  "updated_at": "2012-06-28T10:52:04Z",
19  "created_at": "2012-06-28T10:52:04Z",
20  "project_id": null,
21  "web_url": "http://example.com/snippets/1",
22  "raw_url": "http://example.com/snippets/1/raw"
23}

单个代码片段内容#

获取单个代码片段的原始内容。

plaintext
GET /snippets/:id/raw

参数：

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/snippets/1/raw"

示例响应：

plaintext
Hello World snippet

代码片段仓库文件内容#

以纯文本格式返回原始文件内容。

plaintext
GET /snippets/:id/files/:ref/:file_path/raw

参数：

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/snippets/1/files/main/snippet%2Erb/raw"

示例响应：

plaintext
Hello World snippet

创建新的代码片段#

创建新的代码片段。

plaintext
POST /snippets

参数：

示例请求：

shell
curl --request POST "https://gitlab.example.com/api/v4/snippets" \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     -d @snippet.json

在上述示例请求中使用的 snippet.json：

json
1{
2  "title": "This is a snippet",
3  "description": "Hello World snippet",
4  "visibility": "internal",
5  "files": [
6    {
7      "content": "Hello world",
8      "file_path": "test.txt"
9    }
10  ]
11}

示例响应：

json
1{
2  "id": 1,
3  "title": "This is a snippet",
4  "description": "Hello World snippet",
5  "visibility": "internal",
6  "imported": false,
7  "imported_from": "none",
8  "author": {
9    "id": 1,
10    "username": "john_smith",
11    "email": "john@example.com",
12    "name": "John Smith",
13    "state": "active",
14    "created_at": "2012-05-23T08:00:58Z"
15  },
16  "expires_at": null,
17  "updated_at": "2012-06-28T10:52:04Z",
18  "created_at": "2012-06-28T10:52:04Z",
19  "project_id": null,
20  "web_url": "http://example.com/snippets/1",
21  "raw_url": "http://example.com/snippets/1/raw",
22  "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git",
23  "http_url_to_repo": "https://gitlab.example.com/snippets/1.git",
24  "file_name": "test.txt",
25  "files": [
26    {
27      "path": "text.txt",
28      "raw_url": "https://gitlab.example.com/-/snippets/1/raw/main/renamed.md"
29    }
30  ]
31}

更新代码片段#

更新现有代码片段。

plaintext
PUT /snippets/:id

参数：

示例请求：

shell
curl --request PUT "https://gitlab.example.com/api/v4/snippets/1" \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     -d @snippet.json

在上述示例请求中使用的 snippet.json：

json
1{
2  "title": "foo",
3  "files": [
4    {
5      "action": "move",
6      "previous_path": "test.txt",
7      "file_path": "renamed.md"
8    }
9  ]
10}

示例响应：

json
1{
2  "id": 1,
3  "title": "test",
4  "description": "description of snippet",
5  "visibility": "internal",
6  "imported": false,
7  "imported_from": "none",
8  "author": {
9    "id": 1,
10    "username": "john_smith",
11    "email": "john@example.com",
12    "name": "John Smith",
13    "state": "active",
14    "created_at": "2012-05-23T08:00:58Z"
15  },
16  "expires_at": null,
17  "updated_at": "2012-06-28T10:52:04Z",
18  "created_at": "2012-06-28T10:52:04Z",
19  "project_id": null,
20  "web_url": "http://example.com/snippets/1",
21  "raw_url": "http://example.com/snippets/1/raw",
22  "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git",
23  "http_url_to_repo": "https://gitlab.example.com/snippets/1.git",
24  "file_name": "renamed.md",
25  "files": [
26    {
27      "path": "renamed.md",
28      "raw_url": "https://gitlab.example.com/-/snippets/1/raw/main/renamed.md"
29    }
30  ]
31}

删除代码片段#

删除现有代码片段。

plaintext
DELETE /snippets/:id

参数：

示例请求：

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

以下是可能的返回代码：

列出所有公共代码片段#

列出所有公共代码片段。

plaintext
GET /snippets/public

参数：

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1"

示例响应：

json
1[
2    {
3        "author": {
4            "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
5            "id": 12,
6            "name": "Libby Rolfson",
7            "state": "active",
8            "username": "elton_wehner",
9            "web_url": "http://example.com/elton_wehner"
10        },
11        "created_at": "2016-11-25T16:53:34.504Z",
12        "file_name": "oconnerrice.rb",
13        "id": 49,
14        "title": "Ratione cupiditate et laborum temporibus.",
15        "updated_at": "2016-11-25T16:53:34.504Z",
16        "project_id": null,
17        "web_url": "http://example.com/snippets/49",
18        "raw_url": "http://example.com/snippets/49/raw"
19    },
20    {
21        "author": {
22            "avatar_url": "http://www.gravatar.com/avatar/36583b28626de71061e6e5a77972c3bd?s=80&d=identicon",
23            "id": 16,
24            "name": "Llewellyn Flatley",
25            "state": "active",
26            "username": "adaline",
27            "web_url": "http://example.com/adaline"
28        },
29        "created_at": "2016-11-25T16:53:34.479Z",
30        "file_name": "muellershields.rb",
31        "id": 48,
32        "title": "Minus similique nesciunt vel fugiat qui ullam sunt.",
33        "updated_at": "2016-11-25T16:53:34.479Z",
34        "project_id": null,
35        "web_url": "http://example.com/snippets/48",
36        "raw_url": "http://example.com/snippets/49/raw",
37        "visibility": "public"
38    }
39]

列出所有代码片段#

列出当前用户有权访问的所有代码片段。具有 管理员 或 审计员 访问级别的用户可以看到所有代码片段（个人和项目）。

plaintext
GET /snippets/all

参数：

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/snippets/all?per_page=2&page=1"

示例响应：

json
1[
2  {
3    "id": 113,
4    "title": "Internal Project Snippet",
5    "description": null,
6    "visibility": "internal",
7    "imported": false,
8    "imported_from": "none",
9    "author": {
10      "id": 17,
11      "username": "tim_kreiger",
12      "name": "Tim Kreiger",
13      "state": "active",
14      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
15      "web_url": "http://example.com/tim_kreiger"
16    },
17    "created_at": "2023-08-03T10:21:02.480Z",
18    "updated_at": "2023-08-03T10:21:02.480Z",
19    "project_id": 35,
20    "web_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113",
21    "raw_url": "http://example.com/tim_kreiger/internal_project/-/snippets/113/raw",
22    "file_name": "",
23    "files": [],
24    "repository_storage": "default"
25  },
26  {
27    "id": 112,
28    "title": "Private Personal Snippet",
29    "description": null,
30    "visibility": "private",
31    "imported": false,
32    "imported_from": "none",
33    "author": {
34      "id": 1,
35      "username": "root",
36      "name": "Administrator",
37      "state": "active",
38      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
39      "web_url": "http://example.com/root"
40    },
41    "created_at": "2023-08-03T10:20:59.994Z",
42    "updated_at": "2023-08-03T10:20:59.994Z",
43    "project_id": null,
44    "web_url": "http://example.com/-/snippets/112",
45    "raw_url": "http://example.com/-/snippets/112/raw",
46    "file_name": "",
47    "files": [],
48    "repository_storage": "default"
49  },
50  {
51    "id": 111,
52    "title": "Public Personal Snippet",
53    "description": null,
54    "visibility": "public",
55    "imported": false,
56    "imported_from": "none",
57    "author": {
58      "id": 17,
59      "username": "tim_kreiger",
60      "name": "Tim Kreiger",
61      "state": "active",
62      "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",
63      "web_url": "http://example.com/tim_kreiger"
64    },
65    "created_at": "2023-08-03T10:21:01.312Z",
66    "updated_at": "2023-08-03T10:21:01.312Z",
67    "project_id": null,
68    "web_url": "http://example.com/-/snippets/111",
69    "raw_url": "http://example.com/-/snippets/111/raw",
70    "file_name": "",
71    "files": [],
72    "repository_storage": "default"
73  },
74]

获取用户代理详情#

plaintext
GET /snippets/:id/user_agent_detail

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/snippets/1/user_agent_detail"

示例响应：

json
{
  "user_agent": "AppleWebKit/537.36",
  "ip_address": "127.0.0.1",
  "akismet_submitted": false
}