chrome.webRequest

설명

chrome.webRequest API를 사용하여 트래픽을 관찰 및 분석하고 진행 중인 요청을 가로채거나 차단하거나 수정합니다.

권한

webRequest

필요한 호스트 권한과 함께 웹 요청 API를 사용하려면 확장 프로그램 매니페스트에서 "webRequest" 권한을 선언해야 합니다. 하위 리소스 요청을 가로채려면 확장 프로그램에서 요청된 URL과 시작자 모두에 액세스할 수 있어야 합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

차단 이벤트 핸들러를 등록하는 데 필요합니다. Manifest V3부터는 정책에 설치된 확장 프로그램에서만 사용할 수 있습니다.

webRequestAuthProvider

onAuthRequired 메서드를 사용하는 데 필요합니다. 인증 처리를 참고하세요.

개념 및 사용법

요청 수명 주기

웹 요청 API는 웹 요청의 수명 주기를 따르는 이벤트 집합을 정의합니다. 이러한 이벤트를 사용하여 트래픽을 관찰하고 분석할 수 있습니다. 특정 동기 이벤트를 사용하면 요청을 가로채거나 차단하거나 수정할 수 있습니다.

다음은 성공적인 요청의 이벤트 수명 주기와 이벤트 정의입니다.

웹 요청 API의 관점에서 본 웹 요청의 수명 주기

onBeforeRequest (선택적으로 동기식)
요청이 발생하기 직전에 실행됩니다. 이 이벤트는 TCP 연결이 이루어지기 전에 전송되며 요청을 취소하거나 리디렉션하는 데 사용할 수 있습니다.
onBeforeSendHeaders (선택적으로 동기식)
요청이 발생하기 직전에 초기 헤더가 준비되면 실행됩니다. 이 이벤트는 확장 프로그램에서 요청 헤더(*)를 추가, 수정, 삭제할 수 있도록 하기 위한 것입니다. onBeforeSendHeaders 이벤트가 모든 구독자에게 전달되므로 서로 다른 구독자가 요청을 수정하려고 할 수 있습니다. 처리 방법은 구현 세부정보 섹션을 참조하세요. 이 이벤트를 사용하여 요청을 취소할 수 있습니다.
onSendHeaders
모든 확장 프로그램이 요청 헤더를 수정한 후 실행되고 최종 (*) 버전을 표시합니다. 이 이벤트는 헤더가 네트워크로 전송되기 전에 트리거됩니다. 이 이벤트는 정보를 제공하며 비동기식으로 처리됩니다. 요청 수정 또는 취소는 허용되지 않습니다.
onHeadersReceived (선택적으로 동기식)
HTTP(S) 응답 헤더가 수신될 때마다 실행됩니다. 리디렉션 및 인증 요청으로 인해 요청당 여러 번 발생할 수 있습니다. 이 이벤트는 확장 프로그램이 수신 Content-Type 헤더와 같은 응답 헤더를 추가, 수정, 삭제할 수 있도록 하기 위한 것입니다. 캐싱 지시문은 이 이벤트가 트리거되기 전에 처리되므로 Cache-Control과 같은 헤더를 수정해도 브라우저 캐시에 영향을 미치지 않습니다. 또한 요청을 취소하거나 리디렉션할 수도 있습니다.
onAuthRequired (선택적으로 동기식)
요청에 사용자 인증이 필요한 경우 실행됩니다. 이 이벤트는 동기식으로 처리되어 사용자 인증 정보를 제공할 수 있습니다. 확장 프로그램에서 잘못된 사용자 인증 정보를 제공할 수도 있습니다. 잘못된 사용자 인증 정보를 반복적으로 제공하여 무한 루프에 빠지지 않도록 주의하세요. 요청을 취소하는 데도 사용할 수 있습니다.
onBeforeRedirect
리디렉션이 실행되려고 하면 실행됩니다. 리디렉션은 HTTP 응답 코드 또는 확장 프로그램에 의해 트리거될 수 있습니다. 이 이벤트는 정보를 제공하며 비동기식으로 처리됩니다. 개발자가 요청을 수정하거나 취소할 수는 없습니다.
onResponseStarted
응답 본문의 첫 번째 바이트가 수신되면 실행됩니다. HTTP 요청의 경우 상태 줄과 응답 헤더를 사용할 수 있습니다. 이 이벤트는 정보를 제공하며 비동기식으로 처리됩니다. 요청 수정 또는 취소는 허용되지 않습니다.
onCompleted
요청이 성공적으로 처리되면 실행됩니다.
onErrorOccurred
요청을 성공적으로 처리할 수 없는 경우 실행됩니다.

웹 요청 API는 각 요청에서 onCompleted 또는 onErrorOccurred가 최종 이벤트로 실행되도록 보장합니다. 단, 한 가지 예외가 있습니다. 요청이 data:// URL로 리디렉션되는 경우 onBeforeRedirect가 마지막으로 보고된 이벤트입니다.

* 웹 요청 API는 확장 프로그램에 네트워크 스택의 추상화를 제공합니다. 내부적으로 하나의 URL 요청을 여러 HTTP 요청으로 분할하거나 (예: 대용량 파일에서 개별 바이트 범위 가져오기) 네트워크와 통신하지 않고 네트워크 스택에서 처리할 수 있습니다. 따라서 API는 네트워크로 전송되는 최종 HTTP 헤더를 제공하지 않습니다. 예를 들어 캐싱과 관련된 모든 헤더는 확장 프로그램에 표시되지 않습니다.

다음 헤더는 현재 onBeforeSendHeaders 이벤트에 제공되지 않습니다. 이 목록은 완전하거나 안정적이지 않을 수 있습니다.

  • 승인
  • Cache-Control
  • 연대감
  • Content-Length
  • 호스트
  • If-Modified-Since
  • If-None-Match
  • 조건: 범위
  • 부분 데이터
  • 프라그마
  • 프록시 승인
  • 프록시-연결
  • 전송 인코딩

Chrome 79부터는 요청 헤더 수정이 교차 출처 리소스 공유 (CORS) 검사에 영향을 미칩니다. 교차 출처 요청의 수정된 헤더가 기준을 충족하지 않으면 CORS 프리플라이트가 전송되어 해당 헤더를 수락할 수 있는지 서버에 요청합니다. CORS 프로토콜을 위반하도록 헤더를 수정해야 한다면 opt_extraInfoSpec에 'extraHeaders'를 지정해야 합니다. 반면에 응답 헤더를 수정한다고 해서 CORS 검사를 기만할 수는 없습니다. CORS 프로토콜을 속이려는 경우에는 응답 수정에 'extraHeaders'도 지정해야 합니다.

Chrome 79부터는 webRequest API가 기본적으로 CORS 실행 전 요청 및 응답을 가로채지 않습니다. 요청 URL의 CORS 프리플라이트는 요청 URL에 대해 opt_extraInfoSpec에 지정된 'extraHeaders'가 있는 리스너가 있는 경우 확장 프로그램에 표시됩니다. 또한 onBeforeRequest은 Chrome 79에서 'extraHeaders'를 사용할 수 있습니다.

Chrome 79부터는 다음 요청 헤더가 제공되지 않으며 opt_extraInfoSpec에 'extraHeaders'를 지정하지 않으면 수정하거나 삭제할 수 없습니다.

  • 출발지

Chrome 72부터 교차 출처 읽기 차단(CORB)으로 응답을 차단하기 전에 응답을 수정해야 하는 경우 opt_extraInfoSpec에 'extraHeaders'를 지정해야 합니다.

Chrome 72부터는 다음 요청 헤더가 제공되지 않으며 opt_extraInfoSpec에 'extraHeaders'를 지정하지 않으면 수정하거나 삭제할 수 없습니다.

  • 수락-언어
  • Accept-Encoding
  • 리퍼러
  • 쿠키

Chrome 72부터는 Set-Cookie 응답 헤더가 제공되지 않으며 opt_extraInfoSpec에 'extraHeaders'를 지정하지 않으면 수정하거나 삭제할 수 없습니다.

Chrome 89부터는 opt_extraInfoSpec에 'extraHeaders'를 지정하지 않으면 X-Frame-Options 응답 헤더를 효과적으로 수정하거나 삭제할 수 없습니다.

webRequest API는 호스트 권한에 따라 확장 프로그램에 보기 권한이 있는 요청만 노출합니다. 또한 http://, https://, ftp://, file://, ws:// (Chrome 58부터), wss:// (Chrome 58부터), urn: (Chrome 91부터) 또는 chrome-extension://에만 액세스할 수 있습니다. 또한 위의 스키마 중 하나를 사용하는 URL이 포함된 특정 요청도 숨겨집니다. 여기에는 other_extension_id가 요청을 처리하기 위한 확장 프로그램의 ID가 아닌 chrome-extension://other_extension_id, https://www.google.com/chrome, 브라우저 기능의 핵심인 기타 민감한 요청이 포함됩니다. 또한 교착 상태를 방지하기 위해 확장 프로그램의 동기식 XMLHttpRequest가 이벤트 핸들러 차단에서 숨겨집니다. 지원되는 스키마 중 일부의 경우 해당 프로토콜의 특성으로 인해 사용 가능한 이벤트 세트가 제한될 수 있습니다. 예를 들어 file: 스키마의 경우 onBeforeRequest, onResponseStarted, onCompleted, onErrorOccurred만 전달될 수 있습니다.

Chrome 58부터 webRequest API는 WebSocket 핸드셰이크 요청 가로채기를 지원합니다. 핸드셰이크는 HTTP 업그레이드 요청을 통해 이루어지므로 흐름은 HTTP 지향 webRequest 모델에 적합합니다. API는 다음을 가리지 않습니다.

  • 설정된 WebSocket 연결을 통해 전송되는 개별 메시지
  • WebSocket이 연결을 닫는 중입니다.

WebSocket 요청에는 리디렉션이 지원되지 않습니다.

Chrome 72부터 확장 프로그램은 요청된 URL과 요청 개시자 모두에 대한 호스트 권한이 있는 경우에만 요청을 가로챌 수 있습니다.

Chrome 96부터 webRequest API는 HTTP/3 핸드셰이크 요청을 통한 WebTransport 가로채기를 지원합니다. 핸드셰이크는 HTTP CONNECT 요청을 통해 수행되므로 해당 흐름은 HTTP 지향 webRequest 모델에 적합합니다. 참고:

  • 세션이 설정되면 확장 프로그램이 webRequest API를 통해 세션을 관찰하거나 여기에 개입할 수 없습니다.
  • onBeforeSendHeaders에서 HTTP 요청 헤더 수정은 무시됩니다.
  • HTTP/3을 통한 WebTransport에서는 리디렉션과 인증이 지원되지 않습니다.

요청 ID

각 요청은 요청 ID로 식별됩니다. 이 ID는 브라우저 세션 및 확장 프로그램의 컨텍스트 내에서 고유합니다. 요청 수명 주기 동안 일정하게 유지되며 동일한 요청의 이벤트를 일치시키는 데 사용할 수 있습니다. HTTP 리디렉션 또는 HTTP 인증의 경우 여러 HTTP 요청이 하나의 웹 요청에 매핑됩니다.

이벤트 리스너 등록

웹 요청에 이벤트 리스너를 등록하려면 일반적인 addListener() 함수의 변형을 사용합니다. 콜백 함수를 지정하는 것 외에 필터 인수를 지정해야 하며, 선택적 추가 정보 인수를 지정할 수도 있습니다.

웹 요청 API의 addListener()에 대한 세 가지 인수의 정의는 다음과 같습니다.

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

다음은 onBeforeRequest 이벤트를 수신하는 예입니다.

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

각 addListener() 호출은 필수 콜백 함수를 첫 번째 매개변수로 사용합니다. 이 콜백 함수에는 현재 URL 요청에 대한 정보가 포함된 사전이 전달됩니다. 이 사전의 정보는 특정 이벤트 유형과 opt_extraInfoSpec의 콘텐츠에 따라 달라집니다.

선택사항인 opt_extraInfoSpec 배열에 'blocking' 문자열 (특정 이벤트에만 허용됨)이 포함된 경우 콜백 함수는 동기식으로 처리됩니다. 즉, 콜백 함수가 반환될 때까지 요청이 차단됩니다. 이 경우 콜백은 요청의 추가 수명 주기를 결정하는 webRequest.BlockingResponse를 반환할 수 있습니다. 컨텍스트에 따라 이 응답을 통해 요청 취소 또는 리디렉션 (onBeforeRequest), 요청 취소 또는 헤더 수정 (onBeforeSendHeaders, onHeadersReceived), 요청 취소 또는 사용자 인증 정보 제공 (onAuthRequired)이 가능합니다.

선택사항인 opt_extraInfoSpec 배열에 'asyncBlocking' 문자열 (onAuthRequired에만 허용됨)이 포함된 경우 확장 프로그램은 webRequest.BlockingResponse를 비동기식으로 생성할 수 있습니다.

webRequest.RequestFilter filter를 사용하면 다양한 측정기준에서 트리거되는 이벤트에 대한 요청을 제한할 수 있습니다.

URL
URL 패턴(예: *://www.google.com/foo*bar).
유형
main_frame (최상위 프레임에 로드되는 문서), sub_frame (삽입된 프레임용으로 로드된 문서), image (웹사이트의 이미지)과 같은 요청 유형입니다. webRequest.RequestFilter를 참고하세요.
탭 ID
탭 하나의 식별자입니다.
창 ID
창의 식별자입니다.

이벤트 유형에 따라 opt_extraInfoSpec에 문자열을 지정하여 요청에 대한 추가 정보를 요청할 수 있습니다. 명시적으로 요청된 경우에만 요청 데이터에 대한 자세한 정보를 제공하는 데 사용됩니다.

인증 처리

HTTP 인증 요청을 처리하려면 매니페스트 파일에 "webRequestAuthProvider" 권한을 추가합니다.

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

"webRequestBlocking" 권한이 있는 정책 설치 확장 프로그램에는 이 권한이 필요하지 않습니다.

사용자 인증 정보를 동기식으로 제공하려면 다음 안내를 따르세요.

chrome.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

사용자 인증 정보를 비동기식으로 제공하려면 다음 안내를 따르세요.

chrome.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

구현 세부정보

웹 요청 API를 사용하는 확장 프로그램을 개발할 때는 몇 가지 구현 세부정보를 이해해야 합니다.

web_accessible_resources

확장 프로그램이 webRequest API를 사용하여 공개 리소스 요청을 웹에서 액세스할 수 없는 리소스로 리디렉션하는 경우 차단되고 오류가 발생합니다. 리디렉션 확장 프로그램에서 웹에 액세스할 수 없는 리소스를 소유한 경우에도 위의 내용이 적용됩니다. declarativeWebRequest API와 함께 사용할 리소스를 선언하려면 여기에 설명된 대로 매니페스트에 "web_accessible_resources" 배열을 선언하고 채워야 합니다.

충돌 해결

웹 요청 API의 현재 구현에서 하나 이상의 확장 프로그램이 요청을 취소하도록 지시하면 요청이 취소된 것으로 간주됩니다. 확장 프로그램이 요청을 취소하면 onErrorOccurred 이벤트를 통해 모든 확장 프로그램에 알림이 전송됩니다. 한 번에 하나의 확장 프로그램만 요청을 리디렉션하거나 헤더를 수정할 수 있습니다. 둘 이상의 확장 프로그램이 요청을 수정하려고 시도하면 가장 최근에 설치된 확장 프로그램이 우선 적용되며 다른 확장 프로그램은 모두 무시됩니다. 수정 또는 리디렉션 명령이 무시되면 확장 프로그램에 알림이 전송되지 않습니다.

캐싱

Chrome은 디스크 상의 캐시와 매우 빠른 인메모리 캐시, 이렇게 두 가지 캐시를 사용합니다. 메모리 내 캐시의 전체 기간은 렌더링 프로세스의 전체 기간에 연결되며, 이는 대략 탭에 해당합니다. 메모리 내 캐시에서 응답한 요청은 웹 요청 API에 표시되지 않습니다. 요청 핸들러가 동작을 변경하면 (예: 요청이 차단된 동작) 간단한 페이지 새로고침은 이렇게 변경된 동작을 따르지 않을 수 있습니다. 동작 변경사항이 적용되도록 하려면 handlerBehaviorChanged()를 호출하여 메모리 내 캐시를 플러시합니다. 하지만 자주 실행하지 마세요. 캐시를 삭제하는 작업은 비용이 매우 많이 드는 작업입니다. 이벤트 리스너를 등록하거나 등록 취소한 후에는 handlerBehaviorChanged()를 호출할 필요가 없습니다.

타임스탬프

웹 요청 이벤트의 timestamp 속성은 내부적으로 일관성만 보장됩니다. 한 이벤트를 다른 이벤트와 비교하면 이벤트 간의 올바른 오프셋을 얻을 수 있지만 (new Date()).getTime() 등을 통해 확장 프로그램 내의 현재 시간과 비교하면 예기치 않은 결과가 발생할 수 있습니다.

오류 처리

잘못된 인수가 있는 이벤트를 등록하려고 하면 자바스크립트 오류가 발생하고 이벤트 핸들러가 등록되지 않습니다. 이벤트를 처리하는 동안 오류가 발생하거나 이벤트 핸들러가 잘못된 차단 응답을 반환하면 오류 메시지가 확장 프로그램 콘솔에 로깅되고 핸들러는 해당 요청에 대해 무시됩니다.

예

다음 예는 www.evil.com에 대한 모든 요청을 차단하는 방법을 보여줍니다.

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

이 함수는 차단 이벤트 핸들러를 사용하므로 매니페스트 파일에 "webRequest" 및 "webRequestBlocking" 권한이 필요합니다.

다음 예시에서는 www.evil.com을 타겟팅하지 않는 요청을 확장 프로그램에 전달할 필요가 없으므로 더 효율적인 방식으로 동일한 목표를 달성합니다.

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

다음 예는 모든 요청에서 User-Agent 헤더를 삭제하는 방법을 보여줍니다.

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

chrome.webRequest API를 사용해 보려면 chrome-extension-samples 저장소의 webRequest 샘플을 설치하세요.

유형

BlockingResponse

'차단' extraInfoSpec이 적용된 이벤트 핸들러의 값을 반환합니다. 이벤트 핸들러가 네트워크 요청을 수정할 수 있도록 합니다.

속성

  • authCredentials

    객체 선택사항

    onAuthRequired 이벤트에 대한 응답으로만 사용됩니다. 설정된 경우 제공된 사용자 인증 정보를 사용하여 요청이 이루어집니다.

    • 비밀번호

      string

    • 사용자이름

      string

  • 취소

    부울 선택사항

    true인 경우 요청이 취소됩니다. 이렇게 하면 요청이 전송되지 않습니다. onBeforeRequest, onBeforeSendHeaders, onHeadersReceived 및 onAuthRequired 이벤트에 대한 응답으로 사용할 수 있습니다.

  • redirectUrl

    문자열 선택사항

    onBeforeRequest 및 onHeadersReceived 이벤트에 대한 응답으로만 사용됩니다. 설정된 경우 원래 요청이 전송/완료되지 않고 지정된 URL로 리디렉션됩니다. data:와 같은 HTTP가 아닌 스키마로의 리디렉션은 허용됩니다. 리디렉션 작업에 의해 시작된 리디렉션은 리디렉션에 원래 요청 메서드를 사용합니다. 단, 리디렉션이 onHeadersReceived 단계에서 시작되면 리디렉션은 GET 메서드를 사용하여 실행됩니다. ws:// 및 wss:// 스키마가 포함된 URL의 리디렉션은 무시됩니다.

  • requestHeaders

    HttpHeaders 선택사항

    onBeforeSendHeaders 이벤트에 대한 응답으로만 사용됩니다. 설정된 경우 대신 이러한 요청 헤더를 사용하여 요청이 이루어집니다.

  • responseHeaders

    HttpHeaders 선택사항

    onHeadersReceived 이벤트에 대한 응답으로만 사용됩니다. 설정된 경우 서버가 대신 이러한 응답 헤더로 응답한 것으로 간주됩니다. 충돌 수를 제한하기 위해 헤더를 정말로 수정하려는 경우에만 responseHeaders를 반환합니다 (하나의 확장 프로그램만 각 요청에 대해 responseHeaders를 수정할 수 있음).

FormDataItem

Chrome 66 이상

양식 데이터 내에 전달된 데이터가 포함됩니다. URL 인코딩된 형식의 경우 데이터가 utf-8 문자열이면 문자열로 저장되고 그렇지 않으면 ArrayBuffer로 저장됩니다. 양식 데이터의 경우 ArrayBuffer입니다. form-data가 파일 업로드를 나타내는 경우 파일 이름이 제공된 경우 파일 이름이 포함된 문자열입니다.

열거형

ArrayBuffer

string

HttpHeaders

HTTP 헤더의 배열입니다. 각 헤더는 name 키와 value 또는 binaryValue 키를 포함하는 사전으로 표현됩니다.

유형

객체[]

속성

  • binaryValue

    number[] 선택사항

    UTF-8로 표현할 수 없는 경우 HTTP 헤더의 값으로, 개별 바이트 값 (0..255)으로 저장됩니다.

  • 이름

    string

    HTTP 헤더의 이름입니다.

  • 값

    문자열 선택사항

    UTF-8로 표시할 수 있는 경우 HTTP 헤더의 값입니다.

IgnoredActionType

Chrome 70 이상

열거형

"auth_credentials"

OnAuthRequiredOptions

Chrome 44 이상

열거형

"responseHeaders"
응답 헤더가 이벤트에 포함되어야 함을 지정합니다.

"blocking"
콜백 함수가 반환될 때까지 요청이 차단되도록 지정합니다.

"asyncBlocking"
콜백 함수가 비동기식으로 처리되도록 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnBeforeRedirectOptions

Chrome 44 이상

열거형

"responseHeaders"
응답 헤더가 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnBeforeRequestOptions

Chrome 44 이상

열거형

"blocking"
콜백 함수가 반환될 때까지 요청이 차단되도록 지정합니다.

"requestBody"
요청 본문이 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnBeforeSendHeadersOptions

Chrome 44 이상

열거형

"requestHeaders"
요청 헤더가 이벤트에 포함되어야 함을 지정합니다.

"blocking"
콜백 함수가 반환될 때까지 요청이 차단되도록 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnCompletedOptions

Chrome 44 이상

열거형

"responseHeaders"
응답 헤더가 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnErrorOccurredOptions

Chrome 79 이상

값

"extraHeaders"

OnHeadersReceivedOptions

Chrome 44 이상

열거형

"blocking"
콜백 함수가 반환될 때까지 요청이 차단되도록 지정합니다.

"responseHeaders"
응답 헤더가 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnResponseStartedOptions

Chrome 44 이상

열거형

"responseHeaders"
응답 헤더가 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

OnSendHeadersOptions

Chrome 44 이상

열거형

"requestHeaders"
요청 헤더가 이벤트에 포함되어야 함을 지정합니다.

"extraHeaders"
헤더가 교차 출처 리소스 공유 (CORS)를 위반할 수 있음을 지정합니다.

RequestFilter

webRequest 이벤트에 적용할 필터를 설명하는 객체입니다.

속성

  • tabId

    number 선택사항

  • 유형

    ResourceType[] 선택사항

    요청 유형 목록입니다. 어떤 유형과도 일치하지 않는 요청은 필터링됩니다.

  • urls

    문자열[]

    URL 또는 URL 패턴의 목록입니다. 어떤 URL과도 일치하지 않는 요청은 필터링됩니다.

  • windowId

    number 선택사항

ResourceType

Chrome 44 이상

열거형

"main_frame"
리소스를 기본 프레임으로 지정합니다.

"sub_frame"
리소스를 하위 프레임으로 지정합니다.

"stylesheet"
리소스를 스타일시트로 지정합니다.

"script"
리소스를 스크립트로 지정합니다.

"image"
리소스를 이미지로 지정합니다.

"font"
리소스를 글꼴로 지정합니다.

"object"
리소스를 객체로 지정합니다.

"xmlhttprequest"
리소스를 XMLHttpRequest로 지정합니다.

"ping"
리소스를 핑으로 지정합니다.

"csp_report"
리소스를 콘텐츠 보안 정책 (CSP) 보고서로 지정합니다.

"media"
리소스를 미디어 객체로 지정합니다.

"websocket"
리소스를 WebSocket으로 지정합니다.

"webbundle"
리소스를 WebBundle로 지정합니다.

"other"
리소스를 나열된 유형에 포함되지 않은 유형으로 지정합니다.

UploadData

URL 요청에 업로드된 데이터가 포함됩니다.

속성

  • 바이트

    모든 선택사항

    데이터 사본이 있는 ArrayBuffer입니다.

  • 파일

    문자열 선택사항

    파일 경로 및 이름이 포함된 문자열입니다.

속성

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

10분 지속 간격당 handlerBehaviorChanged를 호출할 수 있는 최대 횟수입니다. handlerBehaviorChanged는 비용이 많이 드는 함수 호출로, 자주 호출하면 안 됩니다.

값

20

방법

handlerBehaviorChanged()

프로미스 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
)

캐싱으로 인한 잘못된 처리를 방지하기 위해 webRequest 핸들러의 동작이 변경되면 호출해야 합니다. 이 함수 호출은 비용이 많이 듭니다. 자주 전화하지 마세요.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    ()=>void

반환 값

  • Promise<void>

    Chrome 116 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onActionIgnored

Chrome 70 이상 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

네트워크 요청에 대해 확장 프로그램에서 제안한 수정이 무시되면 실행됩니다. 이는 다른 확장 프로그램과 충돌하는 경우 발생합니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • 제안된 액션에서 무시되었습니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

인증 실패가 수신되면 시작됩니다. 리스너에는 사용자 인증 정보를 제공하거나, 요청을 취소하고 오류 페이지를 표시하거나, 챌린지에 대해 아무 조치도 취하지 않을 수 있는 세 가지 옵션이 있습니다. 잘못된 사용자 인증 정보가 제공되면 동일한 요청에 대해 여러 번 호출될 수 있습니다. extraInfoSpec 매개변수에 'blocking' 또는 'asyncBlocking' 모드 중 하나만 지정해야 합니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object,asyncCallback?: function)=>BlockingResponse|undefined

    • 세부정보

      객체

      • 챌린저

        객체

        인증을 요청하는 서버입니다.

        • 호스트

          string

        • 포트

          숫자

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • isProxy

        boolean

        프록시 인증은 true이고, WWW-인증은 false입니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • 렐름

        문자열 선택사항

        서버에서 제공하는 인증 영역입니다(있는 경우).

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • responseHeaders

        HttpHeaders 선택사항

        이 응답과 함께 수신된 HTTP 응답 헤더입니다.

      • scheme

        string

        인증 스키마입니다(예: Basic 또는 Digest).

      • statusCode

        숫자

        Chrome 43 이상

        서버에서 반환하는 표준 HTTP 상태 코드입니다.

      • statusLine

        string

        응답의 HTTP 상태 줄 또는 HTTP/0.9 응답 (즉, 상태 행이 없는 응답)의 경우 'HTTP/0.9 200 OK' 문자열 또는 헤더가 없는 경우 빈 문자열입니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

    • asyncCallback

      함수 선택사항

      Chrome 58 이상

      asyncCallback 매개변수는 다음과 같습니다. 

      (response: BlockingResponse)=>void

    • returns

      BlockingResponse|undefined

      'extraInfoSpec' 매개변수에 'blocking'이 지정된 경우 이벤트 리스너는 이 유형의 객체를 반환해야 합니다.

  • filter

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] 선택사항

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

서버에서 시작된 리디렉션이 발생하려고 하면 실행됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • fromCache

        boolean

        이 응답을 디스크 캐시에서 가져왔는지 여부를 나타냅니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • ip

        문자열 선택사항

        요청이 실제로 전송된 서버 IP 주소입니다. 리터럴 IPv6 주소일 수도 있습니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • redirectUrl

        string

        새 URL입니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • responseHeaders

        HttpHeaders 선택사항

        이 리디렉션과 함께 수신된 HTTP 응답 헤더입니다.

      • statusCode

        숫자

        서버에서 반환하는 표준 HTTP 상태 코드입니다.

      • statusLine

        string

        응답의 HTTP 상태 줄 또는 HTTP/0.9 응답 (즉, 상태 행이 없는 응답)의 경우 'HTTP/0.9 200 OK' 문자열 또는 헤더가 없는 경우 빈 문자열입니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] 선택사항

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

요청이 발생하려고 할 때 시작됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>BlockingResponse|undefined

    • 세부정보

      객체

      • documentId

        문자열 선택사항

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • documentLifecycle

        extensionTypes.DocumentLifecycle 선택사항

        Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • frameType

        extensionTypes.FrameType 선택사항

        Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestBody

        객체 선택사항

        HTTP 요청 본문 데이터를 포함합니다. extraInfoSpec에 'requestBody'가 포함된 경우에만 제공됩니다.

        • error

          문자열 선택사항

          요청 본문 데이터를 가져오는 중에 오류가 발생했습니다.

        • formData

          객체 선택사항

          요청 메서드가 POST이고 본문이 multipart/form-data 또는 application/x-www-form-urlencoded로 인코딩된 UTF8로 인코딩된 키-값 쌍의 시퀀스인 경우 이 사전이 존재하며 각 키에 대한 모든 값의 목록이 포함됩니다. 데이터가 다른 미디어 유형이거나 형식이 잘못된 경우 사전이 표시되지 않습니다. 이 사전의 예제 값은 {'key': ['value1', 'value2']}입니다.

        • 원시 데이터

          UploadData[] 선택사항

          요청 메서드가 PUT 또는 POST이고 본문이 formData에서 아직 파싱되지 않은 경우에는 파싱되지 않은 요청 본문 요소가 이 배열에 포함됩니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

    • returns

      BlockingResponse|undefined

      'extraInfoSpec' 매개변수에 'blocking'이 지정된 경우 이벤트 리스너는 이 유형의 객체를 반환해야 합니다.

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] 선택사항

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

요청 헤더를 사용할 수 있게 되면 HTTP 요청을 전송하기 전에 실행됩니다. 이는 서버에 TCP 연결이 설정된 후 HTTP 데이터가 전송되기 전에 발생할 수 있습니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>BlockingResponse|undefined

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestHeaders

        HttpHeaders 선택사항

        이 요청과 함께 전송될 HTTP 요청 헤더입니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

    • returns

      BlockingResponse|undefined

      'extraInfoSpec' 매개변수에 'blocking'이 지정된 경우 이벤트 리스너는 이 유형의 객체를 반환해야 합니다.

  • filter

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] 선택사항

onCompleted

chrome.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

요청이 완료되면 시작됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • fromCache

        boolean

        이 응답을 디스크 캐시에서 가져왔는지 여부를 나타냅니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • ip

        문자열 선택사항

        요청이 실제로 전송된 서버 IP 주소입니다. 리터럴 IPv6 주소일 수도 있습니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • responseHeaders

        HttpHeaders 선택사항

        이 응답과 함께 수신된 HTTP 응답 헤더입니다.

      • statusCode

        숫자

        서버에서 반환하는 표준 HTTP 상태 코드입니다.

      • statusLine

        string

        응답의 HTTP 상태 줄 또는 HTTP/0.9 응답 (즉, 상태 행이 없는 응답)의 경우 'HTTP/0.9 200 OK' 문자열 또는 헤더가 없는 경우 빈 문자열입니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] 선택사항

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

오류가 발생하면 시작됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다. 요청이 프레임 탐색인 경우 이 값은 표시되지 않습니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • error

        string

        오류 설명입니다. 이 문자열은 버전 간에 이전 버전과의 호환성을 보장하지 않습니다. 콘텐츠를 파싱하거나 기반으로 조치해서는 안 됩니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • fromCache

        boolean

        이 응답을 디스크 캐시에서 가져왔는지 여부를 나타냅니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • ip

        문자열 선택사항

        요청이 실제로 전송된 서버 IP 주소입니다. 리터럴 IPv6 주소일 수도 있습니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] 선택사항

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

요청의 HTTP 응답 헤더가 수신되면 실행됩니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>BlockingResponse|undefined

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • responseHeaders

        HttpHeaders 선택사항

        이 응답과 함께 수신된 HTTP 응답 헤더입니다.

      • statusCode

        숫자

        Chrome 43 이상

        서버에서 반환하는 표준 HTTP 상태 코드입니다.

      • statusLine

        string

        응답의 HTTP 상태 줄 또는 HTTP/0.9 응답 (즉, 상태 표시줄이 없는 응답)의 경우 'HTTP/0.9 200 OK' 문자열

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

    • returns

      BlockingResponse|undefined

      'extraInfoSpec' 매개변수에 'blocking'이 지정된 경우 이벤트 리스너는 이 유형의 객체를 반환해야 합니다.

  • filter

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] 선택사항

onResponseStarted

chrome.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

응답 본문의 첫 바이트가 수신되면 시작됩니다. HTTP 요청의 경우 상태 표시줄과 응답 헤더를 사용할 수 있다는 의미입니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • fromCache

        boolean

        이 응답을 디스크 캐시에서 가져왔는지 여부를 나타냅니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • ip

        문자열 선택사항

        요청이 실제로 전송된 서버 IP 주소입니다. 리터럴 IPv6 주소일 수도 있습니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • responseHeaders

        HttpHeaders 선택사항

        이 응답과 함께 수신된 HTTP 응답 헤더입니다.

      • statusCode

        숫자

        서버에서 반환하는 표준 HTTP 상태 코드입니다.

      • statusLine

        string

        응답의 HTTP 상태 줄 또는 HTTP/0.9 응답 (즉, 상태 행이 없는 응답)의 경우 'HTTP/0.9 200 OK' 문자열 또는 헤더가 없는 경우 빈 문자열입니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] 선택사항

onSendHeaders

chrome.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

요청이 서버로 전송되기 직전에 실행됩니다. 이전 onBeforeSendHeaders 콜백에 대한 수정사항은 onSendHeaders가 실행될 때까지 볼 수 있습니다.

매개변수

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (details: object)=>void

    • 세부정보

      객체

      • documentId

        string

        Chrome 106 이상

        요청을 실행하는 문서의 UUID입니다.

      • Chrome 106 이상

        문서가 속한 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 메인 프레임에서 발생함을 나타내고 양수 값은 요청이 발생한 서브프레임의 ID를 나타냅니다. 하위 프레임의 문서가 로드되면(type가 main_frame 또는 sub_frame) frameId는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • Chrome 106 이상

        요청이 발생한 프레임 유형입니다.

      • 개시자

        문자열 선택사항

        Chrome 63 이상

        요청이 시작된 출처입니다. 이는 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 문자열 'null'이 사용됩니다.

      • method

        string

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

        Chrome 106 이상

        이 프레임을 소유한 상위 문서의 UUID입니다. 상위 요소가 없는 경우에는 설정되지 않습니다.

      • parentFrameId

        숫자

        요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.

      • requestHeaders

        HttpHeaders 선택사항

        이 요청과 함께 전송된 HTTP 요청 헤더입니다.

      • requestId

        string

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 다양한 이벤트와 연관시키는 데 사용될 수 있습니다.

      • tabId

        숫자

        요청이 발생한 탭의 ID입니다. 요청이 탭과 관련되지 않은 경우 -1로 설정합니다.

      • timeStamp

        숫자

        이 신호가 트리거된 시간(에포크 이후 밀리초)입니다.

      • 유형

        ResourceType

        요청된 리소스가 사용되는 방식입니다.

      • url

        string

  • filter

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] 선택사항