招待API

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、招待を管理し、ユーザーをグループまたはプロジェクトに追加します。

グループまたはプロジェクトにメンバーを追加する

新しいメンバーを追加します。ユーザーIDを指定するか、メールでユーザーを招待できます。

前提条件:

グループの場合、グループのオーナーロールが必要です。
プロジェクトの場合:
- プロジェクトのメンテナーまたはオーナーロールが必要です。
- グループメンバーシップのロックを無効にする必要があります。
GitLab Self-Managedインスタンスの場合:
- 新規ユーザーアカウントの作成が許可されていない場合、管理者がユーザーを追加する必要があります。
- ユーザー招待が許可されていない場合、管理者がユーザーを追加する必要があります。
- ロールのプロモートに対する管理者承認が有効になっている場合、管理者が招待を承認する必要があります。

POST /groups/:id/invitations
POST /projects/:id/invitations

属性	型	必須	説明
`id`	整数または文字列	はい	IDまたはプロジェクトまたはグループのURLエンコードされたパス
`email`	文字列	はい（`user_id`が指定されていない場合）	新しいメンバーのメール、またはコンマで区切られた複数のメール。
`user_id`	整数または文字列	はい（`email`が指定されていない場合）	新しいメンバーのID、またはコンマで区切られた複数のID。
`access_level`	整数	はい	有効なアクセスレベル。使用可能な値: `0`（アクセスなし）、`5`（最小アクセス）、`10`（ゲスト）、`15`（プランナー）、`20`（レポーター）、`25`（セキュリティマネージャー）、`30`（デベロッパー）、`40`（メンテナー）、または`50`（オーナー）。デフォルトは`30`です。
`expires_at`	文字列	いいえ	`YEAR-MONTH-DAY`形式の日付文字列
`invite_source`	文字列	いいえ	メンバー作成プロセスを開始する招待のソース。
`member_role_id`	整数	いいえ	新しいメンバーに指定されたカスタムロールを割り当てます。GitLab 16.6で(導入)。Ultimateのみです。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/invitations" \
  --data "email=test@example.com&user_id=1&access_level=30"
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/invitations" \
  --data "email=test@example.com&user_id=1&access_level=30"

レスポンス例:

すべてのメールが正常に送信された場合:

{  "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"
             }
}

請求対象でないプロモーションの管理を有効にするには、最初に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`	整数または文字列	はい	IDまたはプロジェクトまたはグループのURLエンコードされたパス
`page`	整数	いいえ	取得するページ
`per_page`	整数	いいえ	ページごとに返すメンバー招待の数
`query`	文字列	いいえ	招待メールで招待されたメンバーをクエリするためのクエリ文字列。クエリテキストはメールアドレスと正確に一致する必要があります。空の場合、すべての招待を返します。

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org"
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	整数または文字列	はい	プロジェクトまたはグループのIDまたはURLエンコードされたパス。
`email`	文字列	はい	以前に招待が送信されたメールアドレス。
`access_level`	整数	いいえ	有効なアクセスレベル。使用可能な値: `0`（アクセスなし）、`5`（最小アクセス）、`10`（ゲスト）、`15`（プランナー）、`20`（レポーター）、`25`（セキュリティマネージャー）、`30`（デベロッパー）、`40`（メンテナー）、または`50`（オーナー）。デフォルトは`30`です。
`expires_at`	文字列	いいえ	ISO 8601形式 (`YYYY-MM-DDTHH:MM:SSZ`) の日付文字列。

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org?access_level=40"
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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`	整数または文字列	はい	IDまたはプロジェクトまたはグループのURLエンコードされたパス
`email`	文字列	はい	以前に招待が送信されたメールアドレス

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org"
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org"

成功すると204が返されますが、コンテンツは返されません。
招待を削除する権限がない場合は403 forbiddenを返します。
権限があり、そのメールアドレスの招待が見つからない場合は404 not foundを返します。
リクエストが有効だったが招待を削除できなかった場合は409を返します。