chrome.declarativeWebRequest

설명

참고: 이 API는 지원 중단되었습니다. 대신 declarativeNetRequest API를 확인하세요. chrome.declarativeWebRequest API를 사용하여 전송 중인 요청을 가로채거나 차단하거나 수정합니다. JavaScript 엔진이 아닌 브라우저에서 평가되는 규칙을 등록할 수 있으므로 chrome.webRequest API보다 훨씬 빠르며, 왕복 지연 시간을 줄이고 효율성을 높일 수 있습니다.

권한

declarativeWebRequest

이 API를 사용하려면 호스트 권한과 함께 확장 프로그램 매니페스트에 'declarativeWebRequest' 권한을 선언해야 합니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

가용성

베타 채널 ≤ MV2

매니페스트

특정 유형의 민감하지 않은 작업에는 호스트 권한이 필요하지 않습니다.

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

SendMessageToExtension() 작업에는 네트워크 요청에 메시지를 트리거하려는 호스트의 호스트 권한이 필요합니다.

그 외 모든 작업에는 모든 URL에 대한 호스트 권한이 필요합니다.

예를 들어 "https://*.google.com/*"이 확장 프로그램에 있는 유일한 호스트 권한인 경우 이러한 확장 프로그램은 다음을 수행하는 규칙을 설정할 수 있습니다.

  • https://www.google.com 또는 https://anything.else.com에 대한 요청을 취소합니다.
  • https://www.google.com로 이동할 때는 메시지를 보내지만 https://something.else.com로 이동할 때는 메시지를 보내지 않습니다.

확장 프로그램은 https://www.google.com을 https://mail.google.com로 리디렉션하는 규칙을 설정할 수 없습니다.

규칙

선언적 웹 요청 API는 선언적 API의 개념을 따릅니다. chrome.declarativeWebRequest.onRequest 이벤트 객체에 규칙을 등록할 수 있습니다.

선언적 웹 요청 API는 단일 유형의 일치 기준인 RequestMatcher를 지원합니다. RequestMatcher는 나열된 모든 기준이 충족되는 경우에만 네트워크 요청과 일치합니다. 다음 RequestMatcher은 사용자가 검색주소창에 https://www.example.com을 입력할 때 네트워크 요청과 일치합니다.

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

https://www.example.com에 대한 요청은 스키마로 인해 RequestMatcher에 의해 거부됩니다. 또한 resourceType로 인해 삽입된 iframe에 대한 모든 요청이 거부됩니다.

'example.com'에 대한 모든 요청을 취소하려면 다음과 같이 규칙을 정의하면 됩니다.

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

example.com 및 foobar.com에 대한 모든 요청을 취소하려면 각 조건이 지정된 모든 작업을 트리거하기에 충분하므로 두 번째 조건을 추가하면 됩니다.

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

다음과 같이 규칙을 등록합니다.

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

조건 및 작업 평가

선언적 웹 요청 API는 웹 요청 API의 웹 요청 수명 주기 모델을 따릅니다. 즉, 웹 요청의 특정 단계에서만 조건을 테스트할 수 있으며 마찬가지로 특정 단계에서만 작업을 실행할 수 있습니다. 다음 표에는 조건 및 작업과 호환되는 요청 단계가 나와 있습니다.

조건 속성을 처리할 수 있는 요청 단계입니다.
조건 속성 onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
작업을 실행할 수 있는 요청 단계입니다.
이벤트 onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

우선순위를 사용하여 규칙 재정의

Events API에 설명된 대로 규칙을 우선순위와 연결할 수 있습니다. 이 메커니즘은 예외를 표현하는 데 사용할 수 있습니다. 다음 예시에서는 'myserver.com' 서버를 제외한 evil.jpg라는 이미지에 대한 모든 요청을 차단합니다.

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

IgnoreRules 작업은 요청 단계에서 유지되지 않습니다. 웹 요청의 각 단계에서 모든 규칙의 모든 조건이 평가됩니다. IgnoreRules 작업이 실행되면 동일한 단계에서 동일한 웹 요청에 대해 실행되는 다른 작업에만 적용됩니다.

유형

AddRequestCookie

요청에 쿠키를 추가하거나 동일한 이름의 다른 쿠키가 이미 있는 경우 쿠키를 재정의합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

AddResponseCookie

응답에 쿠키를 추가하거나 동일한 이름의 다른 쿠키가 이미 있는 경우 쿠키를 재정의합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

AddResponseHeader

이 웹 요청의 응답에 응답 헤더를 추가합니다. 여러 응답 헤더가 동일한 이름을 공유할 수 있으므로 응답 헤더를 바꾸려면 먼저 삭제한 후 새 응답 헤더를 추가해야 합니다.

속성

CancelRequest

네트워크 요청을 취소하는 선언적 이벤트 작업입니다.

속성

EditRequestCookie

요청의 쿠키를 하나 이상 수정합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: EditRequestCookie) => {...}

  • filter

    RequestCookie

    수정될 쿠키를 필터링합니다. 빈 항목은 모두 무시됩니다.

  • 수정

    RequestCookie

    필터와 일치하는 쿠키에서 재정의해야 하는 속성입니다. 빈 문자열로 설정된 속성은 삭제됩니다.

EditResponseCookie

응답의 쿠키를 하나 이상 수정합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

FilterResponseCookie

HTTP 응답의 쿠키 필터입니다.

속성

  • ageLowerBound

    number(숫자) 선택사항

    쿠키 수명의 하한 (현재 시간 이후 초 단위로 지정)입니다. 만료일-시간이 'now + ageLowerBound' 이상으로 설정된 쿠키만 이 기준을 충족합니다. 세션 쿠키가 이 필터의 기준을 충족하지 않습니다. 쿠키 전체 기간은 'max-age' 또는 'expires' 쿠키 속성에서 계산됩니다. 둘 다 지정된 경우 'max-age'가 쿠키 수명을 계산하는 데 사용됩니다.

  • ageUpperBound

    number(숫자) 선택사항

    쿠키 수명의 상한 (현재 시간 이후 초 단위로 지정)입니다. 만료일이 [현재, 현재 + ageUpperBound] 간격에 있는 쿠키만 이 기준을 충족합니다. 세션 쿠키와 만료일-시간이 지난 쿠키는 이 필터의 기준을 충족하지 않습니다. 쿠키 전체 기간은 'max-age' 또는 'expires' 쿠키 속성에서 계산됩니다. 둘 다 지정된 경우 'max-age'가 쿠키 수명을 계산하는 데 사용됩니다.

  • 도메인

    문자열 선택사항

    도메인 쿠키 속성의 값입니다.

  • 만료일

    문자열 선택사항

    Expires 쿠키 속성의 값입니다.

  • httpOnly

    문자열 선택사항

    HttpOnly 쿠키 속성의 존재 여부

  • maxAge

    number(숫자) 선택사항

    Max-Age 쿠키 속성의 값

  • 이름

    문자열 선택사항

    쿠키의 이름입니다.

  • 경로

    문자열 선택사항

    경로 쿠키 속성의 값입니다.

  • 보안

    문자열 선택사항

    Secure 쿠키 속성의 존재 여부입니다.

  • sessionCookie

    불리언 선택사항

    세션 쿠키를 필터링합니다. 세션 쿠키에는 'max-age' 또는 'expires' 속성에 지정된 전체 기간이 없습니다.

  • 값

    문자열 선택사항

    쿠키 값입니다. 큰따옴표로 패딩될 수 있습니다.

HeaderFilter

다양한 기준에 따라 요청 헤더를 필터링합니다. 여러 기준이 접속사로 평가됩니다.

속성

  • nameContains

    문자열 | 문자열[] 선택사항

    헤더 이름에 지정된 문자열이 모두 포함되면 일치합니다.

  • nameEquals

    문자열 선택사항

    헤더 이름이 지정된 문자열과 동일한 경우 일치합니다.

  • namePrefix

    문자열 선택사항

    헤더 이름이 지정된 문자열로 시작하는 경우 일치합니다.

  • nameSuffix

    문자열 선택사항

    헤더 이름이 지정된 문자열로 끝나면 일치합니다.

  • valueContains

    문자열 | 문자열[] 선택사항

    헤더 값에 지정된 문자열이 모두 포함되면 일치합니다.

  • valueEquals

    문자열 선택사항

    헤더 값이 지정된 문자열과 같은 경우 일치합니다.

  • valuePrefix

    문자열 선택사항

    헤더 값이 지정된 문자열로 시작하는 경우 일치합니다.

  • valueSuffix

    문자열 선택사항

    헤더 값이 지정된 문자열로 끝나면 일치합니다.

IgnoreRules

지정된 기준과 일치하는 모든 규칙을 마스크합니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: IgnoreRules) => {...}

  • hasTag

    문자열 선택사항

    설정된 경우 지정된 태그가 있는 규칙은 무시됩니다. 이 무시는 지속되지 않으며 동일한 네트워크 요청 단계의 규칙과 작업에만 영향을 미칩니다. 규칙은 우선순위의 내림차순으로 실행됩니다. 이 작업은 현재 규칙보다 우선순위가 낮은 규칙에 영향을 미칩니다. 우선순위가 같은 규칙은 무시될 수도 있고 무시되지 않을 수도 있습니다.

  • lowerPriorityThan

    number(숫자) 선택사항

    설정된 경우 지정된 값보다 우선순위가 낮은 규칙은 무시됩니다. 이 경계는 유지되지 않으며 동일한 네트워크 요청 단계의 규칙과 작업에만 영향을 미칩니다.

RedirectByRegEx

URL에 정규 표현식을 적용하여 요청을 리디렉션합니다. 정규 표현식은 RE2 구문을 사용합니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: RedirectByRegEx) => {...}

  • 소스:

    문자열

    캡처 그룹을 포함할 수 있는 일치 패턴입니다. JavaScript 정규 표현식에 더 가깝게 하기 위해 캡처 그룹은 RE2 구문(\1, \2, ...) 대신 Perl 구문($1, $2, ...)에서 참조됩니다.

  • ->

    문자열

    대상 패턴입니다.

RedirectRequest

네트워크 요청을 리디렉션하는 선언적 이벤트 작업입니다.

속성

RedirectToEmptyDocument

네트워크 요청을 빈 문서로 리디렉션하는 선언적 이벤트 작업입니다.

속성

RedirectToTransparentImage

네트워크 요청을 투명 이미지로 리디렉션하는 선언적 이벤트 작업입니다.

속성

RemoveRequestCookie

요청의 쿠키를 하나 이상 삭제합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

RemoveRequestHeader

지정된 이름의 요청 헤더를 삭제합니다. 동일한 요청에서 동일한 헤더 이름으로 SetRequestHeader와 RemoveRequestHeader를 사용하지 마세요. 각 요청 헤더 이름은 각 요청에서 한 번만 발생합니다.

속성

RemoveResponseCookie

응답의 쿠키를 하나 이상 삭제합니다. 계산 비용이 더 저렴하므로 쿠키 API를 사용하는 것이 좋습니다.

속성

RemoveResponseHeader

지정된 이름과 값의 모든 응답 헤더를 삭제합니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: RemoveResponseHeader) => {...}

  • 이름

    문자열

    HTTP 요청 헤더 이름 (대소문자 구분 안 함)입니다.

  • 값

    문자열 선택사항

    HTTP 요청 헤더 값 (대소문자 구분 안 함)입니다.

RequestCookie

HTTP 요청의 쿠키 필터 또는 사양입니다.

속성

  • 이름

    문자열 선택사항

    쿠키의 이름입니다.

  • 값

    문자열 선택사항

    쿠키 값입니다. 큰따옴표로 패딩될 수 있습니다.

RequestMatcher

다양한 기준으로 네트워크 이벤트를 일치시킵니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: RequestMatcher) => {...}

  • contentType

    string[] 선택사항

    HTTP Content-Type 헤더의 응답 MIME 미디어 유형이 목록에 포함된 경우 일치합니다.

  • excludeContentType

    string[] 선택사항

    응답의 MIME 미디어 유형 (HTTP Content-Type 헤더에서 가져옴)이 목록에 포함되지 않으면 일치합니다.

  • excludeRequestHeaders

    HeaderFilter[] 선택사항

    요청 헤더가 HeaderFilter와 일치하지 않으면 일치합니다.

  • excludeResponseHeaders

    HeaderFilter[] 선택사항

    응답 헤더 중 어느 것도 HeaderFilter와 일치하지 않는 경우 일치합니다.

  • firstPartyForCookiesUrl

    UrlFilter 선택사항

    지원 중단됨

    버전 82부터 무시됩니다.

    요청의 '퍼스트 파티' URL에 UrlFilter의 조건이 충족되면 일치합니다. 요청의 '퍼스트 파티' URL은 있는 경우 요청의 타겟 URL과 다를 수 있으며, 쿠키의 서드 파티 검사를 위해 '퍼스트 파티'로 간주되는 항목을 설명합니다.

  • requestHeaders

    HeaderFilter[] 선택사항

    요청 헤더 중 일부가 HeaderFilter 중 하나와 일치하는 경우 일치합니다.

  • resourceType

    ResourceType[] 선택사항

    요청의 요청 유형이 목록에 포함된 경우 일치합니다. 어떤 유형과도 일치하지 않는 요청은 필터링됩니다.

  • responseHeaders

    HeaderFilter[] 선택사항

    응답 헤더 중 일부가 HeaderFilter 중 하나와 일치하는 경우 일치합니다.

  • 단계

    단계[] 선택사항

    단계를 설명하는 문자열 목록을 포함합니다. 허용되는 값은 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'입니다. 이 속성이 있으면 적용 가능한 단계가 나열된 단계로 제한됩니다. 전체 조건은 모든 속성과 호환되는 단계에서만 적용됩니다.

  • thirdPartyForCookies

    불리언 선택사항

    지원 중단됨

    버전 87부터 무시됩니다.

    true로 설정하면 서드 파티 쿠키 정책이 적용되는 요청과 일치합니다. false로 설정하면 다른 모든 요청과 일치합니다.

  • URL

    UrlFilter 선택사항

    요청 URL에 UrlFilter의 조건이 충족되면 일치합니다.

ResponseCookie

HTTP 응답의 쿠키 사양입니다.

속성

  • 도메인

    문자열 선택사항

    도메인 쿠키 속성의 값입니다.

  • 만료일

    문자열 선택사항

    Expires 쿠키 속성의 값입니다.

  • httpOnly

    문자열 선택사항

    HttpOnly 쿠키 속성의 존재 여부

  • maxAge

    number(숫자) 선택사항

    Max-Age 쿠키 속성의 값

  • 이름

    문자열 선택사항

    쿠키의 이름입니다.

  • 경로

    문자열 선택사항

    경로 쿠키 속성의 값입니다.

  • 보안

    문자열 선택사항

    Secure 쿠키 속성의 존재 여부입니다.

  • 값

    문자열 선택사항

    쿠키 값입니다. 큰따옴표로 패딩될 수 있습니다.

SendMessageToExtension

declarativeWebRequest.onMessage 이벤트를 트리거합니다.

속성

SetRequestHeader

지정된 이름의 요청 헤더를 지정된 값으로 설정합니다. 지정된 이름의 헤더가 이전에 없었던 경우 새 헤더가 생성됩니다. 헤더 이름 비교는 항상 대소문자를 구분하지 않습니다. 각 요청 헤더 이름은 각 요청에서 한 번만 발생합니다.

속성

  • 생성자

    void

    constructor 함수는 다음과 같습니다. 

    (arg: SetRequestHeader) => {...}

  • 이름

    문자열

    HTTP 요청 헤더 이름입니다.

  • 값

    문자열

    HTTP 요청 헤더 값입니다.

Stage

열거형

'onBeforeRequest'

'onBeforeSendHeaders'

'onHeadersReceived'

'onAuthRequired'

이벤트

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

선언적 웹 요청 API의 작업에서 declarativeWebRequest.SendMessageToExtension를 통해 메시지가 전송될 때 발생합니다.

매개변수

  • callback

    함수

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

    (details: object) => void

    • 세부정보

      객체

      • documentId

        문자열 선택사항

        요청을 한 문서의 UUID입니다.

      • 문서의 수명 주기입니다.

      • frameId

        숫자

        값 0은 요청이 기본 프레임에서 발생함을 나타내고, 양수 값은 요청이 발생하는 하위 프레임의 ID를 나타냅니다. (하위) 프레임의 문서가 로드된 경우 (type가 main_frame 또는 sub_frame인 경우) frameId는 외부 프레임의 ID가 아닌 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다.

      • 탐색이 발생한 프레임의 유형입니다.

      • 메시지

        문자열

        호출 스크립트에서 보낸 메시지입니다.

      • method

        문자열

        표준 HTTP 메서드입니다.

      • parentDocumentId

        문자열 선택사항

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

      • parentFrameId

        숫자

        요청을 보낸 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없는 경우 -1로 설정합니다.

      • requestId

        문자열

        요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 여러 이벤트를 연결하는 데 사용할 수 있습니다.

      • 각 단계에서

        Stage

        이벤트가 트리거된 네트워크 요청의 단계입니다.

      • tabId

        숫자

        요청이 발생하는 탭의 ID입니다. 요청이 탭과 관련이 없는 경우 -1로 설정합니다.

      • timeStamp

        숫자

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

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

      • URL

        문자열

onRequest

addRules, removeRules, getRules로 구성된 선언적 이벤트 API를 제공합니다.

조건

RequestMatcher

작업

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules