Skip to main content

Class: WebRequest

Class: WebRequest​

요청의 수명 주기 동안 다양한 단계에서 요청 내용을 가로채고 수정한다.

프로세스: Main
이 클래스는 'electron' 모듈에서 직접 내보내지 않는다. Electron API의 다른 메서드 반환값으로만 사용할 수 있다.

WebRequest 클래스의 인스턴스는 Session의 webRequest 속성을 통해 접근한다.

WebRequest의 메서드는 선택적 filter와 listener를 인자로 받는다. API 이벤트가 발생하면 listener(details) 형태로 리스너가 호출된다. details 객체는 요청을 설명한다.

⚠️ 마지막으로 부착된 리스너만 사용된다. listener에 null을 전달하면 이벤트 구독이 해제된다.

filter 객체는 urls 속성을 가지며, 이는 URL 패턴의 배열이다. 이 패턴에 맞지 않는 요청은 걸러진다. filter를 생략하면 모든 요청이 매칭된다.

특정 이벤트의 경우 리스너에 callback이 전달되며, 리스너가 작업을 마치면 response 객체와 함께 이 콜백을 호출해야 한다.

다음은 요청에 User-Agent 헤더를 추가하는 예제다:

const { session } = require('electron')

// 다음 URL에 대한 모든 요청의 사용자 에이전트를 수정한다.
const filter = {
  urls: ['https://*.github.com/*', '*://electron.github.io/*']
}

session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
  details.requestHeaders['User-Agent'] = 'MyAgent'
  callback({ requestHeaders: details.requestHeaders })
})

인스턴스 메서드​

WebRequest 인스턴스에서 사용할 수 있는 메서드는 다음과 같다:

webRequest.onBeforeRequest([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보내는 프레임. 프레임이 네비게이션을 수행하거나 파괴된 후에 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나가 될 수 있다.
      • referrer string
      • timestamp Double
      • uploadData UploadData[]
    • callback Function
      • response Object
        • cancel boolean (선택 사항)
        • redirectURL string (선택 사항) - 원래 요청이 전송되거나 완료되는 것을 막고, 대신 주어진 URL로 리다이렉트한다.

listener는 요청이 발생하기 직전에 listener(details, callback) 형식으로 호출된다.

uploadData는 UploadData 객체의 배열이다.

callback은 response 객체와 함께 호출해야 한다.

유효한 urls의 몇 가지 예제:

'http://foo:1234/'
'http://foo.com/'
'http://foo:1234/bar'
'*://*/*'
'*://example.com/*'
'*://example.com/foo/*'
'http://*.foo:1234/'
'file://foo:1234/bar'
'http://foo:*/'
'*://www.foo.com/'

webRequest.onBeforeSendHeaders([filter, ]listener)​

  • filter WebRequestFilter (옵션)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (옵션)
      • webContents WebContents (옵션)
      • frame WebFrameMain | null (옵션) - 요청을 보내는 프레임. 프레임이 네비게이션되거나 파괴된 후에 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나가 될 수 있다.
      • referrer string
      • timestamp Double
      • uploadData UploadData[] (옵션)
      • requestHeaders Record<string, string>
    • callback Function
      • beforeSendResponse Object
        • cancel boolean (옵션)
        • requestHeaders Record<string, string | string[]> (옵션) - 이 헤더를 제공하면 해당 헤더를 사용해 요청을 보낸다.

listener는 HTTP 요청을 보내기 전에, 요청 헤더가 준비되면 listener(details, callback) 형태로 호출된다. 이는 서버와 TCP 연결이 이루어진 후이지만, HTTP 데이터가 전송되기 전에 발생할 수 있다.

callback은 response 객체와 함께 호출해야 한다.

webRequest.onSendHeaders([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보내는 프레임. 프레임이 네비게이션을 완료하거나 파괴된 후에 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나의 값을 가질 수 있다.
      • referrer string
      • timestamp Double
      • requestHeaders Record<string, string>

listener는 요청이 서버로 전송되기 직전에 listener(details) 형식으로 호출된다. 이 시점에서는 이전 onBeforeSendHeaders 응답에서 수정한 내용이 반영되어 있다.

webRequest.onHeadersReceived([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보낸 프레임. 프레임이 네비게이션되거나 파괴된 후 접근하면 null일 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나일 수 있다.
      • referrer string
      • timestamp Double
      • statusLine string
      • statusCode Integer
      • responseHeaders Record<string, string[]> (선택 사항)
    • callback Function
      • headersReceivedResponse Object
        • cancel boolean (선택 사항)
        • responseHeaders Record<string, string | string[]> (선택 사항) - 이 값을 제공하면 서버가 이러한 헤더로 응답한 것으로 간주한다.
        • statusLine string (선택 사항) - responseHeaders를 재정의할 때 헤더 상태를 변경하려면 이 값을 제공해야 한다. 그렇지 않으면 원래 응답 헤더의 상태가 사용된다.

HTTP 요청의 응답 헤더를 받았을 때 listener(details, callback) 형태로 listener가 호출된다.

callback은 response 객체와 함께 호출해야 한다.

webRequest.onResponseStarted([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보낸 프레임. 프레임이 네비게이션을 했거나 파괴된 후에 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나일 수 있다.
      • referrer string
      • timestamp Double
      • responseHeaders Record<string, string[]> (선택 사항)
      • fromCache boolean - 응답이 디스크 캐시에서 가져온 것인지 여부를 나타낸다.
      • statusCode Integer
      • statusLine string

listener는 응답 본문의 첫 번째 바이트가 수신될 때 listener(details)로 호출된다. HTTP 요청의 경우, 이는 상태 라인과 응답 헤더가 사용 가능함을 의미한다.

webRequest.onBeforeRedirect([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보낸 프레임. 프레임이 이동하거나 삭제된 후 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나일 수 있다.
      • referrer string
      • timestamp Double
      • redirectURL string
      • statusCode Integer
      • statusLine string
      • ip string (선택 사항) - 요청이 실제로 전송된 서버의 IP 주소.
      • fromCache boolean
      • responseHeaders Record<string, string[]> (선택 사항)

서버가 리다이렉트를 시작하기 전에 listener가 listener(details) 형태로 호출된다.

webRequest.onCompleted([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보낸 프레임. 프레임이 네비게이션되거나 파괴된 후에 접근하면 null이 될 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket, other 중 하나가 될 수 있다.
      • referrer string
      • timestamp Double
      • responseHeaders Record<string, string[]> (선택 사항)
      • fromCache boolean
      • statusCode Integer
      • statusLine string
      • error string

요청이 완료되면 listener(details) 형태로 리스너가 호출된다.

webRequest.onErrorOccurred([filter, ]listener)​

  • filter WebRequestFilter (선택 사항)
  • listener Function | null
    • details Object
      • id Integer
      • url string
      • method string
      • webContentsId Integer (선택 사항)
      • webContents WebContents (선택 사항)
      • frame WebFrameMain | null (선택 사항) - 요청을 보낸 프레임. 프레임이 네비게이션되거나 파괴된 후 접근하면 null일 수 있다.
      • resourceType string - mainFrame, subFrame, stylesheet, script, image, font, object, xhr, ping, cspReport, media, webSocket 또는 other 중 하나일 수 있다.
      • referrer string
      • timestamp Double
      • fromCache boolean
      • error string - 오류 설명.

오류가 발생하면 listener가 listener(details) 형식으로 호출된다.