Invoke-WebRequest

구문

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      [-Method <WebRequestMethod>]
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-Proxy <Uri>]
      [-ProxyCredential <PSCredential>]
      [-ProxyUseDefaultCredentials]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Invoke-WebRequest
      [-UseBasicParsing]
      [-Uri] <Uri>
      [-HttpVersion <Version>]
      [-WebSession <WebRequestSession>]
      [-SessionVariable <String>]
      [-AllowUnencryptedAuthentication]
      [-Authentication <WebAuthenticationType>]
      [-Credential <PSCredential>]
      [-UseDefaultCredentials]
      [-CertificateThumbprint <String>]
      [-Certificate <X509Certificate>]
      [-SkipCertificateCheck]
      [-SslProtocol <WebSslProtocol>]
      [-Token <SecureString>]
      [-UserAgent <String>]
      [-DisableKeepAlive]
      [-ConnectionTimeoutSeconds <Int32>]
      [-OperationTimeoutSeconds <Int32>]
      [-Headers <IDictionary>]
      [-SkipHeaderValidation]
      [-AllowInsecureRedirect]
      [-MaximumRedirection <Int32>]
      [-MaximumRetryCount <Int32>]
      [-PreserveAuthorizationOnRedirect]
      [-RetryIntervalSec <Int32>]
      -CustomMethod <String>
      [-PreserveHttpMethodOnRedirect]
      [-UnixSocket <UnixDomainSocketEndPoint>]
      [-NoProxy]
      [-Body <Object>]
      [-Form <IDictionary>]
      [-ContentType <String>]
      [-TransferEncoding <String>]
      [-InFile <String>]
      [-OutFile <String>]
      [-PassThru]
      [-Resume]
      [-SkipHttpErrorCheck]
      [<CommonParameters>]

Description

cmdlet은 Invoke-WebRequest 웹 페이지 또는 웹 서비스에 HTTP 및 HTTPS 요청을 보냅니다. 응답을 구문 분석하고 링크, 이미지 및 기타 중요한 HTML 요소 컬렉션을 반환합니다.

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

PowerShell 7.0 Invoke-WebRequest 부터 환경 변수로 정의된 프록시 구성을 지원합니다. 이 문서의 노트 섹션을 참조하세요.

PowerShell 7.4부터 요청에 대한 문자 인코딩은 기본적으로 ASCII 대신 UTF-8로 설정됩니다. 다른 인코딩이 필요한 경우 헤더에 charset Content-Type 특성을 설정해야 합니다.

예제

예제 1: 웹 요청 보내기

이 예제에서는 cmdlet을 Invoke-WebRequest 사용하여 웹 요청을 Bing.com 사이트로 보냅니다.

$Response = Invoke-WebRequest -URI https://www.bing.com/search?q=how+many+feet+in+a+mile
$Response.InputFields | Where-Object {
    $_.name -like "* Value*"
} | Select-Object Name, Value

name       value
----       -----
From Value 1
To Value   5280

첫 번째 명령은 요청을 실행하고 변수에 응답을 $Response 저장합니다.

두 번째 명령은 Name 속성이 같은 InputField 를 가져옵니다."* Value" 필터링된 결과는 이름 및 값 속성을 선택하기 위해 Select-Object 파이프됩니다.

예제 2: 상태 저장 웹 서비스 사용

이 예제에서는 상태 저장 웹 서비스에서 cmdlet을 사용하는 Invoke-WebRequest 방법을 보여줍니다.

$LoginParameters = @{
    Uri             = 'https://www.contoso.com/login/'
    SessionVariable = 'Session'
    Method          = 'POST'
    Body            = @{
        User     = 'jdoe'
        Password = 'P@S$w0rd!'
    }
}
$LoginResponse = Invoke-WebRequest @LoginParameters
$ProfileResponse = Invoke-WebRequest 'https://www.contoso.com/profile/' -WebSession $Session

로그인 요청을 보내는 첫 번째 호출 Invoke-WebRequest 입니다. 이 명령은 SessionVariable 매개 변수 값의 값을 Session 지정합니다. 명령이 완료되면 $LoginResponse 변수 에 BasicHtmlWebResponseObject 가 포함되고 변수에 $Session 개체가 WebRequestSession 포함됩니다. 그러면 사용자가 사이트에 기록됩니다.

두 번째 호출 Invoke-WebRequest 은 사용자가 사이트에 로그인해야 하는 사용자의 프로필을 페치합니다. 변수에 $Session 저장된 세션 데이터는 로그인 중에 만든 사이트에 세션 쿠키를 제공합니다.

예제 3: 웹 페이지에서 링크 가져오기

이 예제에서는 웹 페이지의 링크를 가져옵니다. cmdlet을 Invoke-WebRequest 사용하여 웹 페이지 콘텐츠를 가져옵니다. 그런 다음 반환되는 BasicHtmlWebResponseObject Invoke-WebRequest 의 Links 속성과 각 링크의 Href 속성을 사용합니다.

(Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs").Links.Href

예제 4: 요청된 페이지에 정의된 인코딩을 사용하여 파일에 응답 콘텐츠 쓰기

이 예제에서는 cmdlet을 Invoke-WebRequest 사용하여 PowerShell 설명서 페이지의 웹 페이지 콘텐츠를 검색합니다.

$Response = Invoke-WebRequest -Uri "https://aka.ms/pscore6-docs"
$Stream = [System.IO.StreamWriter]::new('.\docspage.html', $false, $Response.Encoding)
try {
    $Stream.Write($Response.Content)
} finally {
    $Stream.Dispose()
}

첫 번째 명령은 페이지를 검색하고 응답 개체를 변수에 $Response 저장합니다.

두 번째 명령은 파일에 응답 콘텐츠를 쓰는 데 사용할 StreamWriter를 만듭니다. 응답 개체의 인코딩 속성은 파일에 대한 인코딩을 설정하는 데 사용됩니다.

마지막 몇 명령은 Content 속성을 파일에 쓴 다음 StreamWriter를 삭제합니다.

웹 요청이 텍스트 콘텐츠를 반환하지 않는 경우 인코딩 속성은 null입니다.

예제 5: 다중 파트/양식 데이터 파일 제출

이 예제에서는 Invoke-WebRequest cmdlet을 사용하여 파일을 제출로 업로드합니다 multipart/form-data . 파일 c:\document.txt 은 다음을 사용하여 양식 필드 document 로 제출됩니다 Content-Type text/plain.

$FilePath = 'c:\document.txt'
$FieldName = 'document'
$ContentType = 'text/plain'

$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$FileHeader.Name = $FieldName
$FileHeader.FileName = Split-Path -leaf $FilePath
$FileContent = [System.Net.Http.StreamContent]::new($FileStream)
$FileContent.Headers.ContentDisposition = $FileHeader
$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType)

$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$MultipartContent.Add($FileContent)

$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload'

예제 6: 간소화된 다중 파트/양식 데이터 제출

일부 API는 파일 및 혼합 콘텐츠를 업로드하기 위해 제출이 필요합니다 multipart/form-data . 이 예제에서는 사용자 프로필을 업데이트하는 방법을 보여 줍니다.

$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-WebRequest -Uri $Uri -Method Post -Form $Form

프로필 폼에는 다음과 같은 필드가 birthdayhobbieslastNameavataremail필요합니다. firstName API는 사용자 프로필 그림에 대한 이미지가 필드에 제공 avatar 될 것으로 예상합니다. 또한 API는 동일한 형식으로 제출될 여러 hobbies 항목을 허용합니다.

HashTable을 $Form 만들 때 키 이름은 양식 필드 이름으로 사용됩니다. 기본적으로 HashTable의 값은 문자열로 변환됩니다. System.IO.FileInfo 값이 있으면 파일 내용이 제출됩니다. 배열 또는 목록과 같은 컬렉션이 있는 경우 양식 필드가 여러 번 제출됩니다.

키에서 avatar 개체 Get-Item 가 FileInfo 값으로 설정됩니다. 그 결과 이미지 데이터가 jdoe.png 제출됩니다.

키 hobbies 에 목록을 hobbies 제공하면 필드가 각 목록 항목에 대해 제출에 한 번 표시됩니다.

예제 7: Invoke-WebRequest에서 성공하지 않은 메시지 catch

Invoke-WebRequest 성공하지 못한 HTTP 메시지(404, 500 등)가 발생하면 출력을 반환하지 않고 종료 오류를 throw합니다. 오류를 catch하고 StatusCode를 보려면 실행을 블록으로 묶을 try/catch 수 있습니다.

try
{
    $Response = Invoke-WebRequest -Uri "www.microsoft.com/unkownhost"
    # This will only execute if the Invoke-WebRequest is successful.
    $StatusCode = $Response.StatusCode
} catch {
    $StatusCode = $_.Exception.Response.StatusCode.value__
}
$StatusCode

404

종료 오류는 예외 개체에서 StatusCode를 검색하는 블록에 의해 catch catch됩니다.

예제 8: 동시에 여러 파일 다운로드

cmdlet은 Invoke-WebRequest 한 번에 하나의 파일만 다운로드할 수 있습니다. 다음 예제에서는 여러 스레드 작업을 만들어 동시에 여러 파일을 다운로드하는 데 사용합니다 Start-ThreadJob .

$baseUri = 'https://github.com/PowerShell/PowerShell/releases/download'
$files = @(
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.msi"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.3.0-preview.5/PowerShell-7.3.0-preview.5-win-x64.zip"
        OutFile = 'PowerShell-7.3.0-preview.5-win-x64.zip'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.msi"
        OutFile = 'PowerShell-7.2.5-win-x64.msi'
    },
    @{
        Uri = "$baseUri/v7.2.5/PowerShell-7.2.5-win-x64.zip"
        OutFile = 'PowerShell-7.2.5-win-x64.zip'
    }
)

$jobs = @()

foreach ($file in $files) {
    $jobs += Start-ThreadJob -Name $file.OutFile -ScriptBlock {
        $params = $using:file
        Invoke-WebRequest @params
    }
}

Write-Host "Downloads started..."
Wait-Job -Job $jobs

foreach ($job in $jobs) {
    Receive-Job -Job $job
}

예제 9: 헤더 유효성 검사 건너뛰기

기본적으로 cmdlet은 Invoke-WebRequest 표준 정의 값 형식을 가진 잘 알려진 헤더의 값의 유효성을 검사합니다. 다음 예제에서는 이 유효성 검사에서 오류를 발생시키는 방법과 SkipHeaderValidation 매개 변수를 사용하여 잘못된 형식의 값을 허용한 엔드포인트에 대한 값의 유효성을 검사하지 않도록 하는 방법을 보여 줍니다.

$Uri = 'https://httpbin.org/headers'
$InvalidHeaders = @{
    'If-Match' = '12345'
}

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders

Invoke-WebRequest -Uri $Uri -Headers $InvalidHeaders -SkipHeaderValidation

Invoke-WebRequest: The format of value '12345' is invalid.

StatusCode        : 200
StatusDescription : OK
Content           : {
                      "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": �
RawContent        : HTTP/1.1 200 OK
                    Date: Mon, 08 Aug 2022 16:24:24 GMT
                    Connection: keep-alive
                    Server: gunicorn/19.9.0
                    Access-Control-Allow-Origin: *
                    Access-Control-Allow-Credentials: true
                    Content-Type: application�
Headers           : {[Date, System.String[]], [Connection, System.String[]], [Server, System.String[]], [Access-Control-Allow-Origin, System.String[]]�}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 249
RelationLink      : {}

httpbin.org 문제 해결을 위한 웹 요청 및 응답에 대한 정보를 반환하는 서비스입니다. 변수는 $Uri 요청의 헤더를 /headers 응답의 콘텐츠로 반환하는 서비스의 엔드포인트에 할당됩니다.

If-Match 요청 헤더는 RFC-7232 섹션 3.1에서 정의되며 해당 헤더의 값을 주변 따옴표로 정의해야 합니다. 변수에는 $InvalidHeaders 값이 잘못된 해시 테이블이 할당됩니다. 이 테이블 If-Match 은 값이 대신 "12345"정의되어 있기 때문 12345 입니다.

잘못된 헤더를 사용하여 호출 Invoke-WebRequest 하면 형식이 지정된 값이 잘못되었다는 오류 보고가 반환됩니다. 요청이 엔드포인트로 전송되지 않습니다.

SkipHeaderValidation 매개 변수를 사용하여 호출 Invoke-WebRequest 하면 유효성 검사 오류가 무시되고 요청이 엔드포인트로 전송됩니다. 엔드포인트는 비준수 헤더 값을 허용하므로 cmdlet은 오류 없이 응답 개체를 반환합니다.

예제 10: HTTP 2.0을 사용하여 요청 보내기

이 예제에서는 HTTP 2.0 프로토콜을 사용하여 웹 페이지의 링크를 가져옵니다. cmdlet을 Invoke-WebRequest 사용하여 웹 페이지 콘텐츠를 가져옵니다. 그런 다음 반환되는 BasicHtmlWebResponseObject Invoke-WebRequest 의 Links 속성과 각 링크의 Href 속성을 사용합니다.

(Invoke-WebRequest -Uri 'https://aka.ms/pscore6-docs' -HttpVersion 2.0).Links.Href

예제 11: Unix 소켓 애플리케이션에 요청 보내기

Docker와 같은 일부 애플리케이션은 통신을 위해 Unix 소켓을 노출합니다. 이 예제에서는 Docker API를 사용하여 Docker 이미지 목록을 쿼리합니다. 이 cmdlet은 Unix 소켓을 사용하여 Docker 디먼에 연결합니다.

Invoke-WebRequest -Uri "http://localhost/v1.40/images/json/" -UnixSocket "/var/run/docker.sock"

매개 변수

-AllowInsecureRedirect

-AllowUnencryptedAuthentication

-Authentication

-Body

-Certificate

-CertificateThumbprint

-ConnectionTimeoutSeconds

-ContentType

-Credential

-CustomMethod

-DisableKeepAlive

-Form

-Headers

-HttpVersion

-InFile

-MaximumRedirection

-MaximumRetryCount

-Method

-NoProxy

-OperationTimeoutSeconds

-OutFile

-PassThru

-PreserveAuthorizationOnRedirect

-PreserveHttpMethodOnRedirect

-Proxy

-ProxyCredential

-ProxyUseDefaultCredentials

-Resume

-RetryIntervalSec

-SessionVariable

-SkipCertificateCheck

-SkipHeaderValidation

-SkipHttpErrorCheck

-SslProtocol

-Token

-TransferEncoding

-UnixSocket

-Uri

-UseBasicParsing

-UseDefaultCredentials

-UserAgent

-WebSession

입력

Object

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

출력

BasicHtmlWebResponseObject

이 cmdlet은 웹 요청의 결과를 나타내는 응답 개체를 반환합니다.

참고

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

• 모든 플랫폼:
  • iwr

PowerShell 6.0.0 Invoke-WebRequest 부터는 기본 구문 분석만 지원합니다.

자세한 내용은 BasicHtmlWebResponseObject를 참조하세요.

.NET Core 3.1의 변경으로 인해 PowerShell 7.0 이상에서는 HttpClient.DefaultProxy 속성을 사용하여 프록시 구성을 확인합니다.

이 속성의 값은 플랫폼에 의해 결정됩니다.

• Windows의 경우: 환경 변수에서 프록시 구성을 읽습니다. 해당 변수가 정의되지 않은 경우 속성은 사용자의 프록시 설정에서 파생됩니다.
• macOS의 경우: 환경 변수에서 프록시 구성을 읽습니다. 이러한 변수가 정의되지 않은 경우 속성은 시스템의 프록시 설정에서 파생됩니다.
• Linux의 경우: 환경 변수에서 프록시 구성을 읽습니다. 해당 변수가 정의되지 않은 경우 속성은 모든 주소를 우회하는 구성되지 않은 인스턴스를 초기화합니다.

Windows 및 Unix 기반 플랫폼에서 DefaultProxy 초기화에 사용되는 환경 변수는 다음과 같습니다.

• HTTP_PROXY: HTTP 요청에 사용되는 프록시 서버의 호스트 이름 또는 IP 주소입니다.
• HTTPS_PROXY: HTTPS 요청에 사용되는 프록시 서버의 호스트 이름 또는 IP 주소입니다.
• ALL_PROXY: HTTP 및 HTTPS 요청에 사용되는 프록시 서버의 호스트 이름 또는 HTTPS_PROXY IP 주소입니다(예: 정의되지 않은 경우HTTP_PROXY).
• NO_PROXY: 프록시에서 제외해야 하는 쉼표로 구분된 호스트 이름 목록입니다.

PowerShell 7.4는 Brotli 압축 알고리즘에 대한 지원을 추가했습니다.

관련 링크

• Invoke-RestMethod
• ConvertFrom-Json
• ConvertTo-Json