Loading pod-GitLab-Users.md +138 −79 Original line number Original line Diff line number Diff line # NAME # NAME GitLab::Users - implements user API calls `GitLab::Users` - implements user API calls See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and response formats. response formats. Loading @@ -12,11 +12,12 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`. # SYNOPSIS # SYNOPSIS ```{.pl} use GitLab::API; use GitLab::API; use GitLab::Users; use GitLab::Users; # all calls from GitLab::Users are "injected" into the GitLab::API as methods # all calls from GitLab::Users are "injected" into the GitLab::API as methods my $api = GitLab::API->new(); my $api = GitLab::API->new(...); my $john = $api->users(username => "john_doe"); my $john = $api->users(username => "john_doe"); Loading @@ -26,21 +27,26 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`. username => "jane.doe", username => "jane.doe", name => "Jane Doe" name => "Jane Doe" ); ); ``` # DESCRIPTION # DESCRIPTION ## Notation ## Notation All methods take a hash of arguments as specified in the documentation for All methods take a hash of arguments as specified in the documentation for ["exec\_request" in GitLab::API](https://metacpan.org/pod/GitLab::API#exec_request), but to simplify the documentation, [`exec_request` in GitLab::API](pod-GitLab-API.md#exec_request), but to simplify the documentation, we will use the following notation: we will use the following notation: ```{.rb} users( :username, :search ) users( :username, :search ) ``` which means that the `users` method takes a hash with two keys, `username` which means that the `users` method takes a hash with two keys, `username` and `search`, so it can be called as and `search`, so it can be called as ```{.pl} $gitlab->users(search => "john_doe"); $gitlab->users(search => "john_doe"); ``` Optional arguments are denoted as ` [:username] `. Optional arguments are denoted as ` [:username] `. Note that not all optional arguments are listed. Note that not all optional arguments are listed. Loading @@ -48,47 +54,61 @@ Please refer to the official documentation for the full list. ## User CRUD operations ## User CRUD operations - users() - `users()` ```{.pl} $users = $gitlab->users( [:username], [:search] ); $users = $gitlab->users( [:username], [:search] ); ``` This method returns all users. The optional arguments can be used This method returns all users. The optional arguments can be used to filter out the results: to filter out the results: username search for a user by his username (exact match) | argument | description | search search for users with username or email (substring match) | ------------- | ----------- | | `username` | search for a user by his username (**exact match**) | | `search` | search for users with username or email (**substring match**) | Note that the returned value is still an array even when `users(username => $username)` Note that the returned value is still an array even when `users(username => $username)` always returns at most one result. always returns at most one result. - user\_by\_id() - `user_by_id()` ```{.pl} $user = $gitlab->user_by_id( :uid ); $user = $gitlab->user_by_id( :uid ); ``` Returns a user with the given `uid`. Returns a user with the given `uid`. - user\_create() - `user_create()` $user = $gitlab->user_create( :email, :password, :username, :name ); ```{.pl} $user = $gitlab->user_create( :email, :password, :username, :name [, ...]); ``` Creates a new user and if succeeds, returns the generated account information. Creates a new user and if succeeds, returns the generated account information. email primary email, must not exist in GitLab, | argument | description | password user password, | ------------------- | ----------- | username login, must not exist in GitLab, | `email` | primary email, must not exist in GitLab | name display name | `password` | user password | | `username` | login, must not exist in GitLab | | `name` | display name | The function can take many optional arguments. Please see the API documentation for The function can take many optional arguments. Please see the API documentation for the full list. Most interesting arguments are: the full list. Most interesting arguments are: admin create an admin account (bool) | argument | description | can_create_group the user will be able to create group (bool) | -------- | ----------- | external create an external account (bool) | `admin` | create an admin account (bool) | projects_limit maximum number of projects the user can own | `can_create_group` | the user will be able to create group (bool) | | `external` | create an external account (bool) | | `projects_limit` | maximum number of projects the user can own | - user\_update() - `user_update()` ```{.pl} $user = $gitlab->user_update( :uid ); $user = $gitlab->user_update( :uid ); ``` Updates the user with the given `uid`. It takes the same arguments as `user_create` Updates the user with the given `uid`. It takes the same arguments as `user_create` except they are all optional. Note that though it is possible to change user's primary e-mail except they are all optional. Note that though it is possible to change user's primary e-mail Loading @@ -96,150 +116,189 @@ Please refer to the official documentation for the full list. Also, from documentation: Also, from documentation: Note, at the moment this method does only return a 404 error, even in cases where > Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. > a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. - user\_delete() - `user_delete()` ```{.pl} $gitlab->user_delete( :uid ); $gitlab->user_delete( :uid ); ``` Deletes the user with the given `uid`. Deletes the user with the given `uid`. Note that Note that calling this function for a non-existent user id still returns a status code 200 OK. > calling this function for a non-existent user id still returns a status code 200 OK. The JSON response differs if the user was actually deleted or not. > The JSON response differs if the user was actually deleted or not. (from the GitLab API documentation). (from the GitLab API documentation). - user() - `user()` ```{.pl} $user = $gitlab->user(); $user = $gitlab->user(); ``` Returns the user whose authentication key is used for the request Returns the user whose authentication key is used for the request (or impersonated user if `sudo` is in effect). (or impersonated user if `sudo` is in effect). Behaves the same as the ["whoami" in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method. Behaves the same as the [`whoami` in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method. ## SSH keys ## SSH keys - self\_ssh\_keys() - `self_ssh_keys()` ```{.pl} $keys = $gitlab->self_ssh_keys(); $keys = $gitlab->self_ssh_keys(); ``` Returns a list of SSH keys for the user that makes the request. Returns a list of SSH keys for the user that makes the request. - self\_get\_ssh\_key() - `self_get_ssh_key()` ```{.pl} $key = $gitlab->self_get_ssh_key( :keyid ); $key = $gitlab->self_get_ssh_key( :keyid ); ``` For the user that makes the request, the function returns the SSH key with the given `keyid`. For the user that makes the request, the function returns the SSH key with the given `keyid`. - user\_get\_ssh\_keys() - `user_get_ssh_keys()` ```{.pl} $keys = $gitlab->user_get_ssh_keys( :uid ); $keys = $gitlab->user_get_ssh_keys( :uid ); ``` Returns a list of SSH keys for the user with the given `uid`. Returns a list of SSH keys for the user with the given `uid`. - self\_add\_ssh\_key() - `self_add_ssh_key()` ```{.pl} $key = $gitlab->self_add_ssh_key( :title, :key ); $key = $gitlab->self_add_ssh_key( :title, :key ); ``` Adds a new key for the user that makes the request. Required arguments are Adds a new key for the user that makes the request. Required arguments are title the title of the key | argument | description | key public SSH key | -------- | ----------- | | `title` | the title of the key | | `key` | public SSH key | - user\_add\_ssh\_key() - `user_add_ssh_key()` ```{.pl} $key = $gitlab->user_add_ssh_key( :uid, :title, :key ); $key = $gitlab->user_add_ssh_key( :uid, :title, :key ); ``` Similar to `self_add_ssh_key`, but targets the user with the given `uid`. Similar to `self_add_ssh_key`, but targets the user with the given `uid`. - self\_delete\_ssh\_key() - `self_delete_ssh_key()` ```{.pl} $gitlab->self_delete_ssh_key( :keyid ) $gitlab->self_delete_ssh_key( :keyid ) ``` Removes the SSH key with the given `keyid` for the user that makes the request. Removes the SSH key with the given `keyid` for the user that makes the request. - user\_delete\_ssh\_key() - `user_delete_ssh_key()` ```{.pl} $gitlab->user_delete_ssh_key( :uid, :keyid ); $gitlab->user_delete_ssh_key( :uid, :keyid ); ``` Removes the SSH key with the `keyid` for the user with the given `uid`. Removes the SSH key with the `keyid` for the user with the given `uid`. ## E-mails ## E-mails - self\_get\_emails() - `self_get_emails()` ```{.pl} $emails = $gitlab->self_get_emails(); $emails = $gitlab->self_get_emails(); ``` Returns a list of **secondary** e-mails for the user that makes the request. Returns a list of **secondary** e-mails for the user that makes the request. Note that primary e-mail can be obtained from the result of `whoami`. Note that primary e-mail can be obtained from the result of `whoami`. - user\_get\_emails() - `user_get_emails()` ```{.pl} $emails = $gitlab->user_get_emails( :uid ); $emails = $gitlab->user_get_emails( :uid ); ``` Returns a list of **secondary** e-mails for the user with the `uid`. Returns a list of **secondary** e-mails for the user with the `uid`. Note that primary e-mail can be obtained from the result of `user_by_id`. Note that primary e-mail can be obtained from the result of `user_by_id`. - self\_get\_email() - `self_get_email()` ```{.pl} $email = $gitlab->self_get_email( :eid ); $email = $gitlab->self_get_email( :eid ); ``` Returns the e-mail with the given `eid` of the user that makes the request. Returns the e-mail with the given `eid` of the user that makes the request. - self\_add\_email() - `self_add_email()` ```{.pl} $email = $gitlab->self_add_email( :email ); $email = $gitlab->self_add_email( :email ); ``` Adds a new `email` for the user that makes the request. The e-mail must Adds a new `email` for the user that makes the request. The e-mail must not exist in GitLab. not exist in GitLab. - user\_add\_email() - `user_add_email()` ```{.pl} $email = $gitlab->user_add_email( :uid, :email ); $email = $gitlab->user_add_email( :uid, :email ); ``` Adds a new `email` for the user with the given `uid`. The e-mail must Adds a new `email` for the user with the given `uid`. The e-mail must not exist in GitLab. not exist in GitLab. - self\_delete\_email() - `self_delete_email()` ```{.pl} $gitlab->self_delete_email( :eid ); $gitlab->self_delete_email( :eid ); ``` Deletes the e-mail with `eid` of the user that makes the request. Deletes the e-mail with `eid` of the user that makes the request. - user\_delete\_email() - `user_delete_email()` ```{.pl} $gitlab->user_delete_email( :uid, :eid ); $gitlab->user_delete_email( :uid, :eid ); ``` Removes the e-mail with `eid` of the user with the given `uid`. Removes the e-mail with `eid` of the user with the given `uid`. ## Account blocking ## Account blocking - user\_block() - `user_block()` ```{.pl} $gitlab->user_block( :uid ); $gitlab->user_block( :uid ); ``` Blocks the user with `uid` in the GitLab. Blocks the user with `uid` in the GitLab. - user\_unblock() - `user_unblock()` ```{.pl} $gitlab->user_unblock( :uid ); $gitlab->user_unblock( :uid ); ``` Unblocks the user with `uid` in the GitLab. Unblocks the user with `uid` in the GitLab. Note that LDAP blocked users cannot be unblocked by this function. Note that LDAP blocked users cannot be unblocked by this function. In that case the API would return `403 Forbidden`. In that case the API would return `403 Forbidden`. # AUTHOR # AUTHOR Roman Lacko <[xlacko1@fi.muni.cz](https://metacpan.org/pod/xlacko1@fi.muni.cz)> Roman Lacko <[`xlacko1@fi.muni.cz`](mailto:xlacko1@fi.muni.cz)> # SEE ALSO # SEE ALSO - [GitLab](https://metacpan.org/pod/GitLab) - [GitLab](pod-GitLab.md) Wrapper around [GitLab::API](https://metacpan.org/pod/GitLab::API) and other `GitLab::*` modules. Wrapper around [GitLab::API](pod-GitLab-API.md) and other `GitLab::*` modules. Loading
pod-GitLab-Users.md +138 −79 Original line number Original line Diff line number Diff line # NAME # NAME GitLab::Users - implements user API calls `GitLab::Users` - implements user API calls See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and response formats. response formats. Loading @@ -12,11 +12,12 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`. # SYNOPSIS # SYNOPSIS ```{.pl} use GitLab::API; use GitLab::API; use GitLab::Users; use GitLab::Users; # all calls from GitLab::Users are "injected" into the GitLab::API as methods # all calls from GitLab::Users are "injected" into the GitLab::API as methods my $api = GitLab::API->new(); my $api = GitLab::API->new(...); my $john = $api->users(username => "john_doe"); my $john = $api->users(username => "john_doe"); Loading @@ -26,21 +27,26 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`. username => "jane.doe", username => "jane.doe", name => "Jane Doe" name => "Jane Doe" ); ); ``` # DESCRIPTION # DESCRIPTION ## Notation ## Notation All methods take a hash of arguments as specified in the documentation for All methods take a hash of arguments as specified in the documentation for ["exec\_request" in GitLab::API](https://metacpan.org/pod/GitLab::API#exec_request), but to simplify the documentation, [`exec_request` in GitLab::API](pod-GitLab-API.md#exec_request), but to simplify the documentation, we will use the following notation: we will use the following notation: ```{.rb} users( :username, :search ) users( :username, :search ) ``` which means that the `users` method takes a hash with two keys, `username` which means that the `users` method takes a hash with two keys, `username` and `search`, so it can be called as and `search`, so it can be called as ```{.pl} $gitlab->users(search => "john_doe"); $gitlab->users(search => "john_doe"); ``` Optional arguments are denoted as ` [:username] `. Optional arguments are denoted as ` [:username] `. Note that not all optional arguments are listed. Note that not all optional arguments are listed. Loading @@ -48,47 +54,61 @@ Please refer to the official documentation for the full list. ## User CRUD operations ## User CRUD operations - users() - `users()` ```{.pl} $users = $gitlab->users( [:username], [:search] ); $users = $gitlab->users( [:username], [:search] ); ``` This method returns all users. The optional arguments can be used This method returns all users. The optional arguments can be used to filter out the results: to filter out the results: username search for a user by his username (exact match) | argument | description | search search for users with username or email (substring match) | ------------- | ----------- | | `username` | search for a user by his username (**exact match**) | | `search` | search for users with username or email (**substring match**) | Note that the returned value is still an array even when `users(username => $username)` Note that the returned value is still an array even when `users(username => $username)` always returns at most one result. always returns at most one result. - user\_by\_id() - `user_by_id()` ```{.pl} $user = $gitlab->user_by_id( :uid ); $user = $gitlab->user_by_id( :uid ); ``` Returns a user with the given `uid`. Returns a user with the given `uid`. - user\_create() - `user_create()` $user = $gitlab->user_create( :email, :password, :username, :name ); ```{.pl} $user = $gitlab->user_create( :email, :password, :username, :name [, ...]); ``` Creates a new user and if succeeds, returns the generated account information. Creates a new user and if succeeds, returns the generated account information. email primary email, must not exist in GitLab, | argument | description | password user password, | ------------------- | ----------- | username login, must not exist in GitLab, | `email` | primary email, must not exist in GitLab | name display name | `password` | user password | | `username` | login, must not exist in GitLab | | `name` | display name | The function can take many optional arguments. Please see the API documentation for The function can take many optional arguments. Please see the API documentation for the full list. Most interesting arguments are: the full list. Most interesting arguments are: admin create an admin account (bool) | argument | description | can_create_group the user will be able to create group (bool) | -------- | ----------- | external create an external account (bool) | `admin` | create an admin account (bool) | projects_limit maximum number of projects the user can own | `can_create_group` | the user will be able to create group (bool) | | `external` | create an external account (bool) | | `projects_limit` | maximum number of projects the user can own | - user\_update() - `user_update()` ```{.pl} $user = $gitlab->user_update( :uid ); $user = $gitlab->user_update( :uid ); ``` Updates the user with the given `uid`. It takes the same arguments as `user_create` Updates the user with the given `uid`. It takes the same arguments as `user_create` except they are all optional. Note that though it is possible to change user's primary e-mail except they are all optional. Note that though it is possible to change user's primary e-mail Loading @@ -96,150 +116,189 @@ Please refer to the official documentation for the full list. Also, from documentation: Also, from documentation: Note, at the moment this method does only return a 404 error, even in cases where > Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. > a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one. - user\_delete() - `user_delete()` ```{.pl} $gitlab->user_delete( :uid ); $gitlab->user_delete( :uid ); ``` Deletes the user with the given `uid`. Deletes the user with the given `uid`. Note that Note that calling this function for a non-existent user id still returns a status code 200 OK. > calling this function for a non-existent user id still returns a status code 200 OK. The JSON response differs if the user was actually deleted or not. > The JSON response differs if the user was actually deleted or not. (from the GitLab API documentation). (from the GitLab API documentation). - user() - `user()` ```{.pl} $user = $gitlab->user(); $user = $gitlab->user(); ``` Returns the user whose authentication key is used for the request Returns the user whose authentication key is used for the request (or impersonated user if `sudo` is in effect). (or impersonated user if `sudo` is in effect). Behaves the same as the ["whoami" in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method. Behaves the same as the [`whoami` in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method. ## SSH keys ## SSH keys - self\_ssh\_keys() - `self_ssh_keys()` ```{.pl} $keys = $gitlab->self_ssh_keys(); $keys = $gitlab->self_ssh_keys(); ``` Returns a list of SSH keys for the user that makes the request. Returns a list of SSH keys for the user that makes the request. - self\_get\_ssh\_key() - `self_get_ssh_key()` ```{.pl} $key = $gitlab->self_get_ssh_key( :keyid ); $key = $gitlab->self_get_ssh_key( :keyid ); ``` For the user that makes the request, the function returns the SSH key with the given `keyid`. For the user that makes the request, the function returns the SSH key with the given `keyid`. - user\_get\_ssh\_keys() - `user_get_ssh_keys()` ```{.pl} $keys = $gitlab->user_get_ssh_keys( :uid ); $keys = $gitlab->user_get_ssh_keys( :uid ); ``` Returns a list of SSH keys for the user with the given `uid`. Returns a list of SSH keys for the user with the given `uid`. - self\_add\_ssh\_key() - `self_add_ssh_key()` ```{.pl} $key = $gitlab->self_add_ssh_key( :title, :key ); $key = $gitlab->self_add_ssh_key( :title, :key ); ``` Adds a new key for the user that makes the request. Required arguments are Adds a new key for the user that makes the request. Required arguments are title the title of the key | argument | description | key public SSH key | -------- | ----------- | | `title` | the title of the key | | `key` | public SSH key | - user\_add\_ssh\_key() - `user_add_ssh_key()` ```{.pl} $key = $gitlab->user_add_ssh_key( :uid, :title, :key ); $key = $gitlab->user_add_ssh_key( :uid, :title, :key ); ``` Similar to `self_add_ssh_key`, but targets the user with the given `uid`. Similar to `self_add_ssh_key`, but targets the user with the given `uid`. - self\_delete\_ssh\_key() - `self_delete_ssh_key()` ```{.pl} $gitlab->self_delete_ssh_key( :keyid ) $gitlab->self_delete_ssh_key( :keyid ) ``` Removes the SSH key with the given `keyid` for the user that makes the request. Removes the SSH key with the given `keyid` for the user that makes the request. - user\_delete\_ssh\_key() - `user_delete_ssh_key()` ```{.pl} $gitlab->user_delete_ssh_key( :uid, :keyid ); $gitlab->user_delete_ssh_key( :uid, :keyid ); ``` Removes the SSH key with the `keyid` for the user with the given `uid`. Removes the SSH key with the `keyid` for the user with the given `uid`. ## E-mails ## E-mails - self\_get\_emails() - `self_get_emails()` ```{.pl} $emails = $gitlab->self_get_emails(); $emails = $gitlab->self_get_emails(); ``` Returns a list of **secondary** e-mails for the user that makes the request. Returns a list of **secondary** e-mails for the user that makes the request. Note that primary e-mail can be obtained from the result of `whoami`. Note that primary e-mail can be obtained from the result of `whoami`. - user\_get\_emails() - `user_get_emails()` ```{.pl} $emails = $gitlab->user_get_emails( :uid ); $emails = $gitlab->user_get_emails( :uid ); ``` Returns a list of **secondary** e-mails for the user with the `uid`. Returns a list of **secondary** e-mails for the user with the `uid`. Note that primary e-mail can be obtained from the result of `user_by_id`. Note that primary e-mail can be obtained from the result of `user_by_id`. - self\_get\_email() - `self_get_email()` ```{.pl} $email = $gitlab->self_get_email( :eid ); $email = $gitlab->self_get_email( :eid ); ``` Returns the e-mail with the given `eid` of the user that makes the request. Returns the e-mail with the given `eid` of the user that makes the request. - self\_add\_email() - `self_add_email()` ```{.pl} $email = $gitlab->self_add_email( :email ); $email = $gitlab->self_add_email( :email ); ``` Adds a new `email` for the user that makes the request. The e-mail must Adds a new `email` for the user that makes the request. The e-mail must not exist in GitLab. not exist in GitLab. - user\_add\_email() - `user_add_email()` ```{.pl} $email = $gitlab->user_add_email( :uid, :email ); $email = $gitlab->user_add_email( :uid, :email ); ``` Adds a new `email` for the user with the given `uid`. The e-mail must Adds a new `email` for the user with the given `uid`. The e-mail must not exist in GitLab. not exist in GitLab. - self\_delete\_email() - `self_delete_email()` ```{.pl} $gitlab->self_delete_email( :eid ); $gitlab->self_delete_email( :eid ); ``` Deletes the e-mail with `eid` of the user that makes the request. Deletes the e-mail with `eid` of the user that makes the request. - user\_delete\_email() - `user_delete_email()` ```{.pl} $gitlab->user_delete_email( :uid, :eid ); $gitlab->user_delete_email( :uid, :eid ); ``` Removes the e-mail with `eid` of the user with the given `uid`. Removes the e-mail with `eid` of the user with the given `uid`. ## Account blocking ## Account blocking - user\_block() - `user_block()` ```{.pl} $gitlab->user_block( :uid ); $gitlab->user_block( :uid ); ``` Blocks the user with `uid` in the GitLab. Blocks the user with `uid` in the GitLab. - user\_unblock() - `user_unblock()` ```{.pl} $gitlab->user_unblock( :uid ); $gitlab->user_unblock( :uid ); ``` Unblocks the user with `uid` in the GitLab. Unblocks the user with `uid` in the GitLab. Note that LDAP blocked users cannot be unblocked by this function. Note that LDAP blocked users cannot be unblocked by this function. In that case the API would return `403 Forbidden`. In that case the API would return `403 Forbidden`. # AUTHOR # AUTHOR Roman Lacko <[xlacko1@fi.muni.cz](https://metacpan.org/pod/xlacko1@fi.muni.cz)> Roman Lacko <[`xlacko1@fi.muni.cz`](mailto:xlacko1@fi.muni.cz)> # SEE ALSO # SEE ALSO - [GitLab](https://metacpan.org/pod/GitLab) - [GitLab](pod-GitLab.md) Wrapper around [GitLab::API](https://metacpan.org/pod/GitLab::API) and other `GitLab::*` modules. Wrapper around [GitLab::API](pod-GitLab-API.md) and other `GitLab::*` modules.
