{{< details >}}

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

{{< /details >}}

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

有效的访问级别

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

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

将成员添加到群组或项目

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

POST /groups/:id/invitations
POST /projects/:id/invitations
属性 类型 必填 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
email string 是（如果未提供 user_id） 新成员的电子邮件或用逗号分隔的多个电子邮件。
user_id integer/string 是（如果未提供 email） 新成员的 ID 或用逗号分隔的多个 ID。
access_level integer 是 有效的访问级别
expires_at string 否 格式为 YEAR-MONTH-DAY 的日期字符串
invite_source string 否 启动成员创建过程的邀请来源。
member_role_id integer 否 将新成员分配到提供的自定义角色。（引入于极狐GitLab 16.6。仅旗舰版。） 
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"

示例响应：

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

{  "status":  "success"  }

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

{
  "status": "error",
  "message": {
               "test@example.com": "Invite email has already been taken",
               "test2@example.com": "User already exists in source",
               "test_username": "Access level is not included in the list"
             }
}

{{< alert type=”note” >}}

如果管理员批准角色晋升已开启，则将现有用户晋升为计费角色的成员请求需要管理员批准。

{{< /alert >}}

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

示例响应：

{
  "queued_users": {
    "username_1": "Request queued for administrator approval."
  },
  "status": "success"
}

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

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

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

GET /groups/:id/invitations
GET /projects/:id/invitations
属性 类型 必填 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
page integer 否 要检索的页
per_page integer 否 每页返回的成员邀请数
query string 否 查询字符串以通过邀请电子邮件搜索被邀请的成员。查询文本必须与电子邮件地址完全匹配。为空时，返回所有邀请。 
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"

示例响应：

 [
   {
     "id": 1,
     "invite_email": "member@example.org",
     "created_at": "2020-10-22T14:13:35Z",
     "access_level": 30,
     "expires_at": "2020-11-22T14:13:35Z",
     "user_name": "Raymond Smith",
     "created_by_name": "Administrator"
   },
]

更新群组或项目的邀请

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

PUT /groups/:id/invitations/:email
PUT /projects/:id/invitations/:email
属性 类型 必填 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径。
email string 是 邀请先前发送到的电子邮件地址。
access_level integer 否 有效的访问级别（默认值：30，开发者角色）。
expires_at string 否 ISO 8601 格式的日期字符串 (YYYY-MM-DDTHH:MM:SSZ)。 
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"

示例响应：

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

删除群组或项目的邀请

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

DELETE /groups/:id/invitations/:email
DELETE /projects/:id/invitations/:email
属性 类型 必填 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
email string 是 邀请先前发送到的电子邮件地址 
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。