Functions/Get-GSuiteGroup.ps1

<#
.SYNOPSIS
    This function retrieves one GSuite group or all GSuite groups in a domain.
    This function returns either PSCustomObject when there is one group, or Object[] when there is more than one group.
#>

function Get-GSuiteGroup {
    [CmdletBinding(PositionalBinding=$false)]
    [OutputType([Object[]], [PSCustomObject])]
    param (
        # The primary email address for the group.
        [Parameter(Mandatory=$true, ParameterSetName="Email")]
        [ValidateNotNullOrEmpty()]
        [String]$primaryEmailAddress,

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

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

    # Validate that the 'connection' has been established and the group access token exists
    Assert-GSuiteConnection -Scope "Group"

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

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

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

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

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

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

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