# Snippets API

> 原文：[https://docs.gitlab.com/ee/api/snippets.html](https://docs.gitlab.com/ee/api/snippets.html)

*   [Snippet visibility level](#snippet-visibility-level)
*   [List all snippets for a user](#list-all-snippets-for-a-user)
*   [Get a single snippet](#get-a-single-snippet)
*   [Single snippet contents](#single-snippet-contents)
*   [Snippet repository file content](#snippet-repository-file-content)
*   [Create new snippet](#create-new-snippet)
*   [Update snippet](#update-snippet)
*   [Delete snippet](#delete-snippet)
*   [List all public snippets](#list-all-public-snippets)
*   [Get user agent details](#get-user-agent-details)

# Snippets API[](#snippets-api "Permalink")

在 GitLab 8.15 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6373) .

片段 API 在[片段上](../user/snippets.html)运行.

## Snippet visibility level[](#snippet-visibility-level "Permalink")

GitLab 中的代码段可以是私有的，内部的或公共的. 您可以使用代码段中的`visibility`字段进行设置.

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

| Visibility | Description |
| --- | --- |
| `private` | 摘要仅对摘要创建者可见. |
| `internal` | 所有已登录用户都可以看到该代码段. |
| `public` | 无需任何身份验证即可访问代码段. |

## List all snippets for a user[](#list-all-snippets-for-a-user "Permalink")

获取当前用户的片段列表.

```
GET /snippets 
```

请求示例：

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

响应示例：

```
[  {  "id":  42,  "title":  "Voluptatem iure ut qui aut et consequatur quaerat.",  "file_name":  "mclaughlin.rb",  "description":  null,  "visibility":  "internal",  "author":  {  "id":  22,  "name":  "User 0",  "username":  "user0",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",  "web_url":  "http://example.com/user0"  },  "updated_at":  "2018-09-18T01:12:26.383Z",  "created_at":  "2018-09-18T01:12:26.383Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/42",  "raw_url":  "http://example.com/snippets/42/raw"  },  {  "id":  41,  "title":  "Ut praesentium non et atque.",  "file_name":  "ondrickaemard.rb",  "description":  null,  "visibility":  "internal",  "author":  {  "id":  22,  "name":  "User 0",  "username":  "user0",  "state":  "active",  "avatar_url":  "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",  "web_url":  "http://example.com/user0"  },  "updated_at":  "2018-09-18T01:12:26.360Z",  "created_at":  "2018-09-18T01:12:26.360Z",  "project_id":  1,  "web_url":  "http://example.com/gitlab-org/gitlab-test/snippets/41",  "raw_url":  "http://example.com/gitlab-org/gitlab-test/snippets/41/raw"  }  ] 
```

## Get a single snippet[](#get-a-single-snippet "Permalink")

取得一个摘要.

```
GET /snippets/:id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 要检索的代码段的 ID. |

请求示例：

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

响应示例：

```
{  "id":  1,  "title":  "test",  "file_name":  "add.rb",  "description":  "Ruby test snippet",  "visibility":  "private",  "author":  {  "id":  1,  "username":  "john_smith",  "email":  "john@example.com",  "name":  "John Smith",  "state":  "active",  "created_at":  "2012-05-23T08:00:58Z"  },  "expires_at":  null,  "updated_at":  "2012-06-28T10:52:04Z",  "created_at":  "2012-06-28T10:52:04Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/1",  "raw_url":  "http://example.com/snippets/1/raw"  } 
```

## Single snippet contents[](#single-snippet-contents "Permalink")

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

```
GET /snippets/:id/raw 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 要检索的代码段的 ID. |

请求示例：

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

响应示例：

```
Hello World snippet 
```

## Snippet repository file content[](#snippet-repository-file-content "Permalink")

以纯文本形式返回原始文件的内容.

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

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 要检索的代码段 ID |
| `ref` | string | yes | 引用标签，分支或提交 |
| `file_path` | string | yes | 文件的 URL 编码路径 |

请求示例：

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

响应示例：

```
Hello World snippet 
```

## Create new snippet[](#create-new-snippet "Permalink")

创建一个新的代码段.

**注意：**用户必须具有创建新代码段的权限.

```
POST /snippets 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | yes | 摘要的标题. |
| `file_name` | string | yes | 片段文件的名称. |
| `content` | string | yes | 摘要的内容. |
| `description` | string | no | 片段说明. |
| `visibility` | string | no | Snippet’s [visibility](#snippet-visibility-level). |

请求示例：

```
curl --request POST \
     --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/snippets" 
```

响应示例：

```
{  "id":  1,  "title":  "This is a snippet",  "file_name":  "test.txt",  "description":  "Hello World snippet",  "visibility":  "internal",  "author":  {  "id":  1,  "username":  "john_smith",  "email":  "john@example.com",  "name":  "John Smith",  "state":  "active",  "created_at":  "2012-05-23T08:00:58Z"  },  "expires_at":  null,  "updated_at":  "2012-06-28T10:52:04Z",  "created_at":  "2012-06-28T10:52:04Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/1",  "raw_url":  "http://example.com/snippets/1/raw"  } 
```

## Update snippet[](#update-snippet "Permalink")

更新现有代码段.

**注意：**用户必须具有更改现有代码段的权限.

```
PUT /snippets/:id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 要更新的代码段 ID. |
| `title` | string | no | 摘要的标题. |
| `file_name` | string | no | 片段文件的名称. |
| `description` | string | no | 片段说明. |
| `content` | string | no | 摘要的内容. |
| `visibility` | string | no | Snippet’s [visibility](#snippet-visibility-level). |

请求示例：

```
curl --request PUT \
     --data '{"title": "foo", "content": "bar"}' \
     --header 'Content-Type: application/json' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/snippets/1" 
```

响应示例：

```
{  "id":  1,  "title":  "test",  "file_name":  "add.rb",  "description":  "description of snippet",  "visibility":  "internal",  "author":  {  "id":  1,  "username":  "john_smith",  "email":  "john@example.com",  "name":  "John Smith",  "state":  "active",  "created_at":  "2012-05-23T08:00:58Z"  },  "expires_at":  null,  "updated_at":  "2012-06-28T10:52:04Z",  "created_at":  "2012-06-28T10:52:04Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/1",  "raw_url":  "http://example.com/snippets/1/raw"  } 
```

## Delete snippet[](#delete-snippet "Permalink")

删除现有的代码段.

```
DELETE /snippets/:id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 要删除的代码段的 ID. |

请求示例：

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

以下是可能的返回码：

| Code | Description |
| --- | --- |
| `204` | 删除成功. 没有数据返回. |
| `404` | 找不到该代码段. |

## List all public snippets[](#list-all-public-snippets "Permalink")

列出所有公共摘要.

```
GET /snippets/public 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `per_page` | integer | no | 每页要返回的代码段数. |
| `page` | integer | no | 要检索的页面. |

请求示例：

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

响应示例：

```
[  {  "author":  {  "avatar_url":  "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon",  "id":  12,  "name":  "Libby Rolfson",  "state":  "active",  "username":  "elton_wehner",  "web_url":  "http://example.com/elton_wehner"  },  "created_at":  "2016-11-25T16:53:34.504Z",  "file_name":  "oconnerrice.rb",  "id":  49,  "title":  "Ratione cupiditate et laborum temporibus.",  "updated_at":  "2016-11-25T16:53:34.504Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/49",  "raw_url":  "http://example.com/snippets/49/raw"  },  {  "author":  {  "avatar_url":  "http://www.gravatar.com/avatar/36583b28626de71061e6e5a77972c3bd?s=80&d=identicon",  "id":  16,  "name":  "Llewellyn Flatley",  "state":  "active",  "username":  "adaline",  "web_url":  "http://example.com/adaline"  },  "created_at":  "2016-11-25T16:53:34.479Z",  "file_name":  "muellershields.rb",  "id":  48,  "title":  "Minus similique nesciunt vel fugiat qui ullam sunt.",  "updated_at":  "2016-11-25T16:53:34.479Z",  "project_id":  null,  "web_url":  "http://example.com/snippets/48",  "raw_url":  "http://example.com/snippets/49/raw",  "visibility":  "public"  }  ] 
```

## Get user agent details[](#get-user-agent-details "Permalink")

在 GitLab 9.4 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12655) .

**注意：**仅适用于管理员.

```
GET /snippets/:id/user_agent_detail 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 摘要的 ID. |

请求示例：

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

响应示例：

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