APIs/Invoke-CKMSGraphAPI.ps1

function Invoke-CKMSGraphAPIAPI {
    <#
    .SYNOPSIS
    Invoke the Microsoft Graph RESTful web API to access Microsoft Cloud service resources. A wrapper around the Invoke-RestMethod to make requests to the Microsoft Graph API.
     
    Author: Roberto Rodriguez (@Cyb3rWard0g)
    License: MIT
    Required Dependencies: None
    Optional Dependencies: None
     
    .DESCRIPTION
    Invoke-CKMSGraphAPIAPI is a simple PowerShell wrapper around the Invoke-RestMethod to make requests to the Microsoft Graph API.
     
    .PARAMETER AccessToken
    Access token obtained with the right permissions (delegated/Application) to use the MS Graph API.
 
    .PARAMETER APIType
    Type of Graph API. Microsoft Graph (MSGraph) or Azure Active Directory Graph (AADGraph).
 
    .PARAMETER APIEndpoint
    Which Graph API service endpoint: ('Global','US Gov L4','DOD','Germany','China')
 
    .PARAMETER HttpMethod
    The HTTP method used on the request to Microsoft Graph.
 
    Method Description
    ------ -----------
    GET Read data from a resource.
    POST Create a new resource, or perform an action.
    PATCH Update a resource with new values.
    PUT Replace a resource with a new one.
    DELETE Remove a resource.
     
    For the CRUD methods GET and DELETE, no request body is required.
    The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.
 
    .PARAMETER Version
    The version of the Microsoft Graph API your application is using.
 
    .PARAMETER Resource
    The resource in Microsoft Graph that you're referencing.
 
    .PARAMETER QueryParameters
    Optional OData query options or REST method parameters that customize the response.
 
    .PARAMETER SelectFields
    Specific properties/columns to return from objects using the $select query parameter.
 
    .PARAMETER Filter
    Filter results by using the $filter query parameter to retrieve just a subset of a collection.
 
    .PARAMETER PageSize
    Specific number of objects to return per page using the $top query parameter. $top sets the page size of results.
 
    .PARAMETER orderBy
    Order results by specific object properties using the $orderby query parameter. Sorting is defined by the parameter $sortIn in this function.
 
    .PARAMETER sortIn
    Sort results. This is used along with the $orderBy parameter in this function. Sort can be in ascensing and descening order. (e.g. desc or asc)
 
    .PARAMETER Body
    HTTP body request.
 
    .PARAMETER Headers
    HTTP Header request.
 
    .PARAMETER ContentType
    Content type to set the header object for the HTTP request.
 
    .PARAMETER InlineFilePath
    Path to a local file to pass through the HTTP request.
 
    .LINK
    https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0&preserve-view=true
    https://docs.microsoft.com/en-us/graph/use-the-api
    https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-request-differences
    #>


    [cmdletbinding()]
    Param(
        [Parameter(Mandatory = $True)]
        [String]$AccessToken,

        [Parameter(Mandatory = $false)]
        [ValidateSet('MSGraph', 'AADGraph')]
        [String]$APIType = 'MSGraph',

        [Parameter(Mandatory = $false)]
        [ValidateSet('Global','US Gov L4','DOD','Germany','China')]
        [String]$APIEndpoint = 'Global',

        [Parameter(Mandatory = $False)]
        [ValidateSet('Put', 'Get', 'Post', 'Delete', 'Patch')]
        [String]$HttpMethod = "Get",
        
        [parameter(Mandatory = $True)]
        [String]$Resource,
        
        [Parameter(Mandatory = $False)]
        [String]$QueryParameters,

        [parameter(Mandatory = $false)]
        [String]$SelectFields,

        [parameter(Mandatory = $false)]
        [String]$Filter,

        [parameter(Mandatory = $false)]
        [Int]$PageSize,

        [parameter(Mandatory = $false)]
        [String]$OrderBy,

        [parameter(Mandatory = $false)]
        [ValidateSet('desc','asc')]
        [String]$SortIn,

        [Parameter(Mandatory = $False)]
        [Object]$Body,
        
        [Parameter(Mandatory = $False)]
        [Object]$Headers,

        [Parameter(Mandatory = $False)]
        [String]$ContentType = "application/json",

        [Parameter(Mandatory = $False)]
        [string]$InlineFilePath

    )

    DynamicParam {
        # Adding Dynamic parameters
        $parameterDictionary = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary

        if ($APIType -eq 'MSGraph') {
            $ParamOptions = @(
                @{
                    'Name'                  = 'Version';
                    'ValidateSetOptions'    = @('v1.0', 'beta');
                    'Mandatory'             = $false
                }
            )
        }
        elseif ($APIType -eq 'AADGraph') {
            $ParamOptions = @(
                @{
                    'Name'                  = 'Version';
                    'ValidateSetOptions'    = @('api-version=1.6', 'api-version=1.61-internal');
                    'Mandatory'             = $false
                }
            )  
        }

        # Adding Dynamic parameter
        foreach ($NewParam in $ParamOptions) {
            $RuntimeParam = New-DynamicParam @NewParam
            $parameterDictionary.Add($NewParam.Name, $RuntimeParam)
        }
        return $parameterDictionary
    }

    Begin {
        # Service Endpoints
        if ($APIType -eq 'MSGraph') {
            switch ($APIEndpoint){
                'Global'    { $EndpointUrl = 'https://graph.microsoft.com' }
                'US Gov L4' { $EndpointUrl = 'https://graph.microsoft.us' }
                'DOD'       { $EndpointUrl = 'https://dod-graph.microsoft.us' }
                'Germany'   { $EndpointUrl = 'https://graph.microsoft.de' }
                'China'     { $EndpointUrl = 'https://microsoftgraph.chinacloudapi.cn' }
            }
        }
        else {
            switch ($APIEndpoint){
                'Global'    { $EndpointUrl = 'https://graph.windows.net' }
                'US Gov L4' { $EndpointUrl = 'https://graph.microsoftazure.us' }
                'DOD'       { $EndpointUrl = 'https://graph.microsoftazure.us' }
                'Germany'   { $EndpointUrl = 'https://graph.cloudapi.de' }
                'China'     { $EndpointUrl = 'https://graph.chinacloudapi.cn' }
            }

        }

        # Process Dynamic parameters
        if (-not $PSBoundParameters.ContainsKey('Version')) {
            if ($APIType -eq 'MSGraph') {
                $PSBoundParameters.Add('Version','v1.0')
            } else {
                $PsBoundParameters.Add('Version', 'api-version=1.61-internal')
            }
        }
        $PsBoundParameters.GetEnumerator() | ForEach-Object { New-Variable -Name $_.Key -Value $_.Value -ea 'SilentlyContinue'}
    }

    Process {
        if (-not ($Headers)) {
            $Headers = @{
                "Authorization" = "Bearer $AccessToken"
                "Content-Type"  = "$ContentType"
            }
            if ($ContentType){
                switch ($ContentType.ToLower()) {
                    "application/json" { $Body = $Body | ConvertTo-Json -Compress -Depth 20 }
                }
            }
        }

        $PredefinedParameters = @()
        # Process optional query parameters
        if(![String]::IsNullOrEmpty($SelectFields)){$PredefinedParameters += "`$select=$SelectFields"}
        if(![String]::IsNullOrEmpty($Filter)){$PredefinedParameters += "`$filter=$Filter"}
        if(![int]::Equals($PageSize,0)){$PredefinedParameters += "`$top=$PageSize"}
        if(![String]::IsNullOrEmpty($OrderBy) -and ![String]::IsNullOrEmpty($SortIn)){$PredefinedParameters += "`$orderby=$OrderBy $SortIn"}

        # Define HTTP request
        # Reference: https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-request-differences#basic-requests
        if ($APIType -eq 'MSGraph'){
            # https://graph.microsoft.com/{version}/{resource}?query-parameters
            $Uri = "$EndpointUrl/$Version/$Resource$(if($PredefinedParameters){"?$($PredefinedParameters -join '&')"}elseif(![String]::IsNullOrEmpty($QueryParameters)){"?$QueryParameters"})"
        }
        else {
            # https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters
            $Uri = "$EndpointUrl/myorganization/$Resource`?$($Version)$(if($PredefinedParameters){"&$($PredefinedParameters -join '&')"}elseif(![String]::IsNullOrEmpty($QueryParameters)){"?$QueryParameters"})"
        }
        
        $params = @{
            "Method"  = $HttpMethod
            "Uri"     = $Uri
            "Body"    = $Body
            "Headers" = $Headers
        }
        if ($InlineFilePath){
            $params['InFile'] = $InlineFilePath
        }
        # Invoke MS Graph API
        $Response = Invoke-RestMethod @params

        if ($Response.'@odata.nextLink') {
            $results = @()
            # Search through the response until there are no more nextlinks
            do {
                # Getting the next set of results
                $params = @{
                    "Method"  = "Get"
                    "Uri"     = $Response.'@odata.nextLink'
                    "Headers" = @{"Authorization" = "Bearer $AccessToken"}
                }
                $Response = Invoke-RestMethod @params
                # Add response of current iteration to array
                $results += $Response
            } until (-not $Response.'@odata.nextLink')
            # return value from array
            $results.value
        }
        else {
            if ($Response.value) {
                $Response.value
            }
            else {
                $Response
            }
        }
    }
}

function New-DynamicParam {
    [CmdletBinding()]
    [OutputType('System.Management.Automation.RuntimeDefinedParameter')]
    param (
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,
        [Parameter(Mandatory=$false)]
        [array]$ValidateSetOptions,
        [Parameter()]
        [switch]$Mandatory = $false,
        [Parameter()]
        [switch]$ValueFromPipeline = $false,
        [Parameter()]
        [switch]$ValueFromPipelineByPropertyName = $false
    )

    $Attrib = New-Object System.Management.Automation.ParameterAttribute
    $Attrib.Mandatory = $Mandatory.IsPresent
    $Attrib.ParameterSetName = "__AllParameterSets"
    $Attrib.ValueFromPipeline = $ValueFromPipeline.IsPresent
    $Attrib.ValueFromPipelineByPropertyName = $ValueFromPipelineByPropertyName.IsPresent

    # Create AttributeCollection object for the attribute
    $Collection = new-object System.Collections.ObjectModel.Collection[System.Attribute]
    # Add our custom attribute
    $Collection.Add($Attrib)
    # Add Validate Set
    if ($ValidateSetOptions)
    {
        $ValidateSet= new-object System.Management.Automation.ValidateSetAttribute($ValidateSetOptions)
        $Collection.Add($ValidateSet)
    }

    # Create Runtime Parameter
    $DynParam = New-Object System.Management.Automation.RuntimeDefinedParameter($Name, [string], $Collection)
    return $DynParam
}