Invoke-WebRequest

Invoke-WebRequest
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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
    [-Uri] <Uri>
    [-UseBasicParsing]
    [-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
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]
    [-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
    [-Uri] <Uri>
    -CustomMethod <String>
    [-UseBasicParsing]
    [-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>]
    [-PreserveHttpMethodOnRedirect]
    [-UnixSocket <UnixDomainSocketEndPoint>]
    [-NoProxy]
    [-Body <Object>]
    [-Form <IDictionary>]
    [-ContentType <String>]
    [-TransferEncoding <String>]
    [-InFile <String>]
    [-OutFile <String>]
    [-PassThru]
    [-Resume]
    [-SkipHttpErrorCheck]
    [<CommonParameters>]

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

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

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

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

이 예제에서는 Invoke-WebRequest cmdlet을 사용하여 웹 요청을 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 속성이 같은 "* Value" 가져옵니다. 필터링된 결과는 Select-Object 파이프되어 이름 및 값 속성을 선택합니다.

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

$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 첫 번째 호출은 로그인 요청을 보냅니다. 이 명령은 Session 매개 변수 값에 대한 값을 지정합니다. 명령이 완료되면 $LoginResponse 변수에 BasicHtmlWebResponseObject 포함되고 $Session 변수에는 WebRequestSession 개체가 포함됩니다. 그러면 사용자가 사이트에 기록됩니다.

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

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

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

이 예제에서는 Invoke-WebRequest cmdlet을 사용하여 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입니다.

이 예제에서는 Invoke-WebRequest cmdlet을 사용하여 파일을 multipart/form-data 제출로 업로드합니다. 파일 C:\document.txtdocumentContent-Typetext/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'

일부 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

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

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

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

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

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

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

Invoke-WebRequest cmdlet은 한 번에 하나의 파일만 다운로드할 수 있습니다. 다음 예제에서는 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
}

기본적으로 Invoke-WebRequest cmdlet은 표준 정의 값 형식이 있는 잘 알려진 헤더의 값의 유효성을 검사합니다. 다음 예제에서는 이 유효성 검사에서 오류를 발생시키는 방법과 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 호출하면 형식이 지정된 값이 잘못되었다는 오류 보고가 반환됩니다. 요청이 엔드포인트로 전송되지 않습니다.

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

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

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

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

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

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

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

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

PowerShell에는 Invoke-WebRequest에 대한 다음과 같은 별칭들이 포함되어 있습니다.

• 모든 플랫폼:
  • iwr

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

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

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

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

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

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

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

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