Awesome

AzAPICall

You want to have an easy way to interact with the Microsoft Azure API endpoints without getting headache of taking care of valid bearer token and error handling?

Table of content

• AzAPICall
  • Table of content
  • AzAPICall example
    • Get & Set AzAPICall PowerShell module
    • Initialize AzAPICall
    • How to use AzAPICall ?!
      • Example for Microsoft Graph
      • Example for Azure Resource Manager
  • Public functions
  • Supported endpoints
  • General Parameters
  • AzAPICall Parameters
  • Good to know
    • Don´t accept the defaults
    • AzAPICall Tracking
  • Prerequisites
    • Powershell Modules
  • Contribute

AzAPICall example

Get & Set AzAPICall PowerShell module

Install-Module -Name AzAPICall
#Import-Module -Name AzAPICall

Connect to Azure

Connect-AzAccount

Initialize AzAPICall

$parameters4AzAPICallModule = @{
    #SubscriptionId4AzContext = $null #specify Subscription Id #[string]
    #TenantId4AzContext = $null #specify Tenant Id #[string]
    #DebugAzAPICall = $true #[bool]
    #WriteMethod = 'Output' #Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host) #[string]
    #DebugWriteMethod = 'Warning' #Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host) #[string]
    #SkipAzContextSubscriptionValidation = $true #Only use in case you do not have any valid (quotaId != AAD_* & state != disabled) subscriptions in your tenant OR you do not have any permissions on Azure Resources (Management Groups, Subscriptions, Resource Groups, Resources) and but want to connect non-ARM API endpoints such as Microsoft Graph etc. #[bool]
    #AzAPICallCustomRuleSet = $object #wip #[object]
}
$azAPICallConf = initAzAPICall @parameters4AzAPICallModule

How to use AzAPICall ?!

Example for Microsoft Graph

Get AAD Groups:

AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)/v1.0/groups" -AzAPICallConfiguration $azAPICallConf

confused by '$($azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)'? It´s basically a reference to the correct endpoint (think public cloud, sovereign clouds). You can of course also hardcode the endpoint URI:

AzAPICall -uri "https://graph.microsoft.com/v1.0/groups" -AzAPICallConfiguration $azAPICallConf

Example for Azure Resource Manager

List Azure Subscriptions (expect multiple results):

AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions?api-version=2020-01-01" -AzAPICallConfiguration $azAPICallConf

Get Azure Subscription (expect one result):

AzAPICall -uri "$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions/$($subscriptionId)?api-version=2020-01-01" -AzAPICallConfiguration $azAPICallConf -listenOn Content

AzAPICallExample.ps1

Public functions

• initAzAPICall
• AzAPICall
• getAzAPICallFunctions
• getAzAPICallRuleSet
• createBearerToken

createBearerToken example:

$azAPICallConf = initAzAPICall
createBearerToken -AzAPICallConfiguration $azapicallconf -targetEndPoint 'Storage'
Write-Host 'here is the token:' $azAPICallConf['htBearerAccessToken'].Storage

Supported endpoints

Add a new endpoint -> setAzureEnvironment.ps1

General Parameters

Parameters that can be used with the initAzAPICall cmdlet

Example: Initialize AzAPICall

AzAPICall Parameters

Parameters that can be used with the AzAPICall cmdlet

Example: AzAPICall -uri "https://management.azure.com/subscriptions?api-version=2020-01-01" -AzAPICallConfiguration $azAPICallConf

Good to know

Don´t accept the defaults

By default, endPoints return results in batches of e.g. 100. You can increase the return count defining e.g. $top=999 ($top requires use of consistencyLevel = eventual)

AzAPICall Tracking

To get some insights on all API calls you can check the $azAPICallConf['arrayAPICallTracking'] object (synchronized ArrayList)

$azAPICallConf['arrayAPICallTracking'][0] | ConvertTo-Json

{
  "CurrentTask": "Microsoft Graph API: Get - Groups",
  "TargetEndpoint": "MicrosoftGraph",
  "Uri": "https://graph.microsoft.com/v1.0/groups?$top=999&$filter=(mailEnabled eq false and securityEnabled eq true)&$select=id,createdDateTime,displayName,description&$orderby=displayName asc&$count=true",
  "Method": "GET",
  "TryCounter": 0,
  "TryCounterUnexpectedError": 0,
  "RetryAuthorizationFailedCounter": 0,
  "RestartDueToDuplicateNextlinkCounter": 0,
  "TimeStamp": "2022011316040343",
  "Duration": 1.3137266,
  "StatusCode": 404,
  "StatusCodePhrase": "NotFound",
  "rawException": "{
                    "Exception": {
                      "Response": {
                        "Version": "1.1",
                        "Content": "System.Net.Http.HttpConnectionResponseContent",
                        "StatusCode": 404,
                        "ReasonPhrase": "Not Found",
                        [..]
                      },
                      [..]
                    },
                    [..]
                  }"

As well you can see how fast a AzAPICall was responding:

($azAPICallConf['arrayAPICallTracking'].Duration | Measure-Object -Average -Maximum -Minimum) | ConvertTo-Json

{
  "Count": 1000,
  "Average": 0.4292551101999999,
  "Sum": null,
  "Maximum": 2.7991866,
  "Minimum": 0.263543,
  "StandardDeviation": null,
  "Property": null
}

Prerequisites

Powershell Modules

Contribute

Your contribution is welcome.

Thanks to the awesome contributors:

• Brooks Vaugn
• Kai Schulz
• Simon Wahlin
• Tim Stock
• Tim Wanierke