BitTitan.Runbooks.GSuite

0.1.7

Functions/Get-GSuiteUser.ps1

<#
.SYNOPSIS
    This function retrieves one GSuite user or all GSuite users in a domain.
    This function returns either PSCustomObject when there is one user, or Object[] when there is more than one user.
#>
function Get-GSuiteUser {
    [CmdletBinding(PositionalBinding=$false)]
    [OutputType([Object[]], [PSCustomObject])]
    param (
        # The primary email address for the user.
        [Parameter(Mandatory=$true, ParameterSetName="Email")]
        [ValidateNotNullOrEmpty()]
        [String]$primaryEmailAddress,

        # The domain for the users.
        [Parameter(Mandatory=$true, ParameterSetName="Domain")]
        [ValidateNotNullOrEmpty()]
        [String]$domain,

        # Whether to retrieve all the GSuite users.
        [Parameter(Mandatory=$true, ParameterSetName="All")]
        [ValidateNotNull()]
        [Switch]$all
    )

    # Validate that the 'connection' has been established
    if (!$Global:GSuiteAccessTokensHashTable) {
        throw "You must call the Connect-GSuiteAdminAccount cmdlet before calling any other GSuite cmdlets."
    }

    # Validate that the user access token exists in the hash table
    if ([String]::IsNullOrWhiteSpace($Global:GSuiteAccessTokensHashTable.User)) {
        throw "User access token is required to call Get-GSuiteUser."
    }

    # Retrieve the user with the specified email address
    if ($primaryEmailAddress) {
        $Uri = "https://www.googleapis.com/admin/directory/v1/users/$($primaryEmailAddress)"
    }

    # Retrieve all the users in the specified domain
    elseif ($domain) {
        $Uri = "https://www.googleapis.com/admin/directory/v1/users?domain=$($domain)"
    }

    # Retrieve all the users
    else {
        $Uri = "https://www.googleapis.com/admin/directory/v1/users?customer=my_customer"
    }

    # Prepare the REST call parameters
    $invokeRestMethodParams = @{
        Uri     = $Uri
        Method  = "GET"
        Headers = @{
            Accept        = "application/json"
            Authorization = "Bearer $($Global:GSuiteAccessTokensHashTable.User)"
        }
    }

    # Invoke the REST call
    $response = Invoke-RestMethod @invokeRestMethodParams

    # Return the user if $primaryEmailAddress is specified
    if ($primaryEmailAddress) {
        return $response
    }

    # Return the users if $domain or $all is specified
    return $response.users
}