Invoke-RestMethod
Mengirim permintaan HTTP atau HTTPS ke layanan web RESTful.
Sintaks
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
[-Method <WebRequestMethod>]
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
-NoProxy
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Invoke-RestMethod
-CustomMethod <String>
[-FollowRelLink]
[-MaximumFollowRelLink <Int32>]
[-ResponseHeadersVariable <String>]
[-StatusCodeVariable <String>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-AllowUnencryptedAuthentication]
[-Authentication <WebAuthenticationType>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-SkipCertificateCheck]
[-SslProtocol <WebSslProtocol>]
[-Token <SecureString>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-MaximumRetryCount <Int32>]
[-RetryIntervalSec <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-Form <IDictionary>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[-Resume]
[-SkipHttpErrorCheck]
[-PreserveAuthorizationOnRedirect]
[-SkipHeaderValidation]
[<CommonParameters>] Deskripsi
Invoke-RestMethod Cmdlet mengirimkan permintaan HTTP dan HTTPS ke layanan web Representational State Transfer (REST) yang mengembalikan data yang kaya terstruktur.
PowerShell memformat respons berdasarkan jenis data. Untuk umpan RSS atau ATOM, PowerShell mengembalikan node Item atau Xml Entri. Untuk JavaScript Object Notation (JSON) atau XML, PowerShell mengonversi, atau mendeserialisasi, konten menjadi [PSCustomObject] objek.
Catatan
Saat titik akhir REST mengembalikan beberapa objek, objek diterima sebagai array. Jika Anda menyalurkan output dari Invoke-RestMethod ke perintah lain, output dikirim sebagai objek tunggal [Object[]] . Konten array tersebut tidak dijumlahkan untuk perintah berikutnya pada alur.
Cmdlet ini diperkenalkan di Windows PowerShell 3.0.
Dimulai di PowerShell 7.0, Invoke-RestMethod mendukung konfigurasi proksi yang ditentukan oleh variabel lingkungan. Lihat bagian Catatan di artikel ini.
Contoh
Contoh 1: Dapatkan umpan PowerShell RSS
Contoh ini menggunakan Invoke-RestMethod cmdlet untuk mendapatkan informasi dari umpan RSS Blog PowerShell. Perintah menggunakan Format-Table cmdlet untuk menampilkan nilai properti Judul dan pubDate dari setiap blog dalam tabel.
Invoke-RestMethod -Uri https://blogs.msdn.microsoft.com/powershell/feed/ |
Format-Table -Property Title, pubDate
Title pubDate
----- -------
Join the PowerShell 10th Anniversary Celebration! Tue, 08 Nov 2016 23:00:04 +0000
DSC Resource Kit November 2016 Release Thu, 03 Nov 2016 00:19:07 +0000
PSScriptAnalyzer Community Call - Oct 18, 2016 Thu, 13 Oct 2016 17:52:35 +0000
New Home for In-Box DSC Resources Sat, 08 Oct 2016 07:13:10 +0000
New Social Features on Gallery Fri, 30 Sep 2016 23:04:34 +0000
PowerShellGet and PackageManagement in PowerShell Gallery and GitHub Thu, 29 Sep 2016 22:21:42 +0000
PowerShell Security at DerbyCon Wed, 28 Sep 2016 01:13:19 +0000
DSC Resource Kit September Release Thu, 22 Sep 2016 00:25:37 +0000
PowerShell DSC and implicit remoting broken in KB3176934 Tue, 23 Aug 2016 15:07:50 +0000
PowerShell on Linux and Open Source! Thu, 18 Aug 2016 15:32:02 +0000Contoh 2: Jalankan permintaan POST
Dalam contoh ini, pengguna menjalankan Invoke-RestMethod untuk melakukan permintaan POST di situs web intranet di organisasi pengguna.
$Cred = Get-Credential
$Url = "https://server.contoso.com:8089/services/search/jobs/export"
$Body = @{
search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
output_mode = "csv"
earliest_time = "-2d@d"
latest_time = "-1d@d"
}
Invoke-RestMethod -Method 'Post' -Uri $url -Credential $Cred -Body $body -OutFile output.csvKredensial diminta dan kemudian disimpan di $Cred dan URL yang akan diakses ditentukan dalam $Url.
Variabel $Body menjelaskan kriteria pencarian, menentukan CSV sebagai mode output, dan menentukan periode waktu untuk data yang dikembalikan yang dimulai dua hari yang lalu dan berakhir satu hari yang lalu. Variabel isi menentukan nilai untuk parameter yang berlaku untuk REST API tertentu yang Invoke-RestMethod berkomunikasi.
Perintah Invoke-RestMethod dijalankan dengan semua variabel di tempat, menentukan jalur dan nama file untuk file output CSV yang dihasilkan.
Contoh 3: Mengikuti tautan relasi
Beberapa REST API mendukung penomoran halaman melalui Relation Links per RFC5988. Alih-alih mengurai header untuk mendapatkan URL untuk halaman berikutnya, Anda dapat meminta cmdlet melakukan ini untuk Anda. Contoh ini mengembalikan dua halaman pertama masalah dari repositori PowerShell GitHub.
$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2Contoh 4: Pengiriman Multipihak/Formulir-Data yang Disederhanakan
Beberapa API memerlukan multipart/form-data pengiriman untuk mengunggah file dan konten campuran. Contoh ini menunjukkan cara memperbarui profil pengguna.
$Uri = 'https://api.contoso.com/v2/profile'
$Form = @{
firstName = 'John'
lastName = 'Doe'
email = 'john.doe@contoso.com'
avatar = Get-Item -Path 'c:\Pictures\jdoe.png'
birthday = '1980-10-15'
hobbies = 'Hiking','Fishing','Jogging'
}
$Result = Invoke-RestMethod -Uri $Uri -Method Post -Form $FormFormulir profil memerlukan bidang-bidang ini: firstName, , lastName, emailavatar, birthday, dan hobbies. API mengharapkan gambar untuk gambar profil pengguna disediakan di avatar bidang . API juga akan menerima beberapa hobbies entri untuk dikirimkan dalam formulir yang sama.
Saat membuat $Form HashTable, nama kunci digunakan sebagai nama bidang formulir. Secara default, nilai HashTable akan dikonversi menjadi string. Jika ada System.IO.FileInfo nilai, konten file akan dikirimkan. Jika koleksi seperti array atau daftar ada, bidang formulir akan dikirimkan beberapa kali.
Dengan menggunakan Get-Item pada avatar kunci, FileInfo objek akan ditetapkan sebagai nilai . Hasilnya adalah bahwa data gambar untuk jdoe.png akan dikirimkan.
Dengan menyediakan daftar ke hobbies kunci, hobbies bidang akan ada dalam pengiriman sekali untuk setiap item daftar.
Contoh 5: Meneruskan beberapa header
API sering memerlukan header yang diteruskan untuk autentikasi atau validasi. Contoh ini menunjukkan, cara meneruskan beberapa header dari hash-table ke REST API.
$headers = @{
'userId' = 'UserIDValue'
'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $bodyContoh 6: Menghitung item yang dikembalikan pada alur
GitHub mengembalikan beberapa objek array. Jika Anda menyalurkan output ke perintah lain, output dikirim sebagai objek tunggal [Object[]].
Untuk menghitung objek ke dalam alur, pipa hasilnya ke Write-Output atau bungkus cmdlet dalam tanda kurung. Contoh berikut menghitung jumlah objek yang dikembalikan oleh GitHub. Kemudian menghitung jumlah objek yang dijumlahkan ke alur.
$uri = 'https://api.github.com/repos/microsoftdocs/powershell-docs/issues'
$x = 0
Invoke-RestMethod -Uri $uri | ForEach-Object { $x++ }
$x
1
$x = 0
(Invoke-RestMethod -Uri $uri) | ForEach-Object { $x++ }
$x
30
$x = 0
Invoke-RestMethod -Uri $uri | Write-Output | ForEach-Object { $x++ }
$x
30Contoh 7: Melewati Validasi Header
Secara default, Invoke-RestMethod cmdlet memvalidasi nilai header terkenal yang memiliki format nilai yang ditentukan standar. Contoh berikut menunjukkan bagaimana validasi ini dapat menimbulkan kesalahan dan bagaimana Anda dapat menggunakan parameter SkipHeaderValidation untuk menghindari validasi nilai untuk titik akhir yang mentolerir nilai yang diformat secara tidak valid.
$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
'If-Match' = '12345'
}
Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders
Invoke-RestMethod -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation |
Format-List
Invoke-RestMethod: The format of value '12345' is invalid.
headers : @{Host=httpbin.org; If-Match=12345; User-Agent=Mozilla/5.0 (Windows NT 10.0; Microsoft Windows
10.0.19044; en-US) PowerShell/7.2.5; X-Amzn-Trace-Id=Root=1-62f150a6-27754fd4226f31b43a3d2874} httpbin.org adalah layanan yang mengembalikan informasi tentang permintaan web dan respons untuk pemecahan masalah. Variabel $Uri ditetapkan ke /headers titik akhir layanan, yang mengembalikan header permintaan sebagai konten dalam responsnya.
If-Match Header permintaan didefinisikan dalam RFC-7232 bagian 3.1 dan memerlukan nilai untuk header tersebut untuk didefinisikan dengan tanda kutip di sekitarnya. Variabel $InvalidHeaders diberi tabel hash di mana nilai If-Match tidak valid karena didefinisikan sebagai 12345 alih-alih "12345".
Memanggil Invoke-RestMethod dengan header yang tidak valid mengembalikan laporan kesalahan yang melaporkan bahwa nilai yang diformat tidak valid. Permintaan tidak dikirim ke titik akhir.
Memanggil Invoke-RestMethod dengan parameter SkipHeaderValidation mengabaikan kegagalan validasi dan mengirim permintaan ke titik akhir. Karena titik akhir mentolerir nilai header yang tidak sesuai, cmdlet mengembalikan objek respons tanpa kesalahan.
Parameter
-AllowUnencryptedAuthentication
Memungkinkan pengiriman kredensial dan rahasia melalui koneksi yang tidak terenkripsi. Secara default, menyediakan Kredensial atau opsi Autentikasi apa pun dengan Uri yang tidak dimulai https:// akan mengakibatkan kesalahan dan permintaan akan dibatalkan untuk mencegah rahasia yang tidak sengaja berkomunikasi dalam teks biasa melalui koneksi yang tidak terenkripsi. Untuk mengambil alih perilaku ini dengan risiko Anda sendiri, berikan parameter AllowUnencryptedAuthentication .
Peringatan
Menggunakan parameter ini tidak aman dan tidak disarankan. Ini hanya disediakan untuk kompatibilitas dengan sistem warisan yang tidak dapat menyediakan koneksi terenkripsi. Gunakan dengan risiko Anda sendiri.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Authentication
Menentukan jenis autentikasi eksplisit yang akan digunakan untuk permintaan. Default Tidak Ada. Parameter Autentikasi tidak dapat digunakan dengan parameter UseDefaultCredentials .
Opsi Autentikasi yang Tersedia:
None: Ini adalah opsi default ketika Autentikasi tidak disediakan. Tidak ada autentikasi eksplisit yang akan digunakan.Basic: Memerlukan Kredensial. Kredensial akan digunakan untuk mengirim header AutentikasiAuthorization: BasicDasar RFC 7617 dalam formatbase64(user:password).Bearer: Memerlukan parameter Token . Mengirim header RFC 6750Authorization: Bearerdengan token yang disediakan.OAuth: Memerlukan parameter Token . Mengirim header RFC 6750Authorization: Bearerdengan token yang disediakan.
Menyediakan Autentikasi mengambil alih header apa pun Authorization yang disediakan ke Header atau disertakan dalam WebSession.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | WebAuthenticationType |
| Accepted values: | None, Basic, Bearer, OAuth |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Body
Menentukan isi permintaan. Isi adalah konten permintaan yang mengikuti header.
Anda juga dapat menyalurkan nilai isi ke Invoke-RestMethod.
Parameter Isi dapat digunakan untuk menentukan daftar parameter kueri atau menentukan konten respons.
Ketika input adalah permintaan POST dan isinya adalah String, nilai di sebelah kiri tanda sama dengan pertama (=) diatur sebagai kunci dalam data formulir dan teks yang tersisa ditetapkan sebagai nilai . Untuk menentukan beberapa kunci, gunakan objek IDictionary , seperti tabel hash, untuk Isi.
Ketika input adalah permintaan GET dan isinya adalah IDictionary (biasanya, tabel hash), isi ditambahkan ke URI sebagai parameter kueri. Untuk jenis permintaan lain (seperti PATCH), isi diatur sebagai nilai isi permintaan dalam format standar name=value dengan nilai yang dikodekan URL.
Ketika input adalah objek System.Xml.XmlNode dan deklarasi XML menentukan pengodean, pengodean tersebut digunakan untuk data dalam permintaan kecuali ditimpa oleh parameter ContentType .
Saat isi adalah formulir, atau merupakan output dari panggilan lain Invoke-WebRequest , PowerShell mengatur konten permintaan ke bidang formulir.
Parameter Isi juga dapat menerima objek System.Net.Http.MultipartFormDataContent . Ini akan memfasilitasi multipart/form-data permintaan. Ketika objek MultipartFormDataContent disediakan untuk Isi, header terkait konten apa pun yang disediakan ke parameter ContentType, Header, atau WebSession akan ditimpa oleh header MultipartFormDataContent konten objek. Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | Object |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Certificate
Menentukan sertifikat klien yang digunakan untuk permintaan web yang aman. Masukkan variabel yang berisi sertifikat atau perintah atau ekspresi yang mendapatkan sertifikat.
Untuk menemukan sertifikat, gunakan Get-PfxCertificate atau gunakan Get-ChildItem cmdlet di drive Sertifikat (Cert:). Jika sertifikat tidak valid atau tidak memiliki otoritas yang memadai, perintah gagal.
| Type: | X509Certificate |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Menentukan sertifikat kunci publik digital (X509) dari akun pengguna yang memiliki izin untuk mengirim permintaan. Masukkan thumbprint sertifikat sertifikat.
Sertifikat digunakan dalam autentikasi berbasis sertifikat klien. Sertifikat hanya dapat dipetakan ke akun pengguna lokal, bukan akun domain.
Untuk melihat thumbprint sertifikat, gunakan Get-Item perintah atau Get-ChildItem untuk menemukan sertifikat di Cert:\CurrentUser\My.
Catatan
Fitur ini saat ini hanya didukung pada platform OS Windows.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ContentType
Menentukan tipe isi permintaan web.
Jika nilai untuk ContentType berisi format pengodean (sebagai charset), cmdlet menggunakan format tersebut untuk mengodekan isi permintaan web. Jika ContentType tidak menentukan format pengodean, format pengodean default akan digunakan sebagai gantinya. Contoh ContentType dengan format pengodean adalah text/plain; charset=iso-8859-5, yang menentukan alfabet Latin/Sirilik .
Jika parameter ini dihilangkan dan metode permintaan adalah POST, Invoke-RestMethod atur jenis konten ke application/x-www-form-urlencoded. Jika tidak, tipe konten tidak ditentukan dalam panggilan.
ContentType akan ditimpa ketika MultipartFormDataContent objek disediakan untuk Isi.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Credential
Menentukan akun pengguna yang memiliki izin untuk mengirim permintaan. Defaultnya adalah pengguna saat ini.
Ketik nama pengguna, seperti User01 atau Domain01\User01, atau masukkan objek PSCredential yang dihasilkan oleh Get-Credential cmdlet.
Kredensial dapat digunakan sendiri atau bersama dengan opsi parameter Autentikasi tertentu. Ketika digunakan sendiri, server jarak jauh hanya akan memberikan kredensial ke server jarak jauh jika server jarak jauh mengirim permintaan tantangan autentikasi. Saat digunakan dengan opsi Autentikasi , kredensial akan dikirim secara eksplisit.
Kredensial disimpan dalam objek PSCredential dan kata sandi disimpan sebagai SecureString.
Catatan
Untuk informasi selengkapnya tentang perlindungan data SecureString , lihat Seberapa aman SecureString?.
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CustomMethod
Menentukan metode kustom yang digunakan untuk permintaan web. Ini dapat digunakan dengan Metode Permintaan yang diperlukan oleh titik akhir bukanlah opsi yang tersedia pada Metode. Metode dan CustomMethod tidak dapat digunakan bersama-sama.
Contoh:
Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'
Ini membuat TEST permintaan HTTP ke API.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | String |
| Aliases: | CM |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DisableKeepAlive
Menunjukkan bahwa cmdlet mengatur nilai KeepAlive di header HTTP ke False. Secara default, KeepAlive adalah True. KeepAlive membuat koneksi persisten ke server untuk memfasilitasi permintaan berikutnya.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-FollowRelLink
Menunjukkan cmdlet harus mengikuti tautan relasi.
Beberapa REST API mendukung penomoran halaman melalui Relation Links per RFC5988. Alih-alih mengurai header untuk mendapatkan URL untuk halaman berikutnya, Anda dapat meminta cmdlet melakukan ini untuk Anda. Untuk mengatur berapa kali mengikuti tautan relasi, gunakan parameter MaximumFollowRelLink .
Saat menggunakan sakelar ini, cmdlet mengembalikan kumpulan halaman hasil. Setiap halaman hasil mungkin berisi beberapa item hasil.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | SwitchParameter |
| Aliases: | FL |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Form
Mengonversi kamus menjadi multipart/form-data pengiriman. Formulir tidak dapat digunakan dengan Isi.
Jika ContentType akan diabaikan.
Kunci kamus akan digunakan sebagai nama bidang formulir. Secara default, nilai formulir akan dikonversi ke nilai string.
Jika nilainya adalah objek System.IO.FileInfo , maka konten file biner akan dikirimkan.
Nama file akan dikirimkan sebagai filename. MIME akan ditetapkan sebagai application/octet-stream. Get-Item dapat digunakan untuk menyederhanakan penyediaan objek System.IO.FileInfo .
$Form = @{ resume = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }
Jika nilai adalah jenis koleksi, seperti Array atau Daftar, bidang untuk akan dikirimkan beberapa kali. Nilai daftar akan diperlakukan sebagai string secara default. Jika nilainya adalah objek System.IO.FileInfo , maka konten file biner akan dikirimkan. Koleksi berlapis tidak didukung.
$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }
Dalam contoh di atas, tags bidang akan disediakan tiga kali dalam formulir, sekali untuk masing-masing Vacation, Italy, dan 2017. Bidang pictures juga akan dikirimkan sekali untuk setiap file di 2017-Italy folder. Konten biner file dalam folder tersebut akan dikirimkan sebagai nilai.
Fitur ini ditambahkan di PowerShell 6.1.0.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Headers
Menentukan header permintaan web. Masukkan tabel hash atau kamus.
Header terkait konten, seperti Content-Type ditimpa saat MultipartFormDataContent objek disediakan untuk Isi.
| Type: | IDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-InFile
Mendapatkan konten permintaan web dari file.
Masukkan jalur dan nama file. Jika Anda menghilangkan jalur, defaultnya adalah lokasi saat ini.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumFollowRelLink
Menentukan berapa kali untuk mengikuti tautan relasi jika FollowRelLink digunakan. Nilai yang lebih kecil mungkin diperlukan jika REST api dibatasi karena terlalu banyak permintaan. Nilai defaultnya adalah [Int32]::MaxValue. Nilai 0 (nol) mencegah tautan relasi berikut.
| Type: | Int32 |
| Aliases: | ML |
| Position: | Named |
| Default value: | Int32.MaxValue |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRedirection
Menentukan berapa kali PowerShell mengalihkan koneksi ke Pengidentifikasi Sumber Daya Seragam (URI) alternatif sebelum koneksi gagal. Nilai defaultnya adalah 5. Nilai 0 (nol) mencegah semua pengalihan.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRetryCount
Menentukan berapa kali PowerShell mencoba kembali koneksi saat kode kegagalan antara 400 dan 599, inklusif atau 304 diterima. Selain itu , lihat parameter RetryIntervalSec untuk menentukan jumlah detik di antara percobaan ulang.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Method
Menentukan metode yang digunakan untuk permintaan web. Nilai yang dapat diterima untuk parameter ini adalah:
DefaultDeleteGetHeadMergeOptionsPatchPostPutTrace
Parameter CustomMethod dapat digunakan untuk Metode Permintaan yang tidak tercantum di atas.
| Type: | WebRequestMethod |
| Accepted values: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoProxy
Menunjukkan bahwa cmdlet tidak akan menggunakan proksi untuk mencapai tujuan.
Saat Anda perlu melewati proksi yang dikonfigurasi di Internet Explorer, atau proksi yang ditentukan di lingkungan, gunakan sakelar ini.
Parameter ini diperkenalkan di PowerShell 6.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OutFile
Menyimpan isi respons dalam file output yang ditentukan. Masukkan jalur dan nama file. Jika Anda menghilangkan jalur, defaultnya adalah lokasi saat ini. Nama ini diperlakukan sebagai jalur harfiah. Nama yang berisi tanda kurung siku ([]) harus diapit dalam tanda kutip tunggal (').
Secara default, Invoke-RestMethod mengembalikan hasil ke alur.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PassThru
Parameter ini hanya valid ketika parameter OutFile juga digunakan dalam perintah . Tujuannya adalah agar hasilnya ditulis ke file dan ke alur.
Catatan
Saat Anda menggunakan parameter PassThru , output ditulis ke alur tetapi file tidak dibuat. Untuk informasi selengkapnya, lihat Masalah PowerShell #15409.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | No output |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PreserveAuthorizationOnRedirect
Menunjukkan cmdlet harus mempertahankan Authorization header, saat ada, di seluruh pengalihan.
Secara default, cmdlet menghapus Authorization header sebelum mengalihkan. Menentukan parameter ini menonaktifkan logika ini untuk kasus di mana header perlu dikirim ke lokasi pengalihan.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Proxy
Menggunakan server proksi untuk permintaan, daripada menyambungkan langsung ke sumber daya internet. Masukkan Pengidentifikasi Sumber Daya Seragam (URI) server proksi jaringan.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | Uri |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyCredential
Menentukan akun pengguna yang memiliki izin untuk menggunakan server proksi yang ditentukan oleh parameter Proksi . Defaultnya adalah pengguna saat ini.
Ketik nama pengguna, seperti User01 atau Domain01\User01, User@Domain.Com, atau masukkan PSCredential objek, seperti yang dihasilkan oleh Get-Credential cmdlet.
Parameter ini hanya valid ketika parameter Proksi juga digunakan dalam perintah . Anda tidak dapat menggunakan parameter ProxyCredential dan ProxyUseDefaultCredentials dalam perintah yang sama.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyUseDefaultCredentials
Menunjukkan bahwa cmdlet menggunakan kredensial pengguna saat ini untuk mengakses server proksi yang ditentukan oleh parameter Proksi .
Parameter ini hanya valid ketika parameter Proksi juga digunakan dalam perintah . Anda tidak dapat menggunakan parameter ProxyCredential dan ProxyUseDefaultCredentials dalam perintah yang sama.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ResponseHeadersVariable
Membuat variabel yang berisi Kamus Header Respons. Masukkan nama variabel tanpa simbol tanda dolar ($). Kunci kamus berisi nama bidang dan nilai Header Respons yang dikembalikan oleh server web.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | String |
| Aliases: | RHV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Resume
Melakukan upaya terbaik untuk melanjutkan pengunduhan file parsial. Parameter Resume memerlukan parameter OutFile .
Lanjutkan hanya beroperasi pada ukuran file lokal dan file jarak jauh dan tidak melakukan validasi lain bahwa file lokal dan file jarak jauh sama.
Jika ukuran file lokal lebih kecil dari ukuran file jarak jauh, maka cmdlet akan mencoba melanjutkan mengunduh file dan menambahkan byte yang tersisa ke akhir file.
Jika ukuran file lokal sama dengan ukuran file jarak jauh, maka tidak ada tindakan yang diambil dan cmdlet mengasumsikan unduhan sudah selesai.
Jika ukuran file lokal lebih besar dari ukuran file jarak jauh, maka file lokal akan ditimpa dan seluruh file jarak jauh akan sepenuhnya diunduh ulang. Perilaku ini sama dengan menggunakan OutFile tanpa Resume.
Jika server jarak jauh tidak mendukung pengunduhan dilanjutkan, maka file lokal akan ditimpa dan seluruh file jarak jauh akan diunduh ulang sepenuhnya. Perilaku ini sama dengan menggunakan OutFile tanpa Resume.
Jika file lokal tidak ada, maka file lokal akan dibuat dan seluruh file jarak jauh akan diunduh sepenuhnya. Perilaku ini sama dengan menggunakan OutFile tanpa Resume.
Fitur ini ditambahkan di PowerShell 6.1.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-RetryIntervalSec
Menentukan interval antara percobaan ulang untuk koneksi ketika kode kegagalan antara 400 dan 599, inklusif atau 304 diterima. Nilai harus antara 1 dan [int]::MaxValue.
Selain itu , lihat parameter MaximumRetryCount untuk menentukan jumlah percobaan ulang.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SessionVariable
Membuat variabel yang berisi sesi permintaan web. Masukkan nama variabel tanpa simbol tanda dolar ($).
Saat Anda menentukan variabel sesi, Invoke-RestMethod membuat objek sesi permintaan web dan menetapkannya ke variabel dengan nama yang ditentukan dalam sesi PowerShell Anda. Anda dapat menggunakan variabel dalam sesi Anda segera setelah perintah selesai.
Sebelum PowerShell 7.4, sesi permintaan web bukan koneksi persisten. Ini adalah objek yang berisi informasi tentang koneksi dan permintaan, termasuk cookie, kredensial, nilai pengalihan maksimum, dan string agen pengguna. Anda dapat menggunakannya untuk berbagi status dan data di antara permintaan web.
Dimulai di PowerShell 7.4, sesi permintaan web tetap ada selama properti sesi tidak ditimpa dalam permintaan berikutnya. Ketika sudah, cmdlet membuat ulang sesi dengan nilai baru. Sesi persisten mengurangi overhead untuk permintaan berulang, membuatnya jauh lebih cepat.
Untuk menggunakan sesi permintaan web dalam permintaan web berikutnya, tentukan variabel sesi dalam nilai parameter WebSession . PowerShell menggunakan data dalam objek sesi permintaan web saat membuat koneksi baru. Untuk mengambil alih nilai dalam sesi permintaan web, gunakan parameter cmdlet, seperti UserAgent atau Credential. Nilai parameter lebih diutamakan daripada nilai dalam sesi permintaan web.
Anda tidak dapat menggunakan parameter SessionVariable dan WebSession dalam perintah yang sama.
| Type: | String |
| Aliases: | SV |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCertificateCheck
Melewati pemeriksaan validasi sertifikat yang mencakup semua validasi seperti kedaluwarsa, pencabutan, otoritas akar tepercaya, dll.
Peringatan
Menggunakan parameter ini tidak aman dan tidak disarankan. Sakelar ini hanya dimaksudkan untuk digunakan terhadap host yang diketahui menggunakan sertifikat yang ditandatangani sendiri untuk tujuan pengujian. Gunakan dengan risiko Anda sendiri.
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHeaderValidation
Menunjukkan cmdlet harus menambahkan header ke permintaan tanpa validasi.
Sakelar ini harus digunakan untuk situs yang memerlukan nilai header yang tidak sesuai dengan standar. Menentukan sakelar ini menonaktifkan validasi untuk memungkinkan nilai diteruskan tidak dicentang. Ketika ditentukan, semua header ditambahkan tanpa validasi.
Ini akan menonaktifkan validasi untuk nilai yang diteruskan ke parameter ContentType, Headers, dan UserAgent .
Fitur ini ditambahkan di PowerShell 6.0.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipHttpErrorCheck
Parameter ini menyebabkan cmdlet mengabaikan status kesalahan HTTP dan terus memproses respons. Respons kesalahan ditulis ke alur seolah-olah berhasil.
Parameter ini diperkenalkan di PowerShell 7.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SslProtocol
Mengatur protokol SSL/TLS yang diizinkan untuk permintaan web. Secara default semua, protokol SSL/TLS yang didukung oleh sistem diizinkan. SslProtocol memungkinkan pembatasan pada protokol tertentu untuk tujuan kepatuhan.
Nilai-nilai ini didefinisikan sebagai enumerasi berbasis bendera. Anda dapat menggabungkan beberapa nilai bersama-sama untuk mengatur beberapa bendera menggunakan parameter ini. Nilai dapat diteruskan ke parameter SslProtocol sebagai array nilai atau sebagai string yang dipisahkan koma dari nilai tersebut. Cmdlet akan menggabungkan nilai menggunakan operasi biner-OR. Meneruskan nilai sebagai array adalah opsi paling sederhana dan juga memungkinkan Anda menggunakan penyelesaian tab pada nilai. Anda mungkin tidak dapat menyediakan beberapa nilai di semua platform.
Catatan
Pada platform non-Windows mungkin tidak dimungkinkan untuk menyediakan Tls atau Tls12 sebagai opsi. Dukungan untuk Tls13 tidak tersedia di semua sistem operasi dan perlu diverifikasi berdasarkan sistem operasi.
Fitur ini ditambahkan di PowerShell 6.0.0 dan dukungan untuk Tls13 ditambahkan di PowerShell 7.1.
| Type: | WebSslProtocol |
| Accepted values: | Default, Tls, Tls11, Tls12, Tls13 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-StatusCodeVariable
Membuat variabel yang berisi hasil kode status HTTP dari permintaan. Masukkan nama variabel tanpa simbol tanda dolar ($).
Parameter dapat mengidentifikasi pesan keberhasilan atau pesan kegagalan saat digunakan dengan parameter SkipHttpErrorCheck .
Masukkan nama variabel parameter sebagai string seperti -StatusCodeVariable "scv".
Parameter ini diperkenalkan di PowerShell 7.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TimeoutSec
Menentukan berapa lama permintaan dapat tertunda sebelum waktu habis. Masukkan nilai dalam detik. Nilai default, 0, menentukan batas waktu yang tidak terbatas.
Kueri Sistem Nama Domain (DNS) bisa memakan waktu hingga 15 detik untuk kembali atau kehabisan waktu. Jika permintaan Anda berisi nama host yang memerlukan resolusi, dan Anda mengatur TimeoutSec ke nilai yang lebih besar dari nol, tetapi kurang dari 15 detik, dibutuhkan waktu 15 detik atau lebih sebelum WebException dilemparkan, dan waktu permintaan Anda habis.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Token
Token OAuth atau Pembawa untuk disertakan dalam permintaan. Token diperlukan oleh opsi Autentikasi tertentu. Ini tidak dapat digunakan secara independen.
Token mengambil yang SecureString berisi token. Untuk menyediakan token, gunakan hal berikut secara manual:
Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)
Parameter ini diperkenalkan di PowerShell 6.0.
| Type: | SecureString |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-TransferEncoding
Menentukan nilai untuk header respons HTTP pengodean transfer. Nilai yang dapat diterima untuk parameter ini adalah:
- Dipotong
- Kompres
- Mengempis
- GZip
- Identitas
| Type: | String |
| Accepted values: | chunked, compress, deflate, gzip, identity |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Uri
Menentukan Pengidentifikasi Sumber Daya Seragam (URI) sumber daya internet tempat permintaan web dikirim. Parameter ini mendukung nilai HTTP, HTTPS, FTP, dan FILE.
Parameter ini diperlukan. Nama parameter (Uri) bersifat opsional.
| Type: | Uri |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseBasicParsing
Parameter ini tidak digunakan lagi. Dimulai dengan PowerShell 6.0.0, semua permintaan Web hanya menggunakan penguraian dasar. Parameter ini disertakan hanya untuk kompatibilitas mundur dan penggunaannya tidak akan berpengaruh pada pengoperasian cmdlet.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseDefaultCredentials
Menunjukkan bahwa cmdlet menggunakan kredensial pengguna saat ini untuk mengirim permintaan web. Ini tidak dapat digunakan dengan Autentikasi atau Kredensial dan mungkin tidak didukung di semua platform.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UserAgent
Menentukan string agen pengguna untuk permintaan web.
Agen pengguna default mirip Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 dengan sedikit variasi untuk setiap sistem operasi dan platform.
Untuk menguji situs web dengan string agen pengguna standar yang digunakan oleh sebagian besar browser internet, gunakan properti kelas PSUserAgent , seperti Chrome, FireFox, InternetExplorer, Opera, dan Safari.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WebSession
Menentukan sesi permintaan web. Masukkan nama variabel, termasuk tanda dolar ($).
Untuk mengambil alih nilai dalam sesi permintaan web, gunakan parameter cmdlet, seperti UserAgent atau Credential. Nilai parameter lebih diutamakan daripada nilai dalam sesi permintaan web. Header terkait konten, seperti Content-Type, juga akan ditimpa ketika objek MultipartFormDataContent disediakan untuk Isi.
Tidak seperti sesi jarak jauh, sesi permintaan web bukan koneksi persisten. Ini adalah objek yang berisi informasi tentang koneksi dan permintaan, termasuk cookie, kredensial, nilai pengalihan maksimum, dan string agen pengguna. Anda dapat menggunakannya untuk berbagi status dan data di antara permintaan web.
Untuk membuat sesi permintaan web, masukkan nama variabel, tanpa tanda dolar, dalam nilai parameter SessionVariable dari perintah Invoke-RestMethod . Invoke-RestMethod membuat sesi dan menyimpannya dalam variabel. Dalam perintah berikutnya, gunakan variabel sebagai nilai parameter WebSession .
Anda tidak dapat menggunakan parameter SessionVariable dan WebSession dalam perintah yang sama.
| Type: | WebRequestSession |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Input
Anda dapat menyalurkan isi permintaan web ke cmdlet ini.
Output
Saat permintaan mengembalikan bilangan bulat, cmdlet ini mengembalikan bilangan bulat tersebut.
Saat permintaan mengembalikan string, cmdlet ini mengembalikan string tersebut.
Saat permintaan mengembalikan XML yang valid, cmdlet ini mengembalikannya sebagai XmlDocument.
PSObject
Saat permintaan mengembalikan string JSON, cmdlet ini mengembalikan PSObject yang mewakili data.
Catatan
PowerShell menyertakan alias berikut untuk Invoke-RestMethod:
- Semua platform:
irm
Beberapa fitur mungkin tidak tersedia di semua platform.
Karena perubahan dalam .NET Core 3.1, PowerShell 7.0 dan yang lebih tinggi menggunakan properti HttpClient.DefaultProxy untuk menentukan konfigurasi proksi.
Nilai properti ini adalah aturan yang berbeda tergantung pada platform Anda:
- Untuk Windows: Membaca konfigurasi proksi dari variabel lingkungan atau, jika tidak ditentukan, dari pengaturan proksi pengguna.
- Untuk macOS: Membaca konfigurasi proksi dari variabel lingkungan atau, jika tidak ditentukan, dari pengaturan proksi sistem.
- Untuk Linux: Membaca konfigurasi proksi dari variabel lingkungan atau, jika tidak ditentukan, properti ini menginisialisasi instans yang tidak dikonfigurasi yang melewati semua alamat.
Variabel lingkungan yang digunakan untuk DefaultProxy inisialisasi pada platform berbasis Windows dan Unix adalah:
HTTP_PROXY: nama host atau alamat IP server proksi yang digunakan pada permintaan HTTP.HTTPS_PROXY: nama host atau alamat IP server proksi yang digunakan pada permintaan HTTPS.ALL_PROXY: nama host atau alamat IP server proksi yang digunakan pada permintaan HTTP dan HTTPS jikaHTTP_PROXYatauHTTPS_PROXYtidak ditentukan.NO_PROXY: daftar nama host yang dipisahkan koma yang harus dikecualikan dari proksi.
Link Terkait
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk