{"id":21966002,"url":"https://github.com/julianhayward/azapicall","last_synced_at":"2025-04-24T04:17:52.583Z","repository":{"id":41869151,"uuid":"355275769","full_name":"JulianHayward/AzAPICall","owner":"JulianHayward","description":"PowerShell module Azure REST API call handler for ARM, Microsoft Graph, KeyVault, LogAnalytics","archived":false,"fork":false,"pushed_at":"2025-04-17T09:45:39.000Z","size":2169,"stargazers_count":35,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-24T04:17:46.574Z","etag":null,"topics":["azure","azure-resource-manager","microsoft-graph","powershell","powershell-module","rest-api"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JulianHayward.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-06T17:29:53.000Z","updated_at":"2025-04-02T12:07:14.000Z","dependencies_parsed_at":"2023-02-06T00:30:56.808Z","dependency_job_id":"2050d44d-c599-4e8a-ae44-6079dbc9b870","html_url":"https://github.com/JulianHayward/AzAPICall","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianHayward%2FAzAPICall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianHayward%2FAzAPICall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianHayward%2FAzAPICall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JulianHayward%2FAzAPICall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JulianHayward","download_url":"https://codeload.github.com/JulianHayward/AzAPICall/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250560061,"owners_count":21450173,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure","azure-resource-manager","microsoft-graph","powershell","powershell-module","rest-api"],"created_at":"2024-11-29T12:54:13.438Z","updated_at":"2025-04-24T04:17:52.568Z","avatar_url":"https://github.com/JulianHayward.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AzAPICall\n\n[![PowerShell Gallery Version (including pre-releases)](https://img.shields.io/powershellgallery/v/AzAPICall?include_prereleases\u0026label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/AzAPICall)\n\nYou 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?\n\n## Table of content\n\n- [AzAPICall](#azapicall)\n  - [Table of content](#table-of-content)\n  - [AzAPICall example](#azapicall-example)\n    - [Get \\\u0026 Set AzAPICall PowerShell module](#get--set-azapicall-powershell-module)\n    - [Initialize AzAPICall](#initialize-azapicall)\n    - [How to use AzAPICall ?!](#how-to-use-azapicall-)\n      - [Example for Microsoft Graph](#example-for-microsoft-graph)\n      - [Example for Azure Resource Manager](#example-for-azure-resource-manager)\n  - [Public functions](#public-functions)\n  - [Supported endpoints](#supported-endpoints)\n  - [General Parameters](#general-parameters)\n  - [AzAPICall Parameters](#azapicall-parameters)\n  - [Good to know](#good-to-know)\n    - [Don´t accept the defaults](#dont-accept-the-defaults)\n    - [AzAPICall Tracking](#azapicall-tracking)\n  - [Runtime environment](#runtime-environment)\n    - [Azure DevOps](#azure-devops)\n  - [Prerequisites](#prerequisites)\n    - [Powershell Modules](#powershell-modules)\n  - [Contribute](#contribute)\n\n## AzAPICall example\n\n### Get \u0026 Set AzAPICall PowerShell module\n\n```POWERSHELL\nInstall-Module -Name AzAPICall\n#Import-Module -Name AzAPICall\n```\n\nConnect to Azure\n\n```POWERSHELL\nConnect-AzAccount\n```\n\n### Initialize AzAPICall\n\n```POWERSHELL\n$parameters4AzAPICallModule = @{\n    #SubscriptionId4AzContext = $null #specify Subscription Id #[string]\n    #TenantId4AzContext = $null #specify Tenant Id #[string]\n    #DebugAzAPICall = $true #[bool]\n    #WriteMethod = 'Output' #Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host) #[string]\n    #DebugWriteMethod = 'Warning' #Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host) #[string]\n    #SkipAzContextSubscriptionValidation = $true #Only use in case you do not have any valid (quotaId != AAD_* \u0026 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]\n    #AzAPICallCustomRuleSet = $object #wip #[object]\n}\n$azAPICallConf = initAzAPICall @parameters4AzAPICallModule\n```\n\n### How to use AzAPICall ?\n\n#### Example for Microsoft Graph\n\nGet AAD Groups:\n\n```POWERSHELL\nAzAPICall -uri \"$($azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)/v1.0/groups\" -AzAPICallConfiguration $azAPICallConf\n```\n\n_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:_\n\n```POWERSHELL\nAzAPICall -uri \"https://graph.microsoft.com/v1.0/groups\" -AzAPICallConfiguration $azAPICallConf\n```\n\n#### Example for Azure Resource Manager\n\nList Azure Subscriptions (expect multiple results):\n\n```POWERSHELL\nAzAPICall -uri \"$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions?api-version=2020-01-01\" -AzAPICallConfiguration $azAPICallConf\n```\n\nGet Azure Subscription (expect one result):\n\n```POWERSHELL\nAzAPICall -uri \"$($azAPICallConf['azAPIEndpointUrls'].ARM)/subscriptions/$($subscriptionId)?api-version=2020-01-01\" -AzAPICallConfiguration $azAPICallConf -listenOn Content\n```\n\n[AzAPICallExample.ps1](pwsh/AzAPICallExample.ps1)\n\n## Public functions\n\n- initAzAPICall\n\n- AzAPICall\n- getAzAPICallFunctions\n- getAzAPICallRuleSet\n- createBearerToken\n\ncreateBearerToken example:\n\n```POWERSHELL\n$azAPICallConf = initAzAPICall\ncreateBearerToken -AzAPICallConfiguration $azapicallconf -targetEndPoint 'Storage'\nWrite-Host 'here is the token:' $azAPICallConf['htBearerAccessToken'].Storage\n```\n\n## Supported endpoints\n\n| Endpoint                                                                                                                 | Endpoint URL (AzureCloud)                                                                                    | Variable                                                                                                    |\n| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |\n| [Microsoft Graph](https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0)                               | `https://graph.microsoft.com`                                                                                | `$azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph`                                                        |\n| [ARM (Azure Resource Management)](https://docs.microsoft.com/en-us/rest/api/resources/)                                  | `https://management.azure.com`\u003cbr\u003e(or regional: `https://westus.management.azure.com`)                       | `$azAPICallConf['azAPIEndpointUrls'].ARM`\u003cbr\u003e(or regional: `$azAPICallConf['azAPIEndpointUrls'].ARMwestus`) |\n| [Azure Key Vault](https://docs.microsoft.com/en-us/rest/api/keyvault/)                                                   | `https://vault.azure.net`                                                                                    | `$azAPICallConf['azAPIEndpointUrls'].KeyVault`                                                              |\n| [Log Analytics](https://docs.microsoft.com/en-us/rest/api/loganalytics/)                                                 | `https://api.loganalytics.io/v1`                                                                             | `$azAPICallConf['azAPIEndpointUrls'].LogAnalytics`                                                          |\n| [Storage (blob)](https://learn.microsoft.com/en-us/rest/api/storageservices/)                                            | `https://\u003cstorageAccountName\u003e.blob.core.windows.net` / `https://\u003cstorageAccountName\u003e.blob.storage.azure.net` | https://_storageAccountName_.blob.core.windows.net /  https://_storageAccountName_.blob.storage.azure.net   |\n| [Monitor (ingest)](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/logs-ingestion-api-overview#rest-api-call) | `https://\u003cdce-endpoint\u003e.ingest.monitor.azure.com`                                                            | https://_dceEndpoint_```$($azAPICallConf['azAPIEndpointUrls'].MonitorIngest)```                             |\n\nAdd a new endpoint -\u003e setAzureEnvironment.ps1\n\n## General Parameters\n\nParameters that can be used with the initAzAPICall cmdlet\n\nExample: [Initialize AzAPICall](#initialize-azapicall)\n\n| Field                               |   Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                  | Required |\n| ----------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: |\n| DebugAzAPICall                      |  `bool`  | Set to `true` to enable debug output                                                                                                                                                                                                                                                                                                                                                                                         |          |\n| SubscriptionId4AzContext            | `string` | Specify if specific subscription should be used for the AzContext (Subscription Id / GUID)                                                                                                                                                                                                                                                                                                                                   |          |\n| TenantId4AzContext                  | `string` | Specify Tenant be used for the AzContext (Tenant Id / GUID)                                                                                                                                                                                                                                                                                                                                                                  |          |\n| WriteMethod                         | `string` | Write method. Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host)                                                                                                                                                                                                                                                                                                                            |          |\n| DebugWriteMethod                    | `string` | Write method in case of wanted or enforced debug. Debug, Error, Host, Information, Output, Progress, Verbose, Warning (default: host)                                                                                                                                                                                                                                                                                        |          |\n| AzAPICallCustomRuleSet              | `object` | wip                                                                                                                                                                                                                                                                                                                                                                                                                          |          |\n| SkipAzContextSubscriptionValidation |  `bool`  | Only use in case you do not have any valid (quotaId != AAD_* \u0026 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. (Per default a subscription is expected to be present in the Az context, if not then AzAPICall will throw..). |          |\n\n## AzAPICall Parameters\n\nParameters that can be used with the AzAPICall cmdlet\n\nExample: `AzAPICall -uri \"https://management.azure.com/subscriptions?api-version=2020-01-01\" -AzAPICallConfiguration $azAPICallConf`\n\n| Field                  |   Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                          Info                           |\n| ---------------------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------------------------------: |\n| uri                    | `string`  | `$azAPICallConf['azAPIEndpointUrls'].MicrosoftGraph)/v1.0/groups` which translates to: `https://graph.microsoft.com/v1.0/groups`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                  mandatory parameter ✅                  |\n| AzAPICallConfiguration | `object`  | Set of prebuilt (`$azAPICallConf = initAzAPICall`) variables required for AzAPICall operations (`-AzAPICallConfiguration $azAPICallConf`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                  mandatory parameter ✅                  |\n| method                 | `string`  | Method for the API request (e.g. `GET`, `POST`, ..)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                    default is `GET`                     |\n| currentTask            | `string`  | Free text field; in case of error or enabled `-DebugAzAPICall` currentTask will be output to console                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                         |\n| body                   | `string`  | Request Body for the API request - [Example](https://docs.microsoft.com/en-us/graph/api/group-post-owners?view=graph-rest-1.0\u0026tabs=http#request-body)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                         |\n| caller                 | `string`  | Set the value to `CustomDataCollection` for parallelization to have different font colors for the debug output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                         |\n| consistencyLevel       | `string`  | For several [OData query parameters](https://docs.microsoft.com/en-us/graph/query-parameters) the `consistencyLevel`-header need to be set to `eventual`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                         |\n| listenOn               | `string`  | Depending to the expected response of the API call the following values are accepted: `Value`, `Content`, `ContentProperties`, `Headers`, `StatusCode` or `Raw`. \u0026#128161; An example for the ARM Subscriptions API: To get _one_ defined subscription you would use `-listenOn Content`, for get/list _all_ subscriptions you would use no `-listenOn`-parameter as the default `listenOn`-value would be `Value`. Think [singular/plural](#example-for-azure-resource-manager)                                                                                                                                                                                                       |                   default is `Value`                    |\n| noPaging               | `switch`  | If value is `true` paging will be deactivated and you will only get the defined number of `$top` results or [Resource Graph limits any query to returning only `100` records](https://docs.microsoft.com/en-us/azure/governance/resource-graph/concepts/work-with-data). Otherwise, you can use `$top` to increase the result batches from default `100` up to `999` for the `AzAPICall`. Value for `$top` must range from 1 to 999                                                                                                                                                                                                                                                    |                                                         |\n| validateAccess         | `switch`  | Use this parameter if you only want to validate that the requester has permissions to the enpoint, if authorization is denied AzAPICall returns 'failed'. (Using `-validateAccess` will set `noPaging` to `true`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                         |\n| skipOnErrorCode        | `int32[]` | In some cases _(e.g. trying to add a user to a group were the user is already a member of)_ the API responde with an http status code 400. This is an expected error. To not throw an error and exit the script, you can use this parameter and set an expected error status code like `400`. You can also pass multiple errorcodes e.g. `-skipOnErrorCode 400,409`                                                                                                                                                                                                                                                                                                                    |                                                         |\n| unhandledErrorAction   | `string`  | When a call to an API returns an Error, that error is processed by AzAPICallErrorHandler. If that error is unhandled, AzAPICallErrorHandler will log the error and Throw a message which terminates the script. This happens when parameter -unhandledErrorAction is set to `Stop` (which is also the default if not configured). When -unhandledErrorAction is set to `Continue`, AzAPICallErrorHandler logs the error including full details to raise an issue at the repo and continues processing. When -unhandledErrorAction is set to `ContinueQuiet`, AzAPICallErrorHandler only logs the error (excluding full details to raise an issue at the repo) and continues processing | default is `Stop`, options: `Continue`, `ContinueQuiet` |\n\n## Good to know\n\n### Don´t accept the defaults\n\nBy 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`)\n\n### AzAPICall Tracking\n\nTo get some insights on all API calls you can check the `$azAPICallConf['arrayAPICallTracking']` object (synchronized ArrayList)\n\n```POWERSHELL\n$azAPICallConf['arrayAPICallTracking'][0] | ConvertTo-Json\n```\n\n```JSON\n{\n  \"CurrentTask\": \"Microsoft Graph API: Get - Groups\",\n  \"TargetEndpoint\": \"MicrosoftGraph\",\n  \"Uri\": \"https://graph.microsoft.com/v1.0/groups?$top=999\u0026$filter=(mailEnabled eq false and securityEnabled eq true)\u0026$select=id,createdDateTime,displayName,description\u0026$orderby=displayName asc\u0026$count=true\",\n  \"Method\": \"GET\",\n  \"TryCounter\": 0,\n  \"TryCounterUnexpectedError\": 0,\n  \"RetryAuthorizationFailedCounter\": 0,\n  \"RestartDueToDuplicateNextlinkCounter\": 0,\n  \"TimeStamp\": \"2022011316040343\",\n  \"Duration\": 1.3137266,\n  \"StatusCode\": 404,\n  \"StatusCodePhrase\": \"NotFound\",\n  \"rawException\": \"{\n                    \"Exception\": {\n                      \"Response\": {\n                        \"Version\": \"1.1\",\n                        \"Content\": \"System.Net.Http.HttpConnectionResponseContent\",\n                        \"StatusCode\": 404,\n                        \"ReasonPhrase\": \"Not Found\",\n                        [..]\n                      },\n                      [..]\n                    },\n                    [..]\n                  }\"\n```\n\nAs well you can see how fast a AzAPICall was responding:\n\n```POWERSHELL\n($azAPICallConf['arrayAPICallTracking'].Duration | Measure-Object -Average -Maximum -Minimum) | ConvertTo-Json\n```\n\n```JSON\n{\n  \"Count\": 1000,\n  \"Average\": 0.4292551101999999,\n  \"Sum\": null,\n  \"Maximum\": 2.7991866,\n  \"Minimum\": 0.263543,\n  \"StandardDeviation\": null,\n  \"Property\": null\n}\n```\n\n## Runtime environment\n\n### Azure DevOps\n\nIf you are using a PowerShell script within a pipeline and an `OIDC` service connection, you need to set the [`SYSTEM_ACCESSTOKEN` environment variable](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops\u0026tabs=yaml#systemaccesstoken) in the task of your pipeline. This allows the AzAPICall module to use it for token renewal:\n\n```YML\n  - task: AzurePowerShell@5\n    displayName: 'OIDC testing with AzurePowerShell@5'\n    env:\n      SYSTEM_ACCESSTOKEN: $(System.AccessToken)\n    inputs:\n      azureSubscription: '$(ServiceConnection)'\n      azurePowerShellVersion: LatestVersion\n      ScriptType: 'InlineScript'\n      Inline: |\n        try {\n            Install-Module -Name 'AzAPICall' -RequiredVersion '1.3.2' -ErrorAction Stop # ? https://www.powershellgallery.com/packages/AzAPICall/1.3.2\n        }\n        catch {\n            Write-Warning '33596ac3-5aab-4704-aef2-e1de6ac71f05'\n            Throw $_\n        }\n\n        # [..]\n```\n\nOtherwise, you will encounter an error message during your pipeline execution:\n\n```POWERSHELL\nLogging: /home/vsts/work/1/s/AzAPICall/functions/AzAPICallFunctions.ps1:1672\nLine |\n1672 |  …             Logging -logMessage \"-ERROR: OIDC ADO - Could not find ac …\n     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n     | -ERROR: OIDC ADO - Could not find access token, check if the environment\n     | variable 'SYSTEM_ACCESSTOKEN' exists and has valid data.\n     | https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops\u0026tabs=yaml#systemaccesstoken\n\n##[error]PowerShell exited with code '1'.\n```\n\n## Prerequisites\n\n### Powershell Modules\n\n| PowerShell Module |\n| ----------------- |\n| Az.Accounts       |\n\n## Contribute\n\nYour contribution is welcome.\n\nThanks to the awesome contributors:\n\n- Brooks Vaugn\n- Kai Schulz\n- Simon Wahlin\n- Tim Stock\n- Tim Wanierke\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulianhayward%2Fazapicall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulianhayward%2Fazapicall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulianhayward%2Fazapicall/lists"}