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

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

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

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

메모

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

예제

예제 1: PowerShell RSS 피드 가져오기

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

이 명령은 Invoke-RestMethod cmdlet을 사용하여 PowerShell 블로그 RSS 피드에서 정보를 가져옵니다. 이 명령은 Format-Table cmdlet을 사용하여 테이블에 있는 각 블로그의 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: 여러 헤더 전달

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

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

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

매개 변수

-Body

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

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

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

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

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

예를 들어:

$R = Invoke-WebRequest https://website.com/login.aspx $R.Forms[0]. Name = "MyName" $R.Forms[0]. 암호 = "MyPassword" Invoke-RestMethod https://website.com/service.aspx -Body $R.Forms[0]

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

인증서 지문을 가져오려면 Windows PowerShell(Cert:) 드라이브에서 Get-Item 또는 Get-ChildItem 명령을 사용합니다.

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

-ContentType

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

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

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

-Credential

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

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

형식:	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

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

기본값
삭제하다
가져오기
머리
병합
옵션
패치
올리기
놓다
자취

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

-OutFile

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

기본적으로 Invoke-RestMethod 파이프라인에 결과를 반환합니다. 결과를 파일 및 파이프라인으로 보내려면 -Passthru 매개 변수를 사용합니다.

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

-PassThru

결과를 파일에 쓰는 것 외에도 반환합니다. 이 매개 변수는 -OutFile 매개 변수가 명령에 사용되는 경우에만 유효합니다.

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

-Proxy

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

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

-ProxyCredential

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

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

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

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

-ProxyUseDefaultCredentials

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

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

-SessionVariable

웹 요청 세션을 만들고 지정된 변수의 값에 저장합니다. 달러 기호($) 기호 없이 변수 이름을 입력합니다.

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

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

후속 웹 요청에서 웹 요청 세션을 사용하려면 -WebSession 매개 변수 값에 세션 변수를 지정합니다. Windows 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 응답 헤더의 값을 지정합니다. 이 매개 변수에 허용되는 값은 다음과 같습니다.

청크 분할
압축
폐
GZip
신원

형식:	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 클래스의 속성을 사용합니다.

예를 들어 다음 명령은 인터넷에 대한 사용자 에이전트 문자열을 사용합니다.

Invoke-WebRequest -Uri https://website.com/ -UserAgent([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer)

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

-WebSession

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

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

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

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

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

입력

Object

웹 요청의 본문을 파이프하여 Invoke-RestMethod수 있습니다.

출력

System.Xml.XmlDocument, Microsoft.PowerShell.Commands.HtmlWebResponseObject, System.String

cmdlet의 출력은 검색되는 콘텐츠의 형식에 따라 달라집니다.

PSObject

요청이 JSON 문자열을 반환하는 경우 Invoke-RestMethod 문자열을 나타내는 PSObject를 반환합니다.

다음을 통해 공유

Invoke-RestMethod

구문

Description

예제

예제 1: PowerShell RSS 피드 가져오기

예제 2

예제 3: 여러 헤더 전달

매개 변수

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

입력

출력

추가 리소스

다음을 통해 공유

Invoke-RestMethod

구문

Description

예제

예제 1: PowerShell RSS 피드 가져오기

예제 2

예제 3: 여러 헤더 전달

매개 변수

-Body

-Certificate

-CertificateThumbprint

-ContentType

-Credential

-DisableKeepAlive

-Headers

-InFile

-MaximumRedirection

-Method

-OutFile

-PassThru

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-SessionVariable

-TimeoutSec

-TransferEncoding

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

입력

출력

관련 링크

추가 리소스