Invoke-RestMethod

모듈:

Microsoft.PowerShell.Utility Module

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

구문

Default (기본값)

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 스위치를 사용하여 이를 표시하지 않습니다.

매개 변수

-Body

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

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

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

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

본문이 폼이거나 다른 Invoke-WebRequest 호출의 출력인 경우 Windows 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]

매개 변수 속성

형식:	Object
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	True
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Certificate

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

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

매개 변수 속성

형식:	X509Certificate
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-CertificateThumbprint

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

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

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

매개 변수 속성

형식:	String
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-ContentType

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

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

매개 변수 속성

형식:	String
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Credential

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

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

매개 변수 속성

형식:	PSCredential
Default value:	Current user
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-DisableKeepAlive

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

매개 변수 속성

형식:	SwitchParameter
Default value:	KeepAlive
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Headers

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

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

매개 변수 속성

형식:	IDictionary
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-InFile

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

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

매개 변수 속성

형식:	String
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-MaximumRedirection

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

매개 변수 속성

형식:	Int32
Default value:	5
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Method

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

• 기본값
• 삭제
• 가져오기
• 머리
• 병합
• 옵션
• 패치
• 올리기
• Put
• 흔적

매개 변수 속성

형식:	WebRequestMethod
Default value:	Default
허용되는 값:	Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-OutFile

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

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

매개 변수 속성

형식:	String
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-PassThru

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

매개 변수 속성

형식:	SwitchParameter
Default value:	No output
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Proxy

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

매개 변수 속성

형식:	Uri
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-ProxyCredential

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

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

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

매개 변수 속성

형식:	PSCredential
Default value:	Current user
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-ProxyUseDefaultCredentials

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

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

매개 변수 속성

형식:	SwitchParameter
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-SessionVariable

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

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

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

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

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

매개 변수 속성

형식:	String
Default value:	None
와일드카드 지원:	False
DontShow:	False
별칭:	SV

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-TimeoutSec

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

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

매개 변수 속성

형식:	Int32
Default value:	0
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-TransferEncoding

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

• 청크 처리
• 압축
• 수축시키다
• GZip
• 아이덴티티

매개 변수 속성

형식:	String
Default value:	None
허용되는 값:	chunked, compress, deflate, gzip, identity
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-Uri

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

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

매개 변수 속성

형식:	Uri
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	0
필수:	True
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-UseBasicParsing

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

매개 변수 속성

형식:	SwitchParameter
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-UseDefaultCredentials

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

매개 변수 속성

형식:	SwitchParameter
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	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
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

-WebSession

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

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

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

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

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

매개 변수 속성

형식:	WebRequestSession
Default value:	None
와일드카드 지원:	False
DontShow:	False

매개 변수 집합

(All)

Position:	Named
필수:	False
파이프라인의 값:	False
속성 이름별 파이프라인의 값:	False
나머지 인수의 값:	False

CommonParameters

이 cmdlet은 일반적인 매개 변수인 -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction 및 -WarningVariable 매개 변수를 지원합니다. 자세한 내용은 about_CommonParameters를 참조하세요.

입력

Object

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

출력

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

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

PSObject

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

관련 링크

• ConvertTo-Json
• ConvertFrom-Json
• Invoke-WebRequest