{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 私有化部署
{{< /details >}}
你可以使用此 API 获取、创建、更新和删除你的代码库中的文件。你也可以为此 API 配置速率限制。
个人访问令牌的可用范围
个人访问令牌支持以下范围:
Scope | Description |
---|---|
api |
允许对代码库文件进行读写访问。 |
read_api |
允许对代码库文件进行读取访问。 |
read_repository |
允许对代码库文件进行读取访问。 |
从代码库获取文件
允许你接收有关代码库中文件的信息,例如名称、大小和内容。文件内容是 Base64 编码的。如果代码库是公开访问的,你可以在不进行身份验证的情况下访问此端点。
GET /projects/:id/repository/files/:file_path
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径。 |
file_path |
string | yes | URL 编码的新文件完整路径,例如 lib%2Fclass%2Erb 。 |
ref |
string | yes | 分支、标签或提交的名称。使用 HEAD 自动使用默认分支。 |
如果你不知道分支名称或想使用默认分支,你可以使用 HEAD
作为 ref
值。例如:
curl --header "PRIVATE-TOKEN: " \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=HEAD"
响应
在响应中,blob_id
是 blob 的 SHA。请参阅极狐GitLab API 中的从代码库获取 blob。
响应示例:
{
"file_name": "key.rb",
"file_path": "app/models/key.rb",
"size": 1476,
"encoding": "base64",
"content": "IyA9PSBTY2hlbWEgSW5mb3...",
"content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
"ref": "main",
"blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
"commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
"last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d",
"execute_filemode": false
}
仅获取文件元数据
你也可以使用 HEAD
来仅获取文件元数据。
HEAD /projects/:id/repository/files/:file_path
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"
响应示例:
HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: key.rb
X-Gitlab-File-Path: app/models/key.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...
从代码库获取文件责任信息
检索责任信息。每个责任范围包含行及其对应的提交信息。
GET /projects/:id/repository/files/:file_path/blame
Attribute | Type | Required | Description |
---|---|---|---|
file_path |
string | yes | URL 编码的新文件完整路径,例如 lib%2Fclass%2Erb 。 |
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径。 |
range[end] |
integer | yes | 责任范围的最后一行。 |
range[start] |
integer | yes | 责任范围的第一行。 |
ref |
string | yes | 分支、标签或提交的名称。使用 HEAD 自动使用默认分支。 |
range |
hash | no | 责任范围。 |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main"
响应示例:
[
{
"commit": {
"id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
"message": "Add feature\n\nalso fix bug\n",
"parent_ids": [
"cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
],
"authored_date": "2015-12-18T08:12:22.000Z",
"author_name": "John Doe",
"author_email": "john.doe@example.com",
"committed_date": "2015-12-18T08:12:22.000Z",
"committer_name": "John Doe",
"committer_email": "john.doe@example.com"
},
"lines": [
"require 'fileutils'",
"require 'open3'",
""
]
},
...
]
仅获取文件元数据
使用 HEAD
方法仅返回文件元数据,如从代码库获取文件中所示:
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main"
响应
响应示例:
HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: file.rb
X-Gitlab-File-Path: path/to/file.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...
请求责任范围
要请求责任范围,请指定 range[start]
和 range[end]
参数及文件的起始和结束行号。
curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main&range[start]=1&range[end]=2"
响应示例:
[
{
"commit": {
"id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
"message": "Add feature\n\nalso fix bug\n",
"parent_ids": [
"cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
],
"authored_date": "2015-12-18T08:12:22.000Z",
"author_name": "John Doe",
"author_email": "john.doe@example.com",
"committed_date": "2015-12-18T08:12:22.000Z",
"committer_name": "John Doe",
"committer_email": "john.doe@example.com"
},
"lines": [
"require 'fileutils'",
"require 'open3'"
]
},
...
]
从代码库获取原始文件
GET /projects/:id/repository/files/:file_path/raw
Attribute | Type | Required | Description |
---|---|---|---|
file_path |
string | yes | URL 编码的新文件完整路径,例如 lib%2Fclass%2Erb 。 |
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径。 |
lfs |
boolean | no | 确定响应是否应为 Git LFS 文件内容,而不是指针。如果文件未被 Git LFS 跟踪,则忽略。默认值为 false 。在极狐GitLab 15.7 中引入。 |
ref |
string | no | 分支、标签或提交的名称。默认是项目的 HEAD 。 |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=main"
{{< alert type=”note” >}}
如从代码库获取文件,你可以使用 HEAD
来仅获取文件元数据。
{{< /alert >}}
在代码库中创建新文件
允许你创建单个文件。要使用单个请求创建多个文件,请参阅提交 API。
POST /projects/:id/repository/files/:file_path
Attribute | Type | Required | Description |
---|---|---|---|
branch |
string | yes | 要创建的新分支的名称。提交添加到此分支。 |
commit_message |
string | yes | 提交信息。 |
content |
string | yes | 文件的内容。 |
file_path |
string | yes | URL 编码的新文件完整路径。例如:lib%2Fclass%2Erb 。 |
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径。 |
author_email |
string | no | 提交作者的电子邮件地址。 |
author_name |
string | no | 提交作者的姓名。 |
encoding |
string | no | 将编码更改为 base64 。默认是 text 。 |
execute_filemode |
boolean | no | 启用或禁用文件的 execute 标志。可以是 true 或 false 。 |
start_branch |
string | no | 要从中创建新分支的基分支名称。 |
curl --request POST \
--header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
--data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
"content": "some content", "commit_message": "create a new file"}' \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
响应示例:
{
"file_path": "app/project.rb",
"branch": "main"
}
更新代码库中现有文件
允许你更新单个文件。要使用单个请求更新多个文件,请参阅提交 API。
PUT /projects/:id/repository/files/:file_path
Attribute | Type | Required | Description |
---|---|---|---|
branch |
string | yes | 要创建的新分支的名称。提交添加到此分支。 |
commit_message |
string | yes | 提交信息。 |
content |
string | yes | 文件的内容。 |
file_path |
string | yes | URL 编码的新文件完整路径。例如:lib%2Fclass%2Erb 。 |
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径 |
author_email |
string | no | 提交作者的电子邮件地址。 |
author_name |
string | no | 提交作者的姓名。 |
encoding |
string | no | 将编码更改为 base64 。默认是 text 。 |
execute_filemode |
boolean | no | 启用或禁用文件的 execute 标志。可以是 true 或 false 。 |
last_commit_id |
string | no | 最后已知的文件提交 ID。 |
start_branch |
string | no | 要从中创建新分支的基分支名称。 |
curl --request PUT \
--header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
--data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
"content": "some content", "commit_message": "update file"}' \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
响应示例:
{
"file_path": "app/project.rb",
"branch": "main"
}
如果提交因任何原因失败,我们会返回一个 400 Bad Request
错误,并附带一个非特定的错误消息。提交失败的可能原因包括:
-
file_path
包含/../
(尝试目录遍历)。 - 提交是空的:新文件内容与当前文件内容相同。
- 在文件编辑过程中,有人使用
git push
更新了分支。
极狐GitLab Shell 具有布尔返回代码,阻止极狐GitLab 指定错误。
删除代码库中现有文件
删除单个文件。要使用单个请求删除多个文件,请参阅提交 API。
DELETE /projects/:id/repository/files/:file_path
Attribute | Type | Required | Description |
---|---|---|---|
branch |
string | yes | 要创建的新分支的名称。提交添加到此分支。 |
commit_message |
string | yes | 提交信息。 |
file_path |
string | yes | URL 编码的新文件完整路径。例如:lib%2Fclass%2Erb 。 |
id |
integer or string | yes | 项目的 ID 或 URL 编码的项目路径。 |
author_email |
string | no | 提交作者的电子邮件地址。 |
author_name |
string | no | 提交作者的姓名。 |
last_commit_id |
string | no | 最后已知的文件提交 ID。 |
start_branch |
string | no | 要从中创建新分支的基分支名称。 |
curl --request DELETE \
--header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
--data '{"branch": "main", "author_email": "author@example.com", "author_name": "Firstname Lastname",
"commit_message": "delete file"}' \
--url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"