Invoke-RestMethod
Mengirim permintaan HTTP atau HTTPS ke layanan web RESTful.
Sintaks
Invoke-RestMethod
[-Method <WebRequestMethod>]
[-UseBasicParsing]
[-Uri] <Uri>
[-WebSession <WebRequestSession>]
[-SessionVariable <String>]
[-Credential <PSCredential>]
[-UseDefaultCredentials]
[-CertificateThumbprint <String>]
[-Certificate <X509Certificate>]
[-UserAgent <String>]
[-DisableKeepAlive]
[-TimeoutSec <Int32>]
[-Headers <IDictionary>]
[-MaximumRedirection <Int32>]
[-Proxy <Uri>]
[-ProxyCredential <PSCredential>]
[-ProxyUseDefaultCredentials]
[-Body <Object>]
[-ContentType <String>]
[-TransferEncoding <String>]
[-InFile <String>]
[-OutFile <String>]
[-PassThru]
[<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.
Catatan
Secara default, kode skrip di halaman web dapat dijalankan ketika halaman sedang diurai untuk mengisi ParsedHtml
properti. Gunakan tombol UseBasicParsing untuk menekan ini.
Contoh
Contoh 1: Dapatkan umpan PowerShell RSS
Invoke-RestMethod -Uri https://devblogs.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 +0000
Perintah 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.
Contoh 2
Dalam contoh berikut, pengguna berjalan Invoke-RestMethod
untuk melakukan permintaan POST di situs web intranet di organisasi pengguna.
$Cred = Get-Credential
# Next, allow the use of self-signed SSL certificates.
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }
# Create variables to store the values consumed by the Invoke-RestMethod command.
# The search variable contents are later embedded in the body variable.
$Server = 'server.contoso.com'
$Url = "https://${server}:8089/services/search/jobs/export"
$Search = "search index=_internal | reverse | table index,host,source,sourcetype,_raw"
# The cmdlet handles URL encoding. The body variable describes the search criteria, specifies CSV as
# the output mode, and specifies a time period for returned data that starts two days ago and ends
# one day ago. The body variable specifies values for parameters that apply to the particular REST
# API with which Invoke-RestMethod is communicating.
$Body = @{
search = $Search
output_mode = "csv"
earliest_time = "-2d@d"
latest_time = "-1d@d"
}
# Now, run the Invoke-RestMethod command with all variables in place, specifying a path and file
# name for the resulting CSV output file.
Invoke-RestMethod -Method Post -Uri $url -Credential $Cred -Body $body -OutFile output.csv
{"preview":true,"offset":0,"result":{"sourcetype":"contoso1","count":"9624"}}
{"preview":true,"offset":1,"result":{"sourcetype":"contoso2","count":"152"}}
{"preview":true,"offset":2,"result":{"sourcetype":"contoso3","count":"88494"}}
{"preview":true,"offset":3,"result":{"sourcetype":"contoso4","count":"15277"}}
Contoh 3: Meneruskan beberapa header
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 $body
API sering memerlukan header yang diteruskan untuk autentikasi, validasi, dll.
Contoh 3: Mengirimkan data formulir
Ketika isi adalah formulir, atau merupakan output dari panggilan lain Invoke-WebRequest
, PowerShell mengatur konten permintaan ke bidang formulir.
Contohnya:
$R = Invoke-WebRequest https://website.com/login.aspx
$R.Forms[0].Name = "MyName"
$R.Forms[0].Password = "MyPassword"
Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]
Contoh 4: 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
30
Parameter
-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 GET, dan isinya adalah IDictionary (biasanya, tabel hash), isi ditambahkan ke URI sebagai parameter kueri. Untuk jenis permintaan lain (seperti POST), isi diatur sebagai nilai isi permintaan dalam format nama=nilai standar.
Peringatan
Output verbose dari isi POST akan berakhir dengan with -1-byte payload
, meskipun ukuran isi diketahui dan dikirim di Content-Length
header HTTP.
Jenis: | Object |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | True |
Terima karakter wildcard: | 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.
Jenis: | X509Certificate |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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
.
Jenis: | String |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-ContentType
Menentukan tipe isi permintaan web.
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.
Jenis: | String |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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 disimpan dalam objek PSCredential dan kata sandi disimpan sebagai SecureString.
Catatan
Untuk informasi selengkapnya tentang perlindungan data SecureString , lihat Seberapa aman SecureString?.
Jenis: | PSCredential |
Position: | Named |
Nilai default: | Current user |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-DisableKeepAlive
Mengatur nilai KeepAlive di header HTTP ke False. Secara default, KeepAlive adalah True. KeepAlive membuat koneksi persisten ke server untuk memfasilitasi permintaan berikutnya.
Jenis: | SwitchParameter |
Position: | Named |
Nilai default: | KeepAlive |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-Headers
Menentukan header permintaan web. Masukkan tabel hash atau kamus.
Untuk mengatur header UserAgent, gunakan parameter UserAgent . Anda tidak dapat menggunakan parameter ini untuk menentukan header UserAgent atau cookie.
Jenis: | IDictionary |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-InFile
Mendapatkan konten permintaan web dari file.
Masukkan jalur dan nama file. Jika Anda menghilangkan jalur, defaultnya adalah lokasi saat ini.
Jenis: | String |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-MaximumRedirection
Menentukan berapa kali Windows PowerShell mengalihkan koneksi ke Pengidentifikasi Sumber Daya Seragam (URI) alternatif sebelum koneksi gagal. Nilai defaultnya adalah 5. Nilai 0 (nol) mencegah semua pengalihan.
Jenis: | Int32 |
Position: | Named |
Nilai default: | 5 |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-Method
Menentukan metode yang digunakan untuk permintaan web. Nilai yang dapat diterima untuk parameter ini adalah:
Default
Delete
Get
Head
Merge
Options
Patch
Post
Put
Trace
Jenis: | WebRequestMethod |
Nilai yang diterima: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
Position: | Named |
Nilai default: | Default |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-OutFile
Menyimpan isi respons dalam file output yang ditentukan. Masukkan jalur dan nama file. Jika Anda menghilangkan jalur, defaultnya adalah lokasi saat ini.
Secara default, Invoke-RestMethod
mengembalikan hasil ke alur.
Jenis: | String |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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 kosong. Untuk informasi selengkapnya, lihat Masalah PowerShell #15409.
Jenis: | SwitchParameter |
Position: | Named |
Nilai default: | No output |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-Proxy
Menggunakan server proksi untuk permintaan, daripada menyambungkan langsung ke sumber daya Internet. Masukkan URI server proksi jaringan.
Jenis: | Uri |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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", atau masukkan objek PSCredential , 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.
Jenis: | PSCredential |
Position: | Named |
Nilai default: | Current user |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-ProxyUseDefaultCredentials
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.
Jenis: | SwitchParameter |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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.
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 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.
Jenis: | String |
Alias: | SV |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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.
Jenis: | Int32 |
Position: | Named |
Nilai default: | 0 |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-TransferEncoding
Menentukan nilai untuk header respons HTTP pengodean transfer. Nilai yang dapat diterima untuk parameter ini adalah:
Chunked
Compress
Deflate
GZip
Identity
Jenis: | String |
Nilai yang diterima: | chunked, compress, deflate, gzip, identity |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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.
Jenis: | Uri |
Position: | 0 |
Nilai default: | None |
Diperlukan: | True |
Terima input alur: | False |
Terima karakter wildcard: | False |
-UseBasicParsing
Menunjukkan bahwa cmdlet menggunakan penguraian dasar. Cmdlet mengembalikan HTML mentah dalam objek String .
Jenis: | SwitchParameter |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-UseDefaultCredentials
Menggunakan kredensial pengguna saat ini untuk mengirim permintaan web.
Jenis: | SwitchParameter |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | False |
-UserAgent
Menentukan string agen pengguna untuk permintaan web.
Agen pengguna default mirip dengan "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.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, Internet Explorer, Opera, dan Safari.
Jenis: | String |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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.
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) di nilai parameter SessionVariable dari Invoke-RestMethod
perintah. 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.
Jenis: | WebRequestSession |
Position: | Named |
Nilai default: | None |
Diperlukan: | False |
Terima input alur: | False |
Terima karakter wildcard: | 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
Windows PowerShell menyertakan alias berikut untuk Invoke-RestMethod
:
irm