다음을 통해 공유

Invoke-RestMethod

  • 참조
모듈:
Microsoft.PowerShell.Utility

HTTP 또는 HTTPS 요청을 RESTful 웹 서비스로 보냅니다.

구문

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

cmdlet은 Invoke-RestMethod 풍부한 구조화된 데이터를 반환하는 REST(Representational State Transfer) 웹 서비스에 HTTP 및 HTTPS 요청을 보냅니다.

PowerShell은 데이터 형식에 따라 응답 형식을 지정합니다. RSS 또는 ATOM 피드의 경우 PowerShell은 항목 또는 항목 XML 노드를 반환합니다. JSON(JavaScript Object Notation) 또는 XML의 경우 PowerShell은 콘텐츠를 개체로 [PSCustomObject] 변환하거나 역직렬화합니다.

참고 항목

REST 엔드포인트가 여러 개체를 반환하면 개체가 배열로 수신됩니다. 출력을 다른 명령으로 Invoke-RestMethod 파이프하면 단일 [Object[]] 개체로 전송됩니다. 해당 배열의 내용은 파이프라인의 다음 명령에 대해 열거되지 않습니다.

이 cmdlet은 Windows PowerShell 3.0에서 도입되었습니다.

참고 항목

기본적으로 웹 페이지의 스크립트 코드는 페이지를 구문 분석하여 속성을 채울 ParsedHtml 때 실행될 수 있습니다. UseBasicParsing 스위치를 사용하여 이를 표시하지 않습니다.

예제

예제 1: 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

이 명령은 cmdlet을 Invoke-RestMethod 사용하여 PowerShell 블로그 RSS 피드에서 정보를 가져옵니다. 이 명령은 cmdlet을 Format-Table 사용하여 표에 있는 각 블로그의 Title 및 pubDate 속성 값을 표시합니다.

예제 2

다음 예제에서는 사용자가 실행 Invoke-RestMethod 하여 사용자 조직의 인트라넷 웹 사이트에서 POST 요청을 수행합니다.

$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"}}

예제 3: 여러 헤더 전달

이 예제에서는 여러 헤더를 REST API로 hash-table 전달하는 방법을 보여 줍니다.

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

API는 인증, 유효성 검사 등을 위해 전달된 헤더가 필요한 경우가 많습니다.

예제 3: 양식 데이터 제출

본문이 폼이거나 다른 Invoke-WebRequest 호출의 출력인 경우 PowerShell은 요청 콘텐츠를 양식 필드로 설정합니다.

예시:

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

예제 4: 파이프라인에서 반환된 항목 열거

GitHub는 배열을 여러 개체로 반환합니다. 출력을 다른 명령으로 파이프하면 단일 [Object[]]개체로 전송됩니다.

개체를 파이프라인으로 열거하려면 결과를 Write-Output 괄호로 괄호 안에 넣거나 cmdlet을 래핑합니다. 다음 예제에서는 GitHub에서 반환된 개체 수를 계산합니다. 그런 다음 파이프라인에 열거된 개체 수를 계산합니다.

$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

매개 변수

-Body

요청 본문을 지정합니다. 본문은 헤더 뒤에 있는 요청의 내용입니다. 본문 값을 으로 파이프할 Invoke-RestMethod수도 있습니다.

Body 매개 변수를 사용하여 쿼리 매개 변수 목록을 지정하거나 응답 내용을 지정할 수 있습니다.

입력이 GET 요청이고 본문이 IDictionary(일반적으로 해시 테이블)인 경우 본문은 쿼리 매개 변수로 URI에 추가됩니다. 다른 요청 형식(예: POST)의 경우 본문은 표준 name=value 형식의 요청 본문 값으로 설정됩니다.

Warning

POST 본문의 자세한 출력은 본문의 크기가 모두 알려져 있고 HTTP 헤더에서 Content-Length 전송되더라도 종료with -1-byte payload됩니다.

형식:Object
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:True
와일드카드 문자 허용:False

-Certificate

보안 웹 요청에 사용되는 클라이언트 인증서를 지정합니다. 인증서가 포함된 변수를 입력하거나 인증서를 가져오는 명령 또는 식을 입력합니다.

인증서를 찾으려면 인증서(Cert:) 드라이브에서 cmdlet을 사용하거나 사용합니다.Get-PfxCertificate Get-ChildItem 인증서가 유효하지 않거나 권한이 충분하지 않으면 명령이 실패합니다.

형식:X509Certificate
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-CertificateThumbprint

요청을 보낼 수 있는 권한이 있는 사용자 계정의 디지털 공개 키 인증서(X509)를 지정합니다. 인증서의 인증서 지문을 입력합니다.

인증서는 클라이언트 인증서 기반 인증에 사용됩니다. 인증서는 도메인 계정이 아닌 로컬 사용자 계정에만 매핑할 수 있습니다.

인증서 지문을 보려면 또는 명령을 사용하여 Get-Item 인증서를 찾습니다Cert:\CurrentUser\My.Get-ChildItem

형식:String
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-ContentType

웹 요청의 콘텐츠 형식을 지정합니다.

이 매개 변수를 생략하고 요청 메서드가 POST Invoke-RestMethod 인 경우 콘텐츠 형식을 "application/x-www-form-urlencoded"로 설정합니다. 그러지 않으면 호출에서 콘텐츠 형식이 지정되지 않습니다.

형식:String
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Credential

요청을 보낼 수 있는 권한이 있는 사용자 계정을 지정합니다. 기본값은 현재 사용자입니다.

User01 또는 Domain01\User01과 같은 사용자 이름을 입력하거나 cmdlet에서 생성된 PSCredential 개체를 Get-Credential 입력합니다.

자격 증명은 PSCredential 개체에 저장되고 암호는 SecureString으로 저장됩니다.

참고 항목

SecureString 데이터 보호에 대한 자세한 내용은 SecureString이 얼마나 안전한가요?를 참조하세요.

형식:PSCredential
Position:Named
Default value:Current user
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-DisableKeepAlive

HTTP 헤더의 KeepAlive 값을 False로 설정합니다. 기본적으로 KeepAlive 는 True입니다. KeepAlive 는 후속 요청을 용이하게 하기 위해 서버에 대한 영구 연결을 설정합니다.

형식:SwitchParameter
Position:Named
Default value:KeepAlive
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Headers

웹 요청의 헤더를 지정합니다. 해시 테이블 또는 사전을 입력합니다.

UserAgent 헤더를 설정하려면 UserAgent 매개 변수를 사용합니다. 이 매개 변수를 사용하여 UserAgent 또는 쿠키 헤더를 지정할 수 없습니다.

형식:IDictionary
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-InFile

파일에서 웹 요청의 콘텐츠를 가져옵니다.

경로 및 파일 이름을 입력합니다. 경로를 생략하면 기본값은 현재 위치입니다.

형식:String
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-MaximumRedirection

연결이 실패하기 전에 Windows PowerShell에서 연결을 대체 URI(Uniform Resource Identifier)로 리디렉션하는 횟수를 결정합니다. 기본 값은 5입니다. 값이 0이면 모든 리디렉션이 방지됩니다.

형식:Int32
Position:Named
Default value:5
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Method

웹 요청에 사용되는 메서드를 지정합니다. 이 매개 변수에 허용되는 값은 다음과 같습니다.

  • Default
  • Delete
  • Get
  • Head
  • Merge
  • Options
  • Patch
  • Post
  • Put
  • Trace
형식:WebRequestMethod
허용되는 값:Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
Position:Named
Default value:Default
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-OutFile

지정된 출력 파일에 응답 본문을 저장합니다. 경로 및 파일 이름을 입력합니다. 경로를 생략하면 기본값은 현재 위치입니다.

기본적으로 Invoke-RestMethod 파이프라인에 결과를 반환합니다.

형식:String
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-PassThru

이 매개 변수는 OutFile 매개 변수가 명령에 사용되는 경우에만 유효합니다. 결과는 파일 및 파이프라인에 기록됩니다.

참고 항목

PassThru 매개 변수를 사용하는 경우 출력은 파이프라인에 기록되지만 파일은 비어 있습니다. 자세한 내용은 PowerShell 문제 #15409를 참조하세요.

형식:SwitchParameter
Position:Named
Default value:No output
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Proxy

인터넷 리소스에 직접 연결하는 대신 요청에 프록시 서버를 사용합니다. 네트워크 프록시 서버의 URI를 입력합니다.

형식:Uri
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-ProxyCredential

프록시 매개 변수로 지정된 프록시 서버를 사용할 수 있는 권한이 있는 사용자 계정을 지정합니다. 기본값은 현재 사용자입니다.

"User01" 또는 "Domain01\User01"과 같은 사용자 이름을 입력하거나 cmdlet에서 생성된 것과 같은 PSCredential 개체를 Get-Credential 입력합니다.

이 매개 변수는 프록시 매개 변수가 명령에 사용되는 경우에만 유효합니다. 동일한 명령에서 ProxyCredential 및 ProxyUseDefaultCredentials 매개 변수를 사용할 수 없습니다.

형식:PSCredential
Position:Named
Default value:Current user
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-ProxyUseDefaultCredentials

현재 사용자의 자격 증명을 사용하여 프록시 매개 변수로 지정된 프록시 서버에 액세스합니다.

이 매개 변수는 프록시 매개 변수가 명령에 사용되는 경우에만 유효합니다. 동일한 명령에서 ProxyCredential 및 ProxyUseDefaultCredentials 매개 변수를 사용할 수 없습니다.

형식:SwitchParameter
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-SessionVariable

웹 요청 세션을 포함하는 변수를 만듭니다. 달러 기호($) 기호 없이 변수 이름을 입력합니다.

세션 변수 Invoke-RestMethod 를 지정하면 웹 요청 세션 개체를 만들고 PowerShell 세션에서 지정된 이름을 가진 변수에 할당합니다. 명령이 완료되는 즉시 세션에서 변수를 사용할 수 있습니다.

원격 세션과 달리 웹 요청 세션은 영구 연결이 아닙니다. 쿠키, 자격 증명, 최대 리디렉션 값 및 사용자 에이전트 문자열을 포함하여 연결 및 요청에 대한 정보를 포함하는 개체입니다. 웹 요청 간에 상태 및 데이터를 공유하는 데 사용할 수 있습니다.

후속 웹 요청에서 웹 요청 세션을 사용하려면 WebSession 매개 변수 값에 세션 변수를 지정합니다. PowerShell은 새 연결을 설정할 때 웹 요청 세션 개체의 데이터를 사용합니다. 웹 요청 세션의 값을 재정의하려면 UserAgent 또는 Credential과 같은 cmdlet 매개 변수를 사용합니다. 매개 변수 값이 웹 요청 세션의 값보다 우선합니다.

동일한 명령에서는 SessionVariable 및 WebSession 매개 변수를 사용할 수 없습니다.

형식:String
별칭:SV
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-TimeoutSec

요청이 시간 초과되기 전에 보류할 수 있는 기간을 지정합니다. 값을 초 단위로 입력합니다. 기본값 0은 무기한 시간 제한을 지정합니다.

DNS(도메인 이름 시스템) 쿼리는 반환 또는 시간 초과에 최대 15초가 걸릴 수 있습니다. 요청에 해결이 필요한 호스트 이름이 포함되어 있고 TimeoutSec을 0보다 크지만 15초 미만의 값으로 설정하면 WebException이 throw되기까지 15초 이상 걸릴 수 있으며 요청 시간이 초과됩니다.

형식:Int32
Position:Named
Default value:0
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-TransferEncoding

전송 인코딩 HTTP 응답 헤더의 값을 지정합니다. 이 매개 변수에 허용되는 값은 다음과 같습니다.

  • Chunked
  • Compress
  • Deflate
  • GZip
  • Identity
형식:String
허용되는 값:chunked, compress, deflate, gzip, identity
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Uri

웹 요청을 보낼 인터넷 리소스의 URI(Uniform Resource Identifier)를 지정합니다. 이 매개 변수는 HTTP, HTTPS, FTP 및 FILE 값을 지원합니다.

이 매개 변수는 필수입니다. 매개 변수 이름(Uri)은 선택 사항입니다.

형식:Uri
Position:0
Default value:None
필수:True
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-UseBasicParsing

cmdlet이 기본 구문 분석을 사용한다는 것을 나타냅니다. cmdlet은 String 개체의 원시 HTML을 반환합니다.

형식:SwitchParameter
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-UseDefaultCredentials

현재 사용자의 자격 증명을 사용하여 웹 요청을 보냅니다.

형식:SwitchParameter
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-UserAgent

웹 요청에 대한 사용자 에이전트 문자열을 지정합니다.

기본 사용자 에이전트는 "Mozilla/5.0(Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0" - 각 운영 체제 및 플랫폼에 대한 약간의 변형이 있습니다.

대부분의 인터넷 브라우저에서 사용되는 표준 사용자 에이전트 문자열을 사용하여 웹 사이트를 테스트하려면 Chrome, FireFox, Internet Explorer, Opera 및 Safari와 같은 PSUserAgent 클래스의 속성을 사용합니다.

형식:String
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-WebSession

웹 요청 세션을 지정합니다. 달러 기호($)를 포함하여 변수 이름을 입력합니다.

웹 요청 세션의 값을 재정의하려면 UserAgent 또는 Credential과 같은 cmdlet 매개 변수를 사용합니다. 매개 변수 값이 웹 요청 세션의 값보다 우선합니다.

원격 세션과 달리 웹 요청 세션은 영구 연결이 아닙니다. 쿠키, 자격 증명, 최대 리디렉션 값 및 사용자 에이전트 문자열을 포함하여 연결 및 요청에 대한 정보를 포함하는 개체입니다. 웹 요청 간에 상태 및 데이터를 공유하는 데 사용할 수 있습니다.

웹 요청 세션을 만들려면 명령의 SessionVariable 매개 변수 값에 변수 이름(달러 기호 없음)을 Invoke-RestMethod 입력합니다. Invoke-RestMethod 는 세션을 만들고 변수에 저장합니다. 후속 명령에서 변수를 WebSession 매개 변수의 값으로 사용합니다.

동일한 명령에서 SessionVariable 및 WebSession 매개 변수를 사용할 수 없습니다.

형식:WebRequestSession
Position:Named
Default value:None
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

입력

Object

웹 요청의 본문을 이 cmdlet으로 파이프할 수 있습니다.

출력

Int64

요청에서 정수가 반환되면 이 cmdlet은 해당 정수를 반환합니다.

String

요청이 문자열을 반환하면 이 cmdlet은 해당 문자열을 반환합니다.

XmlDocument

요청이 유효한 XML을 반환하면 이 cmdlet은 XmlDocument로 반환합니다.

PSObject

요청이 JSON 문자열을 반환하면 이 cmdlet은 데이터를 나타내는 PSObject를 반환합니다.

참고

Windows PowerShell에는 다음 별칭이 포함됩니다.Invoke-RestMethod

  • irm