Skip to content

Commit c47fbdf

Browse files
markekrausjoeyaiello
markekraus
authored and
joeyaiello
committed
Document New -Form Parameter for Web Cmdlets (#2233)
* Add example to Invoke-RestMethod * Document -Form Feature in Invoke-RestMethod * Add Simplified Mulitpart/Form-Data example to Invoke-WebRequest * Document -Form Feature on Invoke-WebRequest
1 parent 4b834fd commit c47fbdf

File tree

2 files changed

+176
-0
lines changed

2 files changed

+176
-0
lines changed

‎reference/6/Microsoft.PowerShell.Utility/Invoke-RestMethod.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,40 @@ Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2
136136

137137
Some REST APIs support pagination via Relation Links per [RFC5988](https://tools.ietf.org/html/rfc5988#page-6). Instead of parsing the header to get the URL for the next page, you can have the cmdlet do this for you. This example returns the first two pages of issues from the PowerShell GitHub repository
138138

139+
### Example 4: Simplified Multipart/Form-Data Submission
140+
```powershell
141+
$Uri = 'https://api.contoso.com/v2/profile'
142+
$Form = @{
143+
firstName = 'John'
144+
lastName = 'Doe'
145+
email = 'john.doe@contoso.com'
146+
avatar = Get-Item -Path 'c:\Pictures\jdoe.png'
147+
birthday = '1980-10-15'
148+
hobbies = 'Hiking','Fishing','Jogging'
149+
}
150+
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form
151+
```
152+
153+
Some APIs require `multipart/form-data` submissions to upload files and mixed content.
154+
This example demonstrates updating a user profile.
155+
The profile form requires these fields:
156+
`firstName`, `lastName`, `email`, `avatar`, `birthday`, and `hobbies`.
157+
The API is expecting an image for the user profile pic to be supplied in the `avatar` field.
158+
The API will also accept multiple `hobbies` entries to be submitted in the same form.
159+
160+
When creating the `$Form` HashTable, the key names are used as form field names.
161+
By default, the values of the HashTable will be converted to strings.
162+
If a `System.IO.FileInfo` value is present, the file contents will be submitted.
163+
If a collection such as arrays or lists are present,
164+
the form field will be submitted will be submitted multiple times.
165+
166+
By using `Get-Item` on the `avatar` key, the `FileInfo` object will be set as the value.
167+
The result is that the image data for `jdoe.png` will be submitted.
168+
169+
By supplying a list to the `hobbies` key,
170+
the `hobbies` field will be present in the submissions
171+
once for each list item.
172+
139173
## Parameters
140174

141175
### -AllowUnencryptedAuthentication
@@ -350,6 +384,60 @@ Accept pipeline input: False
350384
Accept wildcard characters: False
351385
```
352386

387+
### -Form
388+
Converts a dictionary to a `multipart/form-data` submission.
389+
`-Form` may not be used with `-Body`.
390+
If `-ContentType` will be ignored.
391+
392+
The keys of the dictionary will be used as the form field names.
393+
By default, form values will be converted to string values.
394+
395+
If the value is a `System.IO.FileInfo` object,
396+
then the binary file contents will be submitted.
397+
The name of the file will be submitted as the `filename`.
398+
The MIME will be set as `application/octet-stream`.
399+
`Get-Item` can be used to simplify supplying the `System.IO.FileInfo` object.
400+
401+
```powershell
402+
$Form = @{
403+
resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf'
404+
}
405+
```
406+
407+
If the value is a collection type,
408+
such Arrays or Lists,
409+
the for field will be submitted multiple times.
410+
The values of the the list will be treated as strings by default.
411+
If the value is a `System.IO.FileInfo` object,
412+
then the binary file contents will be submitted.
413+
Nested collections are not supported.
414+
415+
```powershell
416+
$Form = @{
417+
tags = 'Vacation', 'Italy', '2017'
418+
pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy\'
419+
}
420+
```
421+
422+
In the above example the `tags` field will be supplied 3 times in the form,
423+
once for each of `Vacation`, `Italy`, and `2017`.
424+
The `pictures` field will also be submitted once for each file in the `2017-Italy` folder.
425+
The binary contents of the files in that folder will be submitted as the values.
426+
427+
This feature was added in PowerShell 6.1.0.
428+
429+
```yaml
430+
Type: IDictionary
431+
Parameter Sets: (All)
432+
Aliases:
433+
434+
Required: False
435+
Position: Named
436+
Default value: None
437+
Accept pipeline input: False
438+
Accept wildcard characters: False
439+
```
440+
353441
### -Headers
354442
Specifies the headers of the web request.
355443
Enter a hash table or dictionary.

‎reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,40 @@ $Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https
151151

152152
This example uses the `Invoke-WebRequest` cmdlet upload a file as a `multipart/form-data` submission. The file `c:\document.txt` will be submitted as the form field `document` with the `Content-Type` of `text/plain`.
153153

154+
### Example 5: Simplified Multipart/Form-Data Submission
155+
```powershell
156+
$Uri = 'https://api.contoso.com/v2/profile'
157+
$Form = @{
158+
firstName = 'John'
159+
lastName = 'Doe'
160+
email = 'john.doe@contoso.com'
161+
avatar = Get-Item -Path 'c:\Pictures\jdoe.png'
162+
birthday = '1980-10-15'
163+
hobbies = 'Hiking','Fishing','Jogging'
164+
}
165+
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $Form
166+
```
167+
168+
Some APIs require `multipart/form-data` submissions to upload files and mixed content.
169+
This example demonstrates updating a user profile.
170+
The profile form requires these fields:
171+
`firstName`, `lastName`, `email`, `avatar`, `birthday`, and `hobbies`.
172+
The API is expecting an image for the user profile pic to be supplied in the `avatar` field.
173+
The API will also accept multiple `hobbies` entries to be submitted in the same form.
174+
175+
When creating the `$Form` HashTable, the key names are used as form field names.
176+
By default, the values of the HashTable will be converted to strings.
177+
If a `System.IO.FileInfo` value is present, the file contents will be submitted.
178+
If a collection such as arrays or lists are present,
179+
the form field will be submitted will be submitted multiple times.
180+
181+
By using `Get-Item` on the `avatar` key, the `FileInfo` object will be set as the value.
182+
The result is that the image data for `jdoe.png` will be submitted.
183+
184+
By supplying a list to the `hobbies` key,
185+
the `hobbies` field will be present in the submissions
186+
once for each list item.
187+
154188
## PARAMETERS
155189

156190
### -AllowUnencryptedAuthentication
@@ -346,6 +380,60 @@ Accept pipeline input: False
346380
Accept wildcard characters: False
347381
```
348382

383+
### -Form
384+
Converts a dictionary to a `multipart/form-data` submission.
385+
`-Form` may not be used with `-Body`.
386+
If `-ContentType` will be ignored.
387+
388+
The keys of the dictionary will be used as the form field names.
389+
By default, form values will be converted to string values.
390+
391+
If the value is a `System.IO.FileInfo` object,
392+
then the binary file contents will be submitted.
393+
The name of the file will be submitted as the `filename`.
394+
The MIME will be set as `application/octet-stream`.
395+
`Get-Item` can be used to simplify supplying the `System.IO.FileInfo` object.
396+
397+
```powershell
398+
$Form = @{
399+
resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf'
400+
}
401+
```
402+
403+
If the value is a collection type,
404+
such Arrays or Lists,
405+
the for field will be submitted multiple times.
406+
The values of the the list will be treated as strings by default.
407+
If the value is a `System.IO.FileInfo` object,
408+
then the binary file contents will be submitted.
409+
Nested collections are not supported.
410+
411+
```powershell
412+
$Form = @{
413+
tags = 'Vacation', 'Italy', '2017'
414+
pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy\'
415+
}
416+
```
417+
418+
In the above example the `tags` field will be supplied 3 times in the form,
419+
once for each of `Vacation`, `Italy`, and `2017`.
420+
The `pictures` field will also be submitted once for each file in the `2017-Italy` folder.
421+
The binary contents of the files in that folder will be submitted as the values.
422+
423+
This feature was added in PowerShell 6.1.0.
424+
425+
```yaml
426+
Type: IDictionary
427+
Parameter Sets: (All)
428+
Aliases:
429+
430+
Required: False
431+
Position: Named
432+
Default value: None
433+
Accept pipeline input: False
434+
Accept wildcard characters: False
435+
```
436+
349437
### -Headers
350438
Specifies the headers of the web request.
351439
Enter a hash table or dictionary.

0 commit comments

Comments
 (0)