이제 Chrome은 표준화된 browser.* 네임스페이스를 지원합니다 (Chrome 148부터 사용 가능). 문서를 점진적으로 업데이트하고 있습니다. 자세한 내용은 전환 가이드를 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

browser.webRequest

설명

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

권한

webRequest

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

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

webRequestBlocking

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

webRequestAuthProvider

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

개념 및 사용

요청의 수명 주기

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

성공적인 요청의 이벤트 수명 주기는 여기에 나와 있으며, 이벤트 정의는 다음과 같습니다.

webrequest 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
If-Range
Partial-Data
Pragma
Proxy-Authorization
Proxy-Connection
Transfer-Encoding

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

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

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

출발지

참고: Origin 요청 헤더를 수정하면 의도한 대로 작동하지 않을 수 있으며 응답의 CORS 확인에서 예기치 않은 오류가 발생할 수 있습니다. 확장 프로그램은 Origin 요청 헤더만 수정할 수 있지만 요청을 시작한 사용자를 나타내기 위해 가져오기 사양에 정의된 개념인 request origin 또는 이니시에이터는 변경할 수 없기 때문입니다. 이러한 시나리오에서 서버는 수정된 요청에 대한 CORS 액세스를 허용하고 헤더의 Origin를 응답의 Access-Control-Allow-Origin 헤더에 넣을 수 있습니다. 하지만 변경 불가능한 request origin와 일치하지 않으므로 CORS 오류가 발생합니다.

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

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

Accept-Language
Accept-Encoding
리퍼러
쿠키

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

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

참고: opt_extraInfoSpec에서 'extraHeaders'을 지정하면 성능에 부정적인 영향을 미칠 수 있으므로 정말 필요한 경우에만 사용해야 합니다.

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, 브라우저 기능의 핵심인 기타 민감한 요청이 포함됩니다. 또한 확장 프로그램의 동기 XMLHttpRequests는 교착 상태를 방지하기 위해 차단 이벤트 핸들러에서 숨겨집니다. 지원되는 일부 스키마의 경우 해당 프로토콜의 특성으로 인해 사용 가능한 이벤트 집합이 제한될 수 있습니다. 예를 들어 파일 스킴의 경우 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 이벤트를 수신하는 예입니다.

browser.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" 권한이 있는 정책 설치 확장 프로그램에는 이 권한이 필요하지 않습니다.

사용자 인증 정보를 동기식으로 제공하려면 다음을 실행하세요.

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

사용자 인증 정보를 비동기식으로 제공하려면 다음을 실행하세요.

browser.webRequest 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

설명

권한

개념 및 사용

요청의 수명 주기

요청 ID

이벤트 리스너 등록

인증 처리

browser.webRequest