Help us learn about your current experience with the documentation. Take the survey.

项目代码片段

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用项目代码片段 API 来创建、管理和删除代码片段。

代码片段可见性级别

GitLab 中的代码片段可以是私有、内部或公开的。 你可以通过代码片段中的 visibility 字段来设置它。

代码片段可见性级别的常量有：

  • Private：私有 - 代码片段仅对项目成员可见。
  • Internal：内部 - 代码片段对任何已认证用户可见，但外部用户除外。
  • Public：公开 - 代码片段无需任何认证即可访问。

从 2019 年 7 月起，GitLab.com 上新创建的项目、组和代码片段的 Internal 可见性设置已被禁用。 使用 Internal 可见性设置的现有项目、组和代码片段将继续保持此设置。 你可以在相关问题中了解更多关于此变更的信息。

列出代码片段

获取项目代码片段列表。

GET /projects/:id/snippets

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。

单个代码片段

获取单个项目代码片段。

GET /projects/:id/snippets/:snippet_id

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
snippet_id integer yes 项目代码片段的 ID。 
{
  "id": 1,
  "title": "test",
  "file_name": "add.rb",
  "description": "Ruby test snippet",
  "author": {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "created_at": "2012-05-23T08:00:58Z"
  },
  "updated_at": "2012-06-28T10:52:04Z",
  "created_at": "2012-06-28T10:52:04Z",
  "imported": false,
  "imported_from": "none",
  "project_id": 1,
  "web_url": "http://example.com/example/example/snippets/1",
  "raw_url": "http://example.com/example/example/snippets/1/raw"
}

创建新代码片段

创建新的项目代码片段。用户必须有权创建新的代码片段。

POST /projects/:id/snippets

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
files:content string yes 代码片段文件的内容。
files:file_path string yes 代码片段文件的文件路径。
title string yes 代码片段的标题。
content string no 已弃用：请使用 files 替代。代码片段的内容。
description string no 代码片段的描述。
file_name string no 已弃用：请使用 files 替代。代码片段文件的名称。
files array of hashes no 代码片段文件数组。
visibility string no 代码片段的可见性。

示例请求：

curl --request POST "https://gitlab.com/api/v4/projects/:id/snippets" \
     --header "PRIVATE-TOKEN: <your access token>" \
     --header "Content-Type: application/json" \
     -d @snippet.json

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

{
  "title" : "Example Snippet Title",
  "description" : "More verbose snippet description",
  "visibility" : "private",
  "files": [
    {
      "file_path": "example.txt",
      "content" : "source code \n with multiple lines\n"
    }
  ]
}

更新代码片段

更新现有的项目代码片段。用户必须有权更改现有的代码片段。

包含多个文件的代码片段更新必须使用 files 属性。

PUT /projects/:id/snippets/:snippet_id

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
files:action string yes 对文件执行的操作类型。可选值：create、update、delete、move。
snippet_id integer yes 项目代码片段的 ID。
content string no 已弃用：请使用 files 替代。代码片段的内容。
description string no 代码片段的描述。
files array of hashes no 代码片段文件数组。
files:content string no 代码片段文件的内容。
files:file_path string no 代码片段文件的文件路径。
file_name string no 已弃用：请使用 files 替代。代码片段文件的名称。
files:previous_path string no 代码片段文件的先前路径。
title string no 代码片段的标题。
visibility string no 代码片段的可见性。

示例请求：

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

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

{
  "title" : "Updated Snippet Title",
  "description" : "More verbose snippet description",
  "visibility" : "private",
  "files": [
    {
      "action": "update",
      "file_path": "example.txt",
      "content" : "updated source code \n with multiple lines\n"
    }
  ]
}

删除代码片段

删除现有的项目代码片段。如果操作成功，返回 204 No Content 状态码；如果资源未找到，返回 404。

DELETE /projects/:id/snippets/:snippet_id

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
snippet_id integer yes 项目代码片段的 ID。

示例请求：

curl --request DELETE "https://gitlab.com/api/v4/projects/:id/snippets/:snippet_id" \
     --header "PRIVATE-TOKEN: <your_access_token>"

代码片段内容

以纯文本形式返回原始项目代码片段。

GET /projects/:id/snippets/:snippet_id/raw

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
snippet_id integer yes 项目代码片段的 ID。

示例请求：

curl "https://gitlab.com/api/v4/projects/:id/snippets/:snippet_id/raw" \
     --header "PRIVATE-TOKEN: <your_access_token>"

代码片段仓库文件内容

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

GET /projects/:id/snippets/:snippet_id/files/:ref/:file_path/raw

参数：

属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
file_path string yes 文件的 URL 编码路径，例如 snippet%2Erb。
ref string yes 分支、标签或提交的名称，例如 main。
snippet_id integer yes 项目代码片段的 ID。

示例请求：

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

获取用户代理详情

仅对具有管理员访问权限的用户可用。

GET /projects/:id/snippets/:snippet_id/user_agent_detail
属性 类型 必需 描述
id integer or string yes 项目的 ID 或URL 编码路径。
snippet_id Integer yes 代码片段的 ID。

示例请求：

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

示例响应：

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