Skip to content

Commit 1c060be

Browse files
davidhaymonddavidhaymond
authored
Merge pull request #152 from Celerium/New-CommentBasedHelp
Addition of comment based help
2 parents 2126d66 + f8d8686 commit 1c060be

38 files changed

+5239
-222
lines changed

‎ITGlueAPI/ITGlueAPI.psd1

+2
Original file line numberDiff line numberDiff line change
@@ -108,13 +108,15 @@
108108
FunctionsToExport = 'Add-ITGlueAPIKey',
109109
'Get-ITGlueAPIKey',
110110
'Remove-ITGlueAPIKey',
111+
'Test-ITGlueAPIKey',
111112

112113
'Add-ITGlueBaseURI',
113114
'Get-ITGlueBaseURI',
114115
'Remove-ITGlueBaseURI',
115116

116117
'Export-ITGlueModuleSettings',
117118
'Import-ITGlueModuleSettings',
119+
'Remove-ITGlueModuleSettings',
118120

119121
'New-ITGlueAttachments',
120122
'Set-ITGlueAttachments',

‎ITGlueAPI/Internal/APIKey.ps1

+206-14
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,227 @@
11
function Add-ITGlueAPIKey {
2+
<#
3+
.SYNOPSIS
4+
Sets your API key used to authenticate all API calls.
5+
6+
.DESCRIPTION
7+
The Add-ITGlueAPIKey cmdlet sets your API key which is used to
8+
authenticate all API calls made to ITGlue.
9+
10+
ITGlue API keys can be generated via the ITGlue web interface
11+
Account > API Keys
12+
13+
.PARAMETER Api_Key
14+
Defines the API key that was generated from ITGlue.
15+
16+
.EXAMPLE
17+
Add-ITGlueAPIKey
18+
19+
Prompts to enter in the API key
20+
21+
.EXAMPLE
22+
Add-ITGlueAPIKey -Api_key 'some_api_key'
23+
24+
Will use the string entered into the [ -Api_Key ] parameter.
25+
26+
.EXAMPLE
27+
'12345' | Add-ITGlueAPIKey
28+
29+
Will use the string passed into it as its API key.
30+
31+
.NOTES
32+
N\A
33+
34+
.LINK
35+
https://github.com/itglue/powershellwrapper
36+
37+
#>
38+
239
[cmdletbinding()]
340
Param (
441
[Parameter(Mandatory = $false, ValueFromPipeline = $true)]
542
[AllowEmptyString()]
643
[Alias('ApiKey')]
744
[string]$Api_Key
845
)
9-
if ($Api_Key) {
10-
$x_api_key = ConvertTo-SecureString $Api_Key -AsPlainText -Force
1146

12-
Set-Variable -Name "ITGlue_API_Key" -Value $x_api_key -Option ReadOnly -Scope global -Force
47+
process{
48+
49+
if ($Api_Key) {
50+
$x_api_key = ConvertTo-SecureString $Api_Key -AsPlainText -Force
51+
52+
Set-Variable -Name "ITGlue_API_Key" -Value $x_api_key -Option ReadOnly -Scope global -Force
53+
}
54+
else {
55+
Write-Output "Please enter your API key:"
56+
$x_api_key = Read-Host -AsSecureString
57+
58+
Set-Variable -Name "ITGlue_API_Key" -Value $x_api_key -Option ReadOnly -Scope global -Force
59+
}
60+
1361
}
14-
else {
15-
Write-Host "Please enter your API key:"
16-
$x_api_key = Read-Host -AsSecureString
1762

18-
Set-Variable -Name "ITGlue_API_Key" -Value $x_api_key -Option ReadOnly -Scope global -Force
63+
}
64+
65+
66+
67+
function Get-ITGlueAPIKey {
68+
<#
69+
.SYNOPSIS
70+
Gets the ITGlue API key
71+
72+
.DESCRIPTION
73+
The Get-ITGlueAPIKey cmdlet gets the ITGlue API key from
74+
the global variable and returns it as a SecureString.
75+
76+
.EXAMPLE
77+
Get-ITGlueAPIKey
78+
79+
Gets the ITGlue API key global variable and returns it as a SecureString.
80+
81+
.NOTES
82+
N\A
83+
84+
.LINK
85+
https://github.com/itglue/powershellwrapper
86+
87+
#>
88+
89+
[cmdletbinding()]
90+
Param ()
91+
92+
if ($ITGlue_API_Key) {
93+
$ITGlue_API_Key
94+
}
95+
else{
96+
Write-Warning "No API key exists. Please run Add-ITGlueAPIKey to add one."
1997
}
98+
2099
}
21100

101+
102+
22103
function Remove-ITGlueAPIKey {
23-
Remove-Variable -Name "ITGlue_API_Key" -Scope global -Force
104+
<#
105+
.SYNOPSIS
106+
Removes the ITGlue API key
107+
108+
.DESCRIPTION
109+
The Remove-ITGlueAPIKey cmdlet removes the ITGlue API key from
110+
global variable.
111+
112+
.EXAMPLE
113+
Remove-ITGlueAPIKey
114+
115+
Removes the ITGlue API key global variable.
116+
117+
.NOTES
118+
N\A
119+
120+
.LINK
121+
https://github.com/itglue/powershellwrapper
122+
123+
#>
124+
125+
[cmdletbinding(SupportsShouldProcess)]
126+
Param ()
127+
128+
if ($ITGlue_API_Key) {
129+
Remove-Variable -Name "ITGlue_API_Key" -Scope global -Force -WhatIf:$WhatIfPreference
130+
}
131+
else{
132+
Write-Verbose 'The ITGlue API key variable is not set. Nothing to remove'
133+
}
24134
}
25135

26-
function Get-ITGlueAPIKey {
27-
if($null -eq $ITGlue_API_Key) {
28-
Write-Error "No API key exists. Please run Add-ITGlueAPIKey to add one."
136+
137+
138+
function Test-ITGlueAPIKey {
139+
<#
140+
.SYNOPSIS
141+
Test the ITGlue API key
142+
143+
.DESCRIPTION
144+
The Test-ITGlueAPIKey cmdlet tests the base URI & API key that are defined
145+
in the Add-ITGlueBaseURI & Add-ITGlueAPIKey cmdlets.
146+
147+
Helpful when needing to validate general functionality or when using
148+
RMM deployment tools
149+
150+
The ITGlue Regions endpoint is called in this test
151+
152+
.PARAMETER base_uri
153+
Define the base URI for the ITGlue API connection
154+
using ITGlue's URI or a custom URI.
155+
156+
By default the value used is the one defined by Add-ITGlueBaseURI function
157+
'https://api.itglue.com'
158+
159+
.EXAMPLE
160+
Test-ITGlueApiKey
161+
162+
Tests the base URI & API key that are defined in the
163+
Add-ITGlueBaseURI & Add-ITGlueAPIKey cmdlets.
164+
165+
.EXAMPLE
166+
Test-ITGlueApiKey -base_uri http://myapi.gateway.example.com
167+
168+
Tests the defined base URI & API key that was defined in
169+
the Add-ITGlueAPIKey cmdlet.
170+
171+
The full base uri test path in this example is:
172+
http://myapi.gateway.example.com/regions
173+
174+
.NOTES
175+
N\A
176+
177+
.LINK
178+
https://github.com/itglue/powershellwrapper
179+
180+
#>
181+
182+
[cmdletbinding()]
183+
Param (
184+
[parameter(Mandatory = $false)]
185+
[ValidateNotNullOrEmpty()]
186+
[string]$base_uri = $ITGlue_Base_URI
187+
)
188+
189+
$resource_uri = "/regions"
190+
191+
Write-Verbose "Testing API key against [ $($base_uri + $resource_uri) ]"
192+
193+
try {
194+
195+
$ITGlue_Headers.Add('x-api-key', (New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList 'N/A', $ITGlue_API_Key).GetNetworkCredential().Password)
196+
197+
$rest_output = Invoke-WebRequest -Method Get -Uri ($base_uri + $resource_uri) -Headers $ITGlue_Headers -ErrorAction Stop
29198
}
30-
else {
31-
$ITGlue_API_Key
199+
catch {
200+
201+
[PSCustomObject]@{
202+
Method = $_.Exception.Response.Method
203+
StatusCode = $_.Exception.Response.StatusCode.value__
204+
StatusDescription = $_.Exception.Response.StatusDescription
205+
Message = $_.Exception.Message
206+
URI = $($base_uri + $resource_uri)
207+
}
208+
209+
} finally {
210+
[void] ($ITGlue_Headers.Remove('x-api-key'))
211+
}
212+
213+
if ($rest_output){
214+
$data = @{}
215+
$data = $rest_output
216+
217+
[PSCustomObject]@{
218+
StatusCode = $data.StatusCode
219+
StatusDescription = $data.StatusDescription
220+
URI = $($base_uri + $resource_uri)
221+
}
32222
}
33223
}
34224

35-
New-Alias -Name Set-ITGlueAPIKey -Value Add-ITGlueAPIKey
225+
226+
227+
New-Alias -Name Set-ITGlueAPIKey -Value Add-ITGlueAPIKey

0 commit comments

Comments
 (0)