Invoke-RestMethod
HTTP- vagy HTTPS-kérést küld egy RESTful webszolgáltatásnak.
Syntax
Default (Alapértelmezett)
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>]
Description
A Invoke-RestMethod parancsmag HTTP- és HTTPS-kéréseket küld az Representational State Transfer (REST) webszolgáltatásoknak, amelyek gazdagon strukturált adatokat ad vissza.
A Windows PowerShell az adattípusnak megfelelően formázja a választ. RSS- vagy ATOM-hírcsatornák esetén a Windows PowerShell visszaadja az Elem vagy bejegyzés XML-csomópontjait. JavaScript Object Notation (JSON) vagy XML esetén a Windows PowerShell objektummá alakítja (vagy deszerializálja) a tartalmat.
Ezt a parancsmagot a Windows PowerShell 3.0-ban vezettük be.
Megjegyzés:
Alapértelmezés szerint a weblap szkriptkódja futtatható, ha a lap elemzése folyamatban van a ParsedHtml tulajdonság feltöltéséhez.
Ezt a -UseBasicParsing kapcsolóval tilthatja le.
Paraméterek
-Body
A kérelem törzsét adja meg.
A törzs a fejléceket követő kérés tartalma.
A törzsértéket a Invoke-RestMethodrészére is át lehet irányítani.
A -Body paraméterrel megadhatja a lekérdezési paraméterek listáját, vagy megadhatja a válasz tartalmát.
Ha a bemenet egy GET kérés, és a törzs egy IDictionary (általában egy kivonattáblázat), akkor a törzset lekérdezési paraméterekként hozzáadják az URI-hoz. Más kéréstípusok (például POST) esetén a törzs a kérelem törzsének értékeként van beállítva a standard name=value formátumban.
Figyelmeztetési: A POST-törzs részletes kimenete with -1-byte payloadvégződik, annak ellenére, hogy a törzs mérete is ismert, és a Content-Length HTTP-fejlécben lesz elküldve.
Ha a törzs egy űrlap, vagy egy másik Invoke-WebRequest hívás kimenete, a Windows PowerShell a kérelem tartalmát az űrlapmezőkre állítja.
Például:
$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]
Paramétertulajdonságok
| Típus: | Object |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | True |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Certificate
Megadja a biztonságos webkérelemhez használt ügyféltanúsítványt. Adjon meg egy változót, amely tartalmaz egy tanúsítványt, vagy egy parancsot vagy kifejezést, amely lekéri a tanúsítványt.
Tanúsítvány kereséséhez használja a Get-PfxCertificate, vagy használja a Get-ChildItem parancsmagot a Tanúsítvány (Cert:) meghajtón.
Ha a tanúsítvány érvénytelen, vagy nem rendelkezik megfelelő jogosultságtal, a parancs meghiúsul.
Paramétertulajdonságok
| Típus: | X509Certificate |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-CertificateThumbprint
Egy olyan felhasználói fiók digitális nyilvános kulcsú tanúsítványát (X509) adja meg, amely jogosult a kérés elküldésére. Adja meg a tanúsítvány ujjlenyomatát.
A tanúsítványok az ügyféltanúsítvány-alapú hitelesítésben használatosak. Ezek csak helyi felhasználói fiókokra képezhetők le; nem működnek tartományi fiókokkal.
Tanúsítvány ujjlenyomatának lekéréséhez használja a Windows PowerShell (Get-Item) meghajtójának Get-ChildItem vagy Cert: parancsát.
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-ContentType
Megadja a webes kérelem tartalomtípusát.
Ha ez a paraméter nincs megadva, és a kérelem metódusa POST, Invoke-RestMethod a tartalomtípust "application/x-www-form-urlencoded" értékre állítja.
Ellenkező esetben a tartalomtípus nincs megadva a hívásban.
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Credential
Olyan felhasználói fiókot ad meg, amely rendelkezik a kérés elküldéséhez szükséges engedéllyel. Az alapértelmezett az aktuális felhasználó.
Írjon be egy felhasználónevet (például "User01" vagy "Domain01\User01"), vagy írjon be egy PSCredential objektumot, például a Get-Credential parancsmag által létrehozott objektumot.
Paramétertulajdonságok
| Típus: | PSCredential |
| Alapértelmezett érték: | Current user |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-DisableKeepAlive
A HTTP-fejlécben lévő KeepAlive értékét False (Hamis) értékre állítja. Alapértelmezés szerint KeepAlive igaz. KeepAlive állandó kapcsolatot létesít a kiszolgálóval a további kérések megkönnyítése érdekében.
Paramétertulajdonságok
| Típus: | SwitchParameter |
| Alapértelmezett érték: | KeepAlive |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Headers
Meghatározza a webes kérelem fejléceit. Írjon be egy kivonattáblát vagy szótárt.
A UserAgent fejlécek beállításához használja a -UserAgent paramétert.
Ez a paraméter nem használható UserAgent vagy cookie fejlécek megadására.
Paramétertulajdonságok
| Típus: | IDictionary |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-InFile
Lekéri a webes kérelem tartalmát egy fájlból.
Adjon meg egy elérési utat és egy fájlnevet. Ha kihagyja az elérési utat, az alapértelmezett hely az aktuális hely.
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-MaximumRedirection
Meghatározza, hogy a Windows PowerShell hányszor irányítja át a kapcsolatot egy másodlagos egységes erőforrás-azonosítóhoz (URI), mielőtt a kapcsolat meghiúsul. Az alapértelmezett érték 5. A 0 (nulla) érték megakadályozza az összes átirányítást.
Paramétertulajdonságok
| Típus: | Int32 |
| Alapértelmezett érték: | 5 |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Method
A webes kérelemhez használt metódust adja meg. A paraméter elfogadható értékei a következők:
- Alapértelmezett
- Törlés
- Megszerez
- Fej
- Egyesítés
- Beállítások
- Javítás
- Posta
- Put
- Nyom
Paramétertulajdonságok
| Típus: | WebRequestMethod |
| Alapértelmezett érték: | Default |
| Elfogadott értékek: | Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-OutFile
Menti a válasz törzsét a megadott kimeneti fájlban. Adjon meg egy elérési utat és egy fájlnevet. Ha kihagyja az elérési utat, az alapértelmezett hely az aktuális hely.
Alapértelmezés szerint Invoke-RestMethod visszaadja az eredményeket a feldolgozási sornak.
Az eredmények fájlba és folyamatba való küldéséhez használja a -Passthru paramétert.
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-PassThru
Az eredményeket amellett adja vissza, hogy egy fájlba írja őket.
Ez a paraméter csak akkor érvényes, ha a -OutFile paramétert is használja a parancsban.
Paramétertulajdonságok
| Típus: | SwitchParameter |
| Alapértelmezett érték: | No output |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Proxy
A kéréshez proxykiszolgálót használ ahelyett, hogy közvetlenül az internetes erőforráshoz csatlakozik. Adja meg egy hálózati proxykiszolgáló URI-ját.
Paramétertulajdonságok
| Típus: | Uri |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-ProxyCredential
Olyan felhasználói fiókot ad meg, amely jogosult a -Proxy paraméter által megadott proxykiszolgáló használatára.
Az alapértelmezett az aktuális felhasználó.
Írjon be egy felhasználónevet (például "User01" vagy "Domain01\User01"), vagy írjon be egy PSCredential objektumot, például a Get-Credential parancsmag által létrehozott objektumot.
Ez a paraméter csak akkor érvényes, ha a -Proxy paramétert is használja a parancsban.
Ugyanabban a parancsban nem használhatja a -ProxyCredential és -ProxyUseDefaultCredentials paramétereket.
Paramétertulajdonságok
| Típus: | PSCredential |
| Alapértelmezett érték: | Current user |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-ProxyUseDefaultCredentials
Az aktuális felhasználó hitelesítő adataival fér hozzá a -Proxy paraméter által megadott proxykiszolgálóhoz.
Ez a paraméter csak akkor érvényes, ha a -Proxy paramétert is használja a parancsban.
Ugyanabban a parancsban nem használhatja a -ProxyCredential és -ProxyUseDefaultCredentials paramétereket.
Paramétertulajdonságok
| Típus: | SwitchParameter |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-SessionVariable
Létrehoz egy webkérelem-munkamenetet, és menti a megadott változó értékére.
Adjon meg egy változónevet a dollárjel ($) szimbólum nélkül.
Amikor megad egy munkamenet-változót, Invoke-RestMethod létrehoz egy webkérelem munkamenet-objektumot, és hozzárendeli azt egy változóhoz, amelynek a megadott neve szerepel a Windows PowerShell-munkamenetben.
A változót a parancs befejeződése után használhatja a munkamenetben.
A távoli munkamenetekkel ellentétben a webkérelmek munkamenete nem állandó kapcsolat. Ez egy objektum, amely információkat tartalmaz a kapcsolatról és a kérésről, beleértve a cookie-kat, a hitelesítő adatokat, a maximális átirányítási értéket és a felhasználói ügynök sztringet. Ezzel megoszthatja az állapotot és az adatokat a webes kérések között.
A webkérelem-munkamenet későbbi webes kérelmekben való használatához adja meg a munkamenet változóját a -WebSession paraméter értékében.
A Windows PowerShell a webkérelem munkamenet-objektumában lévő adatokat használja az új kapcsolat létrehozásakor.
Ha felül szeretne bírálni egy értéket a webes kérelem munkamenetében, használjon egy parancsmagparamétert, például -UserAgent vagy -Credential.
A paraméterértékek elsőbbséget élveznek a webes kérelem munkamenetében lévő értékekkel szemben.
Ugyanabban a parancsban nem használhatja a -SessionVariable és -WebSession paramétereket.
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
| Aliasok: | SV |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-TimeoutSec
Megadja, hogy mennyi ideig lehet függőben a kérelem, mielőtt túllépi az időkorlátot. Adjon meg egy értéket másodpercek alatt. Az alapértelmezett érték, 0, meghatározatlan időtartamot ad meg.
A DNS-lekérdezések visszaérése vagy időtúllépése akár 15 másodpercet is igénybe vehet. Ha a kérés tartalmaz egy feloldást igénylő gazdagépnevet, és a TimeoutSec értékét nullánál nagyobbra, de 15 másodpercnél rövidebbre állítja be, az 15 másodpercet vagy többet is igénybe vehet a WebException kiváltása előtt, és a kérés túllépi az időkorlátot.
Paramétertulajdonságok
| Típus: | Int32 |
| Alapértelmezett érték: | 0 |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-TransferEncoding
Megadja az átvitelkódoló HTTP-válaszfejléc értékét. A paraméter elfogadható értékei a következők:
- Felaprított
- Tömörít
- Leereszt
- GZip
- Személyazonosság
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Elfogadott értékek: | chunked, compress, deflate, gzip, identity |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-Uri
Annak az internetes erőforrásnak az egységes erőforrás-azonosítóját (URI) adja meg, amelyre a webkérelmet küldi. Ez a paraméter támogatja a HTTP, HTTPS, FTP és FILE értékeket.
Ez a paraméter kötelező.
A paraméter neve (-Uri) megadása nem kötelező.
Paramétertulajdonságok
| Típus: | Uri |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | 0 |
| Kötelező: | True |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-UseBasicParsing
Azt jelzi, hogy a parancsmag alapszintű elemzést használ. A parancsmag egy sztring objektum nyers HTML-kódját adja vissza.
Paramétertulajdonságok
| Típus: | SwitchParameter |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-UseDefaultCredentials
Az aktuális felhasználó hitelesítő adataival küldi el a webes kérelmet.
Paramétertulajdonságok
| Típus: | SwitchParameter |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-UserAgent
Meghatároz egy user agent karakterláncot a webes kéréshez.
Az alapértelmezett felhasználói ügynök a "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" kisebb változatokkal az egyes operációs rendszerekhez és platformokhoz.
Ha a legtöbb internetböngésző által használt szabványos felhasználóiügynök-sztringgel szeretne tesztelni egy webhelyet, használja a PSUserAgent osztály( például Chrome, FireFox, Internet Explorer, Opera és Safari) tulajdonságait.
Az alábbi parancs például az internethez készült felhasználói ügynök sztringet használja
Invoke-WebRequest -Uri https://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)
Paramétertulajdonságok
| Típus: | String |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
-WebSession
Webkérelem-munkamenetet határoz meg.
Adja meg a változó nevét, beleértve a dollárjelet ($).
Ha felül szeretne bírálni egy értéket a webes kérelem munkamenetében, használjon egy parancsmagparamétert, például -UserAgent vagy -Credential.
A paraméterértékek elsőbbséget élveznek a webes kérelem munkamenetében lévő értékekkel szemben.
A távoli munkamenetekkel ellentétben a webkérelmek munkamenete nem állandó kapcsolat. Ez egy objektum, amely információkat tartalmaz a kapcsolatról és a kérésről, beleértve a cookie-kat, a hitelesítő adatokat, a maximális átirányítási értéket és a felhasználói ügynök sztringet. Ezzel megoszthatja az állapotot és az adatokat a webes kérések között.
Webkérelem-munkamenet létrehozásához írjon be egy változónevet (dollárjel nélkül) egy -SessionVariable parancs Invoke-RestMethod paraméterének értékébe.
Invoke-RestMethod létrehozza a munkamenetet, és megmenti a változóban.
A következő parancsokban használja a változót a -WebSession paraméter értékeként.
Ugyanabban a parancsban nem használhatja a -SessionVariable és -WebSession paramétereket.
Paramétertulajdonságok
| Típus: | WebRequestSession |
| Alapértelmezett érték: | None |
| Támogatja a helyettesítő karaktereket: | False |
| DontShow: | False |
Paraméterkészletek
(All)
| Position: | Named |
| Kötelező: | False |
| Folyamatból származó érték: | False |
| Folyamatból származó érték tulajdonságnév alapján: | False |
| Fennmaradó argumentumokból származó érték: | False |
CommonParameters
Ez a parancsmag a következő gyakori paramétereket támogatja: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction és -WarningVariable. További információért lásd about_CommonParameters.
Bevitelek
Object
A webes kérés törzsét a Invoke-RestMethod.
Kimenetek
System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String
A parancsmag kimenete a lekért tartalom formátumától függ.
PSObject
Ha a kérelem JSON-sztringeket ad vissza, Invoke-RestMethod a sztringeket képviselő PSObject értéket adja vissza.