다음을 통해 공유

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 요청을 보냅니다.

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

메모

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

이 명령은 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: 여러 헤더 전달

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

$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 형식의 요청 본문 값으로 설정됩니다.

경고

POST 본문의 자세한 출력은 본문의 크기가 이미 알려져 있고 with -1-byte payload HTTP 헤더에서 전송되더라도 Content-Length로 끝납니다.

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

-Certificate

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

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

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

-CertificateThumbprint

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

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

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

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

-ContentType

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

ContentType 값에 인코딩 형식(charset)이 포함된 경우 cmdlet은 해당 형식을 사용하여 웹 요청의 본문을 인코딩합니다. ContentType 인코딩 형식을 지정하지 않으면 기본 인코딩 형식이 대신 사용됩니다. 인코딩 형식이 있는 ContentType의 예로는 text/plain; charset=iso-8859-5가 있으며, 이는 라틴어/키릴 자모 알파벳을 지정합니다.

매개 변수를 생략하면 사용하는 HTTP 메서드에 따라 콘텐츠 형식이 다를 수 있습니다.

  • POST 메서드의 경우 콘텐츠 형식이 application/x-www-form-urlencoded
  • PUT 메서드의 경우 콘텐츠 형식이 application/json
  • 다른 메서드의 경우 콘텐츠 형식이 요청에 지정되지 않습니다.

InFile 매개 변수를 사용하여 파일을 업로드하는 경우 콘텐츠 형식을 설정해야 합니다. 일반적으로 형식은 application/octet-stream합니다. 그러나 엔드포인트의 요구 사항에 따라 콘텐츠 형식을 설정해야 합니다.

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

-Credential

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

User01 또는 Domain01\User01같은 사용자 이름을 입력하거나 cmdlet에서 생성된 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:False
필수:False
파이프라인 입력 허용:False
와일드카드 문자 허용:False

-Headers

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

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

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

-InFile

파일에서 웹 요청 본문의 콘텐츠를 가져옵니다. 경로 및 파일 이름을 입력합니다. 경로를 생략하면 기본값은 현재 위치입니다.

요청의 콘텐츠 형식도 설정해야 합니다. 예를 들어 파일을 업로드하려면 콘텐츠 형식을 설정해야 합니다. 일반적으로 형식은 application/octet-stream합니다. 그러나 엔드포인트의 요구 사항에 따라 콘텐츠 형식을 설정해야 합니다.

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

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

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

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

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

-ProxyUseDefaultCredentials

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

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

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

-SessionVariable

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

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

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

후속 웹 요청에서 웹 요청 세션을 사용하려면 WebSession 매개 변수 값에 세션 변수를 지정합니다. PowerShell은 새 연결을 설정할 때 웹 요청 세션 개체의 데이터를 사용합니다. 웹 요청 세션의 값을 재정의하려면 UserAgent 또는 자격 증명같은 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 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0 유사합니다.

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

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

-WebSession

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

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

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

웹 요청 세션을 만들려면 명령의 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