Invoke-RestMethod

HTTP- vagy HTTPS-kérést küld egy RESTful-webszolgáltatásnak.

Syntax

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>]

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 adnak vissza.

A PowerShell az adattípusnak megfelelően formázja a választ. RSS- vagy ATOM-hírcsatornák esetén a PowerShell az Elem vagy a Bejegyzés XML-csomópontot adja vissza. JavaScript Object Notation (JSON) vagy XML esetén a PowerShell objektummá alakítja vagy deszerializálja a tartalmat [PSCustomObject] .

Megjegyzés

Amikor a REST-végpont több objektumot ad vissza, az objektumok tömbként lesznek fogadva. Ha a kimenetet Invoke-RestMethod egy másik parancsba küldi, az egyetlen [Object[]] objektumként lesz elküldve. A tömb tartalma nem lesz számba adva a folyamat következő parancsához.

Ezt a parancsmagot a Windows PowerShell 3.0-s kiadásban vezettük be.

A PowerShell 7.0-tól Invoke-RestMethod kezdve támogatja a környezeti változók által meghatározott proxykonfigurációt. Lásd a cikk Jegyzetek szakaszát.

Példák

1. példa: A PowerShell RSS-hírcsatorna lekérése

Ez a példa a parancsmagot használja a Invoke-RestMethod PowerShell blog RSS-hírcsatornájának információinak lekéréséhez. A parancsmag a Format-Table parancsmaggal jeleníti meg az egyes blogok Cím és pubDate tulajdonságának értékeit egy táblázatban.

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 +0000

2. példa: POST-kérelem futtatása

Ebben a példában egy felhasználó futtat Invoke-RestMethod egy POST-kérést a felhasználó szervezetének intranetes webhelyén.

$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.csv

A rendszer kéri, majd tárolja $Cred a hitelesítő adatokat, és a hozzáférést biztosító URL-címet a rendszer a következőben $Urlhatározza meg: .

A $Body változó leírja a keresési feltételeket, megadja a CSV-t kimeneti módként, és megadja a két nappal ezelőtt kezdődő és egy nappal ezelőtt véget ért visszaadott adatok időtartamát. A törzsváltozó olyan paraméterek értékeit határozza meg, amelyek az adott REST API-val Invoke-RestMethod kommunikálnak.

A Invoke-RestMethod parancs az összes változóval együtt fut, és megadja az eredményül kapott CSV-kimeneti fájl elérési útját és fájlnevét.

3. példa: Relációs hivatkozások követése

Egyes REST API-k támogatják a relációs hivatkozásokon keresztüli lapozást RFC5988-onként. Ahelyett, hogy elemezte volna a fejlécet a következő oldal URL-címének lekéréséhez, a parancsmag ezt megteheti Ön helyett. Ez a példa a PowerShell GitHub-adattár első két lapját adja vissza.

$url = 'https://api.github.com/repos/powershell/powershell/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

4. példa: Egyszerűsített többrészes/űrlap-adatküldés

Egyes API-k fájlokat multipart/form-data és vegyes tartalmakat tölthetnek fel. Ez a példa bemutatja, hogyan frissítheti egy felhasználó profilját.

$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 $Form

A profilűrlaphoz a következő mezők szükségesek: firstName, lastName, email, avatar, birthdayés hobbies. Az API arra számít, hogy a felhasználói profil képe megjelenik a avatar mezőben. Az API több hobbies , ugyanabban az űrlapon elküldendő bejegyzést is elfogad.

A Kivonattábla létrehozásakor a $Form kulcsnevek űrlapmezőnevekként lesznek használva. Alapértelmezés szerint a kivonattábla értékei sztringekké lesznek konvertálva. Ha egy System.IO.FileInfo érték jelenik meg, a fájl tartalma el lesz küldve. Ha egy gyűjtemény, például tömbök vagy listák vannak jelen, az űrlapmező többször lesz elküldve.

A kulcs használatával Get-Itemavatar az FileInfo objektum értékként lesz beállítva. Az eredmény az, hogy a rendszer a képadatokat jdoe.png küldi el.

Ha megad egy listát a hobbies kulcsnak, a hobbies mező minden listaelemhez egyszer jelen lesz a beküldésekben.

5. példa: Több fejléc átadása

Az API-k gyakran átment fejléceket igényelnek a hitelesítéshez vagy az ellenőrzéshez. Ez a példa bemutatja, hogyan továbbíthat több fejlécet egy hash-table REST API-nak.

$headers = @{
    'userId' = 'UserIDValue'
    'token' = 'TokenValue'
}
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body

6. példa: A folyamat visszaadott elemeinek számbavétele

A GitHub több objektumot ad vissza egy tömbhöz. Ha a kimenetet egy másik parancsba küldi, az egyetlen [Object[]]objektumként lesz elküldve.

Ha az objektumokat a folyamatba szeretné enumerálni, az eredményeket zárójelek közé kell tenni, vagy be kell csomagolnia Write-Output a parancsmagot. Az alábbi példa a GitHub által visszaadott objektumok számát számlálja meg. Ezután megszámolja a folyamatba enumerált objektumok számát.

$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

7. példa: Fejlécérvényesítés kihagyása

Alapértelmezés szerint a Invoke-RestMethod parancsmag ellenőrzi a szabványos értékformátumú, jól ismert fejlécek értékeit. Az alábbi példa bemutatja, hogy ez az ellenőrzés hogyan okozhat hibát, és hogyan használható a SkipHeaderValidation paraméter az érvénytelenül formázott értékeket toleráló végpontok értékeinek ellenőrzésére.

$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 egy szolgáltatás, amely a webes kérésekről és a hibaelhárításra adott válaszokról ad vissza információkat. A $Uri változó a /headers szolgáltatás végpontjára van rendelve, amely a kérés fejléceit adja vissza a válasz tartalmaként.

A If-Match kérelem fejléce az RFC-7232 3.1 szakaszában van definiálva, és megköveteli, hogy a fejléc értékét a környező idézőjelekkel kell meghatározni. A $InvalidHeaders változóhoz egy kivonattáblát rendelünk, amelynek értéke If-Match érvénytelen, mert a függvény a helyett "12345"a következőképpen van definiálva12345.

Az érvénytelen fejléceket tartalmazó hívás Invoke-RestMethod hibaüzenetet ad vissza, amely szerint a formázott érték érvénytelen. A rendszer nem küldi el a kérést a végpontnak.

A SkipHeaderValidation paraméterrel való hívás Invoke-RestMethod figyelmen kívül hagyja az érvényesítési hibát, és elküldi a kérést a végpontnak. Mivel a végpont nem megfelelő fejlécértékeket tolerál, a parancsmag hiba nélkül adja vissza a válaszobjektumot.

Paraméterek

-AllowUnencryptedAuthentication

Lehetővé teszi a hitelesítő adatok és titkos kódok küldését titkosítatlan kapcsolatokon keresztül. Alapértelmezés szerint a hitelesítő adatok vagy bármely hitelesítési lehetőség nem kezdődő https://URI-val való megadásával hiba lép fel, és a kérés megszakítja a titkos kulcsok nem titkosított kapcsolatokon keresztüli véletlen közlését. Ha ezt a viselkedést saját felelősségére szeretné felülbírálni, adja meg az AllowUnencryptedAuthentication paramétert.

Figyelmeztetés

A paraméter használata nem biztonságos, ezért nem ajánlott. Csak az örökölt rendszerekkel való kompatibilitás érdekében érhető el, amelyek nem tudnak titkosított kapcsolatokat biztosítani. Saját felelősségre használható.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Authentication

Megadja a kérelemhez használandó explicit hitelesítési típust. Az alapértelmezett érték Nincs. A hitelesítési paraméter nem használható a UseDefaultCredentials paraméterrel.

Elérhető hitelesítési lehetőségek:

  • None: Ez az alapértelmezett beállítás, ha a hitelesítés nincs megadva. A rendszer nem használ explicit hitelesítést.
  • Basic: Hitelesítő adatokat igényel. A hitelesítő adatokkal az RFC 7617 Egyszerű hitelesítés Authorization: Basic fejléce base64(user:password)küldhető el a következő formátumban: .
  • Bearer: A Token paramétert igényli. Egy RFC 6750-fejlécet Authorization: Bearer küld a megadott jogkivonattal.
  • OAuth: A Token paramétert igényli. Egy RFC 6750-fejlécet Authorization: Bearer küld a megadott jogkivonattal.

A hitelesítés megadása felülbírálja Authorization a fejlécekhez megadott vagy a WebSession szolgáltatásban található fejléceket.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:WebAuthenticationType
Accepted values:None, Basic, Bearer, OAuth
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-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 is beszűkítheti.Invoke-RestMethod

A Törzs 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 kivonattáblázat), akkor a rendszer a törzset lekérdezési paraméterekként hozzáadja az egységes erőforrás-azonosítóhoz (URI). 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.

Ha a törzs egy űrlap, vagy egy másik Invoke-WebRequest hívás kimenete, a PowerShell a kérelem tartalmát az űrlapmezőkre állítja.

A Body paraméter egy System.Net.Http.MultipartFormDataContent objektumot is elfogadhat. Ez megkönnyíti multipart/form-data a kéréseket. Ha egy MultipartFormDataContent objektumot ad meg a Body elemhez, a ContentType, Headers vagy WebSession paraméterekhez megadott tartalomhoz kapcsolódó fejléceket felülbírálják az MultipartFormDataContent objektum tartalomfejlécei. Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:Object
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False

-Certificate

Megadja a biztonságos webes kéréshez használt ügyféltanúsítványt. Adjon meg egy olyan változót, amely tanúsítványt vagy parancsot vagy kifejezést tartalmaz, amely lekéri a tanúsítványt.

Tanúsítvány kereséséhez használja Get-PfxCertificate vagy használja a Get-ChildItem tanúsítvány (Cert:) meghajtón található parancsmagot. Ha a tanúsítvány érvénytelen vagy nem rendelkezik megfelelő jogosultságtal, a parancs meghiúsul.

Type:X509Certificate
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters: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.

A tanúsítvány ujjlenyomatának lekéréséhez használja a Get-Item PowerShell-meghajtón Cert: található parancsotGet-ChildItem.

Megjegyzés

Ez a funkció jelenleg csak Windows operációsrendszer-platformokon támogatott.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters: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 a következőre application/x-www-form-urlencodedállítja be: . Ellenkező esetben a hívásban nincs megadva a tartalomtípus.

A ContentType felül lesz bírálva, amikor egy MultipartFormDataContent objektumot ad meg a törzs számára.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Olyan felhasználói fiókot ad meg, amely jogosult a kérés elküldésére. Alapértelmezés szerint az aktuális felhasználó.

Írjon be egy felhasználónevet (például User01 vagy Domain01\User01), vagy adjon meg egy, a Get-Credential parancsmag által létrehozott PSCredential objektumot.

A hitelesítő adatok önállóan vagy bizonyos hitelesítési paraméterekkel együtt is használhatók. Egyedül használva csak akkor ad meg hitelesítő adatokat a távoli kiszolgálónak, ha a távoli kiszolgáló hitelesítési kérést küld. Ha hitelesítési beállításokat használ, a rendszer explicit módon elküldi a hitelesítő adatokat.

A hitelesítő adatokat egy PSCredential objektum tárolja, a jelszót Pedig SecureString-ként tárolja a rendszer.

Megjegyzés

További információ a SecureString adatvédelemről: How secure is SecureString?.

Type:PSCredential
Position:Named
Default value:Current user
Accept pipeline input:False
Accept wildcard characters:False

-CustomMethod

A webes kérelemhez használt egyéni metódust adja meg. Ez a végpont által igényelt kérelemmetódussal használható, és nem érhető el a metódusban. A metódus és a CustomMethod nem használható együtt.

Példa:

Invoke-RestMethod -uri 'https://api.contoso.com/widget/' -CustomMethod 'TEST'

Ez HTTP-kérést TEST küld az API-nak.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:String
Aliases:CM
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-DisableKeepAlive

Azt jelzi, hogy a parancsmag a HTTP-fejléc KeepAlive értékét False (Hamis) értékre állítja. Alapértelmezés szerint a KeepAlive értéke Igaz. A KeepAlive állandó kapcsolatot létesít a kiszolgálóval a további kérések megkönnyítése érdekében.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-FollowRelLink

Azt jelzi, hogy a parancsmagnak relációs hivatkozásokat kell követnie.

Egyes REST API-k támogatják a relációs hivatkozásokon keresztüli lapozást RFC5988-onként. Ahelyett, hogy elemezte volna a fejlécet a következő oldal URL-címének lekéréséhez, a parancsmag ezt megteheti Ön helyett. Ha meg szeretné adni, hogy hányszor kövesse a relációs hivatkozásokat, használja a MaximumFollowRelLink paramétert.

A kapcsoló használatakor a parancsmag eredményoldalak gyűjteményét adja vissza. Az eredmények oldalai több találatelemet is tartalmazhatnak.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Aliases:FL
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Form

Egy szótárt beküldővé multipart/form-data alakít át. Az űrlap nem használható a Body billentyűvel. Ha a ContentType nem lesz figyelmen kívül hagyva.

A szótár kulcsai lesznek az űrlapmezők nevei. Alapértelmezés szerint az űrlapértékek sztringértékekké lesznek konvertálva.

Ha az érték System.IO.FileInfo objektum, akkor a bináris fájl tartalma lesz elküldve. A fájl neve a következő lesz filename: . A MIME beállítása application/octet-streama következő lesz: . Get-Item a System.IO.FileInfo objektum megadásának egyszerűsítésére használható.

$Form = @{ önéletrajz = Get-Item 'c:\Users\jdoe\Documents\John Doe.pdf' }

Ha az érték gyűjteménytípus, például tömb vagy lista, a for mező többször lesz elküldve. A lista értékei alapértelmezés szerint sztringként lesznek kezelve. Ha az érték System.IO.FileInfo objektum, akkor a bináris fájl tartalma lesz elküldve. A beágyazott gyűjtemények nem támogatottak.

$Form = @{ tags = 'Vacation', 'Italy', '2017' pictures = Get-ChildItem 'c:\Users\jdoe\Pictures\2017-Italy' }

A fenti példában a tags mező háromszor lesz megadva az űrlapon, egyszer az egyes Vacation, Italyés 2017. A pictures mező a mappában lévő 2017-Italy minden fájlhoz egyszer lesz elküldve. A mappában lévő fájlok bináris tartalma lesz elküldve értékekként.

Ez a funkció a PowerShell 6.1.0-s verzióban lett hozzáadva.

Type:IDictionary
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Headers

Megadja a webes kérelem fejléceit. Adjon meg egy kivonattáblát vagy szótárt.

A UserAgent fejlécek beállításához használja a UserAgent paramétert. Ezt a paramétert nem használhatja cookie-fejlécek megadására User-Agent .

A tartalommal kapcsolatos fejlécek, például Content-Type felül lesznek bírálva, amikor egy MultipartFormDataContent objektumot ad meg a törzshöz.

Type:IDictionary
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters: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.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-MaximumFollowRelLink

Megadja, hogy hányszor kövesse a relációs hivatkozásokat , ha a FollowRelLinket használja. Kisebb értékre lehet szükség, ha a REST API túl sok kérés miatt szabályoz. Az alapértelmezett érték [Int32]::MaxValue. A 0 (nulla) érték megakadályozza a relációs hivatkozások követését.

Type:Int32
Aliases:ML
Position:Named
Default value:Int32.MaxValue
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Azt adja meg, hogy a PowerShell hányszor irányítja át a kapcsolatot egy másodlagos egységes erőforrás-azonosítóra (URI), mielőtt a kapcsolat megszakad. Az alapértelmezett érték 5. A 0 (nulla) érték megakadályozza az átirányítást.

Type:Int32
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRetryCount

Meghatározza, hogy a PowerShell hányszor próbálkozik újra egy kapcsolattal, ha a rendszer 400 és 599 közötti hibakódot fogad, beleértve a 304-et is. Lásd még a RetryIntervalSec paramétert az újrapróbálkozások számának megadásához.

Type:Int32
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Method

A webes kérelemhez használt metódust adja meg. A paraméter elfogadható értékei a következők:

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace

A CustomMethod paraméter a fent nem felsorolt kérésmetódusokhoz használható.

Type:WebRequestMethod
Accepted values:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-NoProxy

Azt jelzi, hogy a parancsmag nem használ proxyt a cél eléréséhez.

Ha meg kell kerülnie az Internet Explorerben konfigurált proxyt vagy a környezetben megadott proxyt, használja ezt a kapcsolót.

Ezt a paramétert a PowerShell 6.0-ban vezettük be.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-OutFile

Menti a válasz törzsét a megadott kimeneti fájlba. 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. A név literális elérési útként lesz kezelve. A szögletes zárójeleket ([]) tartalmazó neveket szimpla idézőjelek (') közé kell foglalni.

Alapértelmezés szerint Invoke-RestMethod visszaadja az eredményeket a folyamatnak.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

Ez a paraméter csak akkor érvényes, ha az OutFile paramétert is használja a parancsban. A cél az, hogy az eredményeket a fájlba és a folyamatba írja.

Megjegyzés

A PassThru paraméter használatakor a kimenet a folyamatba lesz írva, de a fájl nem jön létre. További információ: PowerShell-probléma #15409.

Type:SwitchParameter
Position:Named
Default value:No output
Accept pipeline input:False
Accept wildcard characters:False

-PreserveAuthorizationOnRedirect

Azt jelzi, hogy a parancsmagnak meg kell őriznie a Authorization fejlécet, ha van ilyen, az átirányítások között.

Alapértelmezés szerint a parancsmag az átirányítás előtt eltávolítja a Authorization fejlécet. A paraméter megadása letiltja ezt a logikát azokban az esetekben, amikor a fejlécet az átirányítási helyre kell elküldeni.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-Proxy

Proxykiszolgálót használ a kéréshez ahelyett, hogy közvetlenül csatlakozik az internetes erőforráshoz. Adja meg egy hálózati proxykiszolgáló egységes erőforrás-azonosítóját (URI).

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:Uri
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Olyan felhasználói fiókot ad meg, amely jogosult a proxyparaméter által megadott proxykiszolgáló használatára. Alapértelmezés szerint az aktuális felhasználó.

Írjon be egy felhasználónevet (például User01 vagy Domain01\User01), User@Domain.Comvagy írjon be egy PSCredential objektumot, például a Get-Credential parancsmag által létrehozottat.

Ez a paraméter csak akkor érvényes, ha a proxyparamétert is használja a parancsban. Nem használhatja a ProxyCredential és a ProxyUseDefaultCredentials paramétereket ugyanabban a parancsban.

Type:PSCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ProxyUseDefaultCredentials

Azt jelzi, hogy a parancsmag az aktuális felhasználó hitelesítő adataival fér hozzá a proxyparaméter által megadott proxykiszolgálóhoz.

Ez a paraméter csak akkor érvényes, ha a proxyparamétert is használja a parancsban. Nem használhatja a ProxyCredential és a ProxyUseDefaultCredentials paramétereket ugyanabban a parancsban.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-ResponseHeadersVariable

Létrehoz egy válaszfejlécszótárat tartalmazó változót. Adjon meg egy változónevet a dollárjel ($) szimbólum nélkül. A szótár kulcsai tartalmazzák a webkiszolgáló által visszaadott válaszfejléc mezőnevét és értékeit.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:String
Aliases:RHV
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Resume

Minden erőfeszítést megtesz egy részleges fájl letöltésének folytatására. A Resume paraméterhez az OutFile paraméter szükséges.

Az önéletrajz csak a helyi fájl és a távoli fájl méretén működik, és nem végez más ellenőrzést arról, hogy a helyi fájl és a távoli fájl azonos-e.

Ha a helyi fájlméret kisebb, mint a távoli fájlméret, akkor a parancsmag megpróbálja folytatni a fájl letöltését, és hozzáfűzi a fennmaradó bájtokat a fájl végéhez.

Ha a helyi fájlméret megegyezik a távoli fájlméretével, akkor nem történik művelet, és a parancsmag feltételezi, hogy a letöltés már befejeződött.

Ha a helyi fájl mérete nagyobb, mint a távoli fájl mérete, akkor a helyi fájl felülíródik, és a teljes távoli fájl teljesen újra letöltődik. Ez a viselkedés ugyanaz, mint a Folytatás nélküli OutFile használata.

Ha a távoli kiszolgáló nem támogatja a letöltés folytatását, akkor a helyi fájl felülíródik, és a teljes távoli fájl teljesen újra letöltődik. Ez a viselkedés ugyanaz, mint a Folytatás nélküli OutFile használata.

Ha a helyi fájl nem létezik, a helyi fájl létrejön, és a teljes távoli fájl teljesen le lesz töltve. Ez a viselkedés ugyanaz, mint a Folytatás nélküli OutFile használata.

Ez a funkció a PowerShell 6.1.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-RetryIntervalSec

Megadja a kapcsolat újrapróbálkozásai közötti időközt, ha a rendszer 400 és 599 közötti hibakódot fogad, beleértve a 304-et is. Az újrapróbálkozások számának megadásához tekintse meg a MaximumRetryCount paramétert is. Az értéknek a következő közé 1 kell lennie: és [int]::MaxValue.

Type:Int32
Position:Named
Default value:5
Accept pipeline input:False
Accept wildcard characters:False

-SessionVariable

Létrehoz egy változót, amely a webes kérelem munkamenetét tartalmazza. Adjon meg egy változónevet a dollárjel ($) szimbólum nélkül.

Amikor megad egy munkamenet-változót, létrehoz egy webes kérelem munkamenet-objektumot, Invoke-RestMethod és hozzárendeli azt egy, a PowerShell-munkamenetben megadott névvel rendelkező változóhoz. A változót a parancs befejeződése után használhatja a munkamenetben.

A távoli munkamenetektől eltérően a webes kérelem 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 sztringjét. Segítségével megoszthatja az állapotot és az adatokat a webes kérések között.

A webkérelem-munkamenet későbbi webes kérésekben való használatához adja meg a munkamenet változóját a WebSession paraméter értékében. A PowerShell a webes ké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 a UserAgent vagy a Credential paramétert. 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 a WebSession paramétereket.

Type:String
Aliases:SV
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-SkipCertificateCheck

Kihagyja a tanúsítványérvényesítési ellenőrzéseket, amelyek tartalmazzák az összes ellenőrzést, például a lejáratot, a visszavonást, a megbízható legfelső szintű hitelesítésszolgáltatót stb.

Figyelmeztetés

A paraméter használata nem biztonságos, ezért nem ajánlott. Ez a kapcsoló csak az ismert gazdagépeken használható, tesztelési célokra önaláírt tanúsítvány használatával. Saját felelősségre használható.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipHeaderValidation

Azt jelzi, hogy a parancsmagnak érvényesítés nélkül kell fejléceket hozzáadnia a kérelemhez.

Ezt a kapcsolót olyan webhelyekhez kell használni, amelyek olyan fejlécértékeket igényelnek, amelyek nem felelnek meg a szabványoknak. A kapcsoló megadása letiltja az érvényesítést, hogy az érték ne legyen bejelölve. Ha meg van adva, a rendszer minden fejlécet érvényesítés nélkül ad hozzá.

Ez letiltja a ContentType, a Headers és a UserAgent paramétereknek átadott értékek érvényesítését.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipHttpErrorCheck

Ez a paraméter miatt a parancsmag figyelmen kívül hagyja a HTTP-hibaállapotokat, és folytatja a válaszok feldolgozását. A hibaválaszok ugyanúgy lesznek beírva a folyamatba, mintha sikeresek lennének.

Ez a paraméter a PowerShell 7-ben lett bevezetve.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-SslProtocol

Beállítja azokat az SSL-/TLS-protokollokat, amelyek engedélyezve vannak a webes kéréshez. Alapértelmezés szerint a rendszer által támogatott SSL/TLS protokollok engedélyezettek. Az SslProtocol lehetővé teszi adott protokollokra való korlátozást megfelelőségi célokból.

Ezek az értékek jelzőalapú számbavételként vannak definiálva. Több érték kombinálásával több jelölőt is beállíthat ezzel a paraméterrel. Az értékek átadhatók az SslProtocol paraméternek értéktömbként vagy az értékek vesszővel elválasztott sztringjeként. A parancsmag bináris VAGY művelettel egyesíti az értékeket. Az értékek tömbként való átadása a legegyszerűbb lehetőség, és lehetővé teszi a tabulátorkiegészítés használatát is az értékeken. Előfordulhat, hogy nem tud több értéket megadni minden platformon.

Megjegyzés

Nem Windows-platformokon előfordulhat, hogy nem lehet megadni Tls , vagy Tls12 lehetőségként. Tls13 A támogatás nem minden operációs rendszeren érhető el, és operációs rendszerenként kell ellenőrizni.

Ez a funkció a PowerShell 6.0.0-s verzióban lett hozzáadva, és a Tls13 Támogatás a PowerShell 7.1-ben lett hozzáadva.

Type:WebSslProtocol
Accepted values:Default, Tls, Tls11, Tls12, Tls13
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-StatusCodeVariable

Létrehoz egy változót, amely a kérés HTTP-állapotkódjának eredményét tartalmazza. Adjon meg egy változónevet a dollárjel ($) szimbólum nélkül.

A paraméter képes azonosítani a sikeres üzeneteket és a sikertelen üzeneteket a SkipHttpErrorCheck paraméterrel való használatkor.

Adja meg a paraméter változójának nevét sztringként, például -StatusCodeVariable "scv": .

Ez a paraméter a PowerShell 7-ben lett bevezetve.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TimeoutSec

Meghatározza, 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) határozatlan időre szól.

A tartománynévrendszer-lekérdezések visszatérése vagy időtúllépése akár 15 másodpercet is igénybe vehet. Ha a kérés egy feloldást igénylő állomásnevet tartalmaz, és a TimeoutSec értékét nullánál nagyobb, de 15 másodpercnél rövidebb értékre állítja be, az a WebException kidobása előtt 15 másodpercet vagy többet is igénybe vehet, és a kérés túllépi az időkorlátot.

Type:Int32
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Token

A kérelembe belefoglalandó OAuth- vagy Tulajdonosi jogkivonat. Bizonyos hitelesítési beállítások jogkivonatot igényelnek. Önállóan nem használható.

A token a jogkivonatot SecureString tartalmazó jogkivonatot veszi fel. A jogkivonat megadásához manuálisan használja a következőt:

Invoke-RestMethod -Uri $uri -Authentication OAuth -Token (Read-Host -AsSecureString)

Ezt a paramétert a PowerShell 6.0-ban vezettük be.

Type:SecureString
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-TransferEncoding

Megadja az átvitelkódoló HTTP-válaszfejléc értékét. A paraméter elfogadható értékei a következők:

  • Adattömb
  • Tömöríteni
  • Deflate
  • Gzip
  • Identitás
Type:String
Accepted values:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Uri

Annak az internetes erőforrásnak az egységes erőforrás-azonosítóját (URI) adja meg, amelyre a webes kérést 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ő.

Type:Uri
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-UseBasicParsing

Ez a paraméter elavult. A PowerShell 6.0.0-tól kezdve minden webes kérés csak alapszintű elemzést használ. Ez a paraméter csak a visszamenőleges kompatibilitás érdekében érhető el, és a használata semmilyen hatással nem lesz a parancsmag működésére.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-UseDefaultCredentials

Azt jelzi, hogy a parancsmag az aktuális felhasználó hitelesítő adataival küldi el a webes kérést. Ez nem használható hitelesítéssel vagy hitelesítő adatokkal , és nem minden platformon támogatott.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

-UserAgent

Megadja a webes kérelemhez tartozó felhasználói ügynök sztringet.

Az alapértelmezett felhasználói ügynök hasonló Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 az egyes operációs rendszerek és platformok kis eltéréseihez.

Ha egy webhelyet a legtöbb internetböngésző által használt szabványos felhasználóiügynök-sztringgel szeretne tesztelni, használja a PSUserAgent osztály (például Chrome, FireFox, InternetExplorer, Opera és Safari) tulajdonságait.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters: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 a UserAgent vagy a Credential paramétert. A paraméterértékek elsőbbséget élveznek a webes kérelem munkamenetében lévő értékekkel szemben. A tartalommal kapcsolatos fejlécek, például Content-Typea , felül lesznek bírálva, ha egy MultipartFormDataContent objektumot ad meg a törzshöz.

A távoli munkamenetektől eltérően a webes kérelem 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 sztringjét. Segítségével megoszthatja az állapotot és az adatokat a webes kérések között.

Webes kérelem munkamenetének létrehozásához írjon be egy változónevet dollárjel nélkül a parancs SessionVariable paraméterének értékébe Invoke-RestMethod . Invoke-RestMethod A létrehozza a munkamenetet, és menti a változóba. 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 a WebSession paramétereket.

Type:WebRequestSession
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Bevitelek

Object

A webes kérés törzsét átirányíthatja a következőre Invoke-RestMethod: .

Kimenetek

System.Int64, System.String, System.Xml.XmlDocument

A parancsmag kimenete a lekért tartalom formátumától függ.

PSObject

Ha a kérelem JSON-sztringeket ad vissza, Invoke-RestMethod egy PSObject értéket ad vissza, amely a sztringeket jelöli.

Jegyzetek

Előfordulhat, hogy egyes funkciók nem minden platformon érhetők el.

A .NET Core 3.1 változásai miatt a PowerShell 7.0-s és újabb verziói a HttpClient.DefaultProxy tulajdonsággal határozzák meg a proxykonfigurációt.

Ennek a tulajdonságnak az értéke a platformtól függően eltérő szabályok:

  • Windows esetén: Beolvassa a proxykonfigurációt a környezeti változókból, vagy ha ezek nincsenek meghatározva, a felhasználó proxybeállításaiból.
  • MacOS esetén: Beolvassa a proxykonfigurációt a környezeti változókból, vagy ha ezek nincsenek meghatározva, a rendszer proxybeállításaiból.
  • Linux esetén: Beolvassa a proxykonfigurációt a környezeti változókból, vagy ha ezek nincsenek meghatározva, ez a tulajdonság inicializál egy nem konfigurált példányt, amely minden címet megkerül.

A Windows- és Unix-alapú platformokon az inicializáláshoz DefaultProxy használt környezeti változók a következők:

  • HTTP_PROXY: a HTTP-kérelmekhez használt proxykiszolgáló állomásneve vagy IP-címe.
  • HTTPS_PROXY: a HTTPS-kérelmekhez használt proxykiszolgáló állomásneve vagy IP-címe.
  • ALL_PROXY: a HTTP- és HTTPS-kérelmekben használt proxykiszolgáló állomásneve vagy IP-címe, ha HTTP_PROXYHTTPS_PROXY nincs meghatározva.
  • NO_PROXY: azoknak az állomásneveknek a vesszővel tagolt listája, amelyeket ki kell zárni a proxyzásból.