极狐 GitLab Logo

邀请 API

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

使用此 API 来管理邀请并将用户添加到群组或项目。

有效的访问级别#

要发送邀请，您必须拥有要发送电子邮件的项目或群组的访问权限。有效的访问级别定义在 Gitlab::Access 模块中。目前，这些级别是有效的：

  • 无访问权限 (0)
  • 最小访问权限 (5)
  • 访客 (10)
  • 计划员 (15)
  • 报告员 (20)
  • 开发者 (30)
  • 维护者 (40)
  • 所有者 (50)

将成员添加到群组或项目#

添加新成员。您可以指定用户 ID 或通过电子邮件邀请用户。

plaintext
POST /groups/:id/invitations
POST /projects/:id/invitations
属性类型必填描述
idinteger/string是项目或群组的 ID 或 URL 编码路径
emailstring是（如果未提供 user_id）新成员的电子邮件或用逗号分隔的多个电子邮件。
user_idinteger/string是（如果未提供 email）新成员的 ID 或用逗号分隔的多个 ID。
access_levelinteger是有效的访问级别
expires_atstring否格式为 YEAR-MONTH-DAY 的日期字符串
invite_sourcestring否启动成员创建过程的邀请来源。
member_role_idinteger否将新成员分配到提供的自定义角色。（引入于极狐GitLab 16.6。仅旗舰版。）
shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "email=test@example.com&user_id=1&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations"

示例响应：

当所有电子邮件成功发送时：

json
{  "status":  "success"  }

当发送电子邮件时发生任何错误：

json
1{
2  "status": "error",
3  "message": {
4               "test@example.com": "Invite email has already been taken",
5               "test2@example.com": "User already exists in source",
6               "test_username": "Access level is not included in the list"
7             }
8}
如果[管理员批准角色晋升](../administration/settings/sign_up_restrictions.md#turn-on-administrator-approval-for-role-promotions)已开启，则将现有用户晋升为计费角色的成员请求需要管理员批准。

要启用 管理非计费晋升，您必须首先启用 enable_member_promotion_management 应用程序设置。

示例响应：

json
1{
2  "queued_users": {
3    "username_1": "Request queued for administrator approval."
4  },
5  "status": "success"
6}

列出群组或项目的所有待处理邀请#

获取经过身份验证的用户可查看的被邀请群组或项目成员的列表。仅返回直接成员的邀请，而不是通过继承的上级群组。

此功能接受分页参数 page 和 per_page 来限制成员列表。

plaintext
GET /groups/:id/invitations
GET /projects/:id/invitations
属性类型必填描述
idinteger/string是项目或群组的 ID 或 URL 编码路径
pageinteger否要检索的页
per_pageinteger否每页返回的成员邀请数
querystring否查询字符串以通过邀请电子邮件搜索被邀请的成员。查询文本必须与电子邮件地址完全匹配。为空时，返回所有邀请。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org"
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/invitations?query=member@example.org"

示例响应：

json
1 [
2   {
3     "id": 1,
4     "invite_email": "member@example.org",
5     "created_at": "2020-10-22T14:13:35Z",
6     "access_level": 30,
7     "expires_at": "2020-11-22T14:13:35Z",
8     "user_name": "Raymond Smith",
9     "created_by_name": "Administrator"
10   },
11]

更新群组或项目的邀请#

更新待处理邀请的访问级别或访问到期日期。

plaintext
PUT /groups/:id/invitations/:email
PUT /projects/:id/invitations/:email
属性类型必填描述
idinteger/string是项目或群组的 ID 或 URL 编码路径。
emailstring是邀请先前发送到的电子邮件地址。
access_levelinteger否有效的访问级别（默认值：30，开发者角色）。
expires_atstring否ISO 8601 格式的日期字符串 (YYYY-MM-DDTHH:MM:SSZ)。
shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org?access_level=40"
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org?access_level=40"

示例响应：

json
{
  "expires_at": "2012-10-22T14:13:35Z",
  "access_level": 40,
}

删除群组或项目的邀请#

通过电子邮件地址删除待处理的邀请。

plaintext
DELETE /groups/:id/invitations/:email
DELETE /projects/:id/invitations/:email
属性类型必填描述
idinteger/string是项目或群组的 ID 或 URL 编码路径
emailstring是邀请先前发送到的电子邮件地址
shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org"
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org"
  • 成功时返回 204 且无内容。
  • 如果无权删除邀请，则返回 403 禁止。
  • 如果授权且未找到该电子邮件地址的邀请，则返回 404 未找到。
  • 如果请求有效但邀请无法删除，则返回 409。