chrome.declarativeWebRequest

설명

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

권한

declarativeWebRequest

'declarativeWebRequest' 이 항목을 사용하려면 확장 프로그램 매니페스트의 권한이 필요합니다. API와 호스트 권한을 함께 제공합니다.

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

가용성

<ph type="x-smartling-placeholder"></ph> 베타 채널 에서 확인하세요. &amp;leq; 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 이벤트 객체에 추가합니다.

Declarative Web Request 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에서 거부됩니다. 또한 삽입된 iframe에 대한 모든 요청이 resourceType로 인해 거부됩니다.

'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에 설명된 대로 우선순위와 연결될 수 있습니다. 이 메커니즘은 예외를 표현하는 데 사용됩니다. 다음 예시는 이름이 evil.jpg인 이미지에 대한 모든 요청을 차단합니다. 'myserver.com' 서버를 제외하고 모두 해당됩니다.

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

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

속성

AddResponseCookie

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

속성

AddResponseHeader

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

속성

CancelRequest

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

속성

EditRequestCookie

하나 이상의 요청 쿠키를 수정합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.

속성

  • 생성자

    void

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

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

  • filter

    RequestCookie

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

  • 수정

    RequestCookie

    필터를 처리하는 쿠키에서 재정의되어야 하는 속성입니다. 빈 문자열로 설정된 속성은 삭제됩니다.

EditResponseCookie

하나 이상의 응답 쿠키를 수정합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.

속성

FilterResponseCookie

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

속성

  • ageLowerBound

    숫자 선택사항

    쿠키 전체 기간의 포괄적인 하한입니다 (현재 시간 이후의 초 단위로 지정됨). 만료일-시간이 '현재 + ageLowBound'로 설정된 쿠키만 이 기준을 충족할 수 있습니다. 세션 쿠키는 이 필터의 기준을 충족하지 않습니다. 쿠키 수명은 'max-age' 또는 'max-age' 또는 '만료'됩니다. 쿠키 속성으로 바꾸어야 합니다. 둘 다 지정하면 'max-age'가 됩니다. 쿠키 수명을 계산하는 데 사용됩니다.

  • ageUpperBound

    숫자 선택사항

    쿠키 전체 기간의 포함 상한값 (현재 시간 후 초 단위로 지정됨)입니다. 만료 날짜 및 시간이 [현재, 지금 + ageUpperBound] 간격인 쿠키만 이 기준을 충족합니다. 만료 날짜 및 시간이 과거인 세션 쿠키와 쿠키는 이 필터의 기준을 충족하지 않습니다. 쿠키 수명은 'max-age' 또는 'max-age' 또는 '만료'됩니다. 쿠키 속성으로 바꾸어야 합니다. 둘 다 지정하면 'max-age'가 됩니다. 쿠키 수명을 계산하는 데 사용됩니다.

  • 도메인

    문자열(선택사항)

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

  • 만료일

    문자열(선택사항)

    만료 쿠키 속성의 값입니다.

  • httpOnly

    문자열(선택사항)

    HttpOnly 쿠키 속성이 있습니다.

  • maxAge

    숫자 선택사항

    Max-Age 쿠키 속성의 값

  • 이름

    문자열(선택사항)

    쿠키의 이름입니다.

  • 경로

    문자열(선택사항)

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

  • 보안

    문자열(선택사항)

    보안 쿠키 속성이 있습니다.

  • sessionCookie

    불리언 선택사항

    세션 쿠키를 필터링합니다. 세션 쿠키의 전체 기간이 'max-age'에 지정되어 있지 않습니다. 또는 '만료'됩니다. 속성

  • 값

    문자열(선택사항)

    쿠키 값은 큰따옴표로 묶을 수 있습니다.

HeaderFilter

다양한 기준에 따라 요청 헤더를 필터링합니다. 여러 기준은 결합으로 평가됩니다.

속성

  • nameContains

    string | string[] 선택사항

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

  • nameEquals

    문자열(선택사항)

    헤더 이름이 지정된 문자열과 같으면 일치합니다.

  • namePrefix

    문자열(선택사항)

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

  • nameSuffix

    문자열(선택사항)

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

  • valueContains

    string | string[] 선택사항

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

  • valueEquals

    문자열(선택사항)

    헤더 값이 지정된 문자열과 같으면 일치합니다.

  • valuePrefix

    문자열(선택사항)

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

  • valueSuffix

    문자열(선택사항)

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

IgnoreRules

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

속성

  • 생성자

    void

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

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

  • hasTag

    문자열(선택사항)

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

  • lowerPriorityThan

    숫자 선택사항

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

RedirectByRegEx

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

속성

  • 생성자

    void

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

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

  • 출처:

    문자열

    캡처 그룹이 포함될 수 있는 일치 패턴 캡처 그룹은 자바스크립트 정규 표현식에 더 가까워지도록 RE2 구문(\1, \2, ...) 대신 Perl 구문($1, $2, ...)에서 참조됩니다.

  • to

    문자열

    대상 패턴입니다.

RedirectRequest

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

속성

RedirectToEmptyDocument

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

속성

RedirectToTransparentImage

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

속성

RemoveRequestCookie

하나 이상의 요청 쿠키를 삭제합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.

속성

RemoveRequestHeader

지정된 이름의 요청 헤더를 삭제합니다. 같은 요청에서 헤더 이름이 같은 SetRequestHeader 및 RemoveRequestHeader를 사용하지 마세요. 각 요청 헤더 이름은 각 요청에서 한 번만 나타납니다.

속성

RemoveResponseCookie

하나 이상의 응답 쿠키를 삭제합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.

속성

RemoveResponseHeader

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

속성

  • 생성자

    void

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

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

  • 이름

    문자열

    HTTP 요청 헤더 이름 (대소문자를 구분하지 않음)

  • 값

    문자열(선택사항)

    HTTP 요청 헤더 값 (대소문자를 구분하지 않음)

RequestCookie

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

속성

  • 이름

    문자열(선택사항)

    쿠키의 이름입니다.

  • 값

    문자열(선택사항)

    쿠키 값은 큰따옴표로 묶을 수 있습니다.

RequestMatcher

다양한 기준에 따라 네트워크 이벤트를 일치시킵니다.

속성

  • 생성자

    void

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

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

  • contentType

    string[] 선택사항

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

  • excludeContentType

    string[] 선택사항

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

  • excludeRequestHeaders

    HeaderFilter[] 선택사항

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

  • excludeResponseHeaders

    HeaderFilter[] 선택사항

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

  • firstPartyForCookiesUrl

    UrlFilter 선택사항

    <ph type="x-smartling-placeholder"></ph> 지원 중단됨

    출시 82 이후 무시됩니다.

    '퍼스트 파티'에 대해 UrlFilter의 조건이 충족되면 일치합니다. 요청의 URL입니다. '퍼스트 파티' 요청의 URL(있는 경우)은 요청의 대상 URL과 다를 수 있으며 '퍼스트 파티'로 간주되는 URL을 설명합니다. 제3자가 쿠키를 확인할 수 있기 때문입니다.

  • requestHeaders

    HeaderFilter[] 선택사항

    요청 헤더 중 일부가 HeaderFilters 중 하나와 일치하면 일치합니다.

  • resourceType

    ResourceType[] 선택사항

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

  • responseHeaders

    HeaderFilter[] 선택사항

    일부 응답 헤더가 HeaderFilters 중 하나와 일치하면 일치합니다.

  • 단계

    단계[] 선택사항

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

  • thirdPartyForCookies

    불리언 선택사항

    <ph type="x-smartling-placeholder"></ph> 지원 중단됨

    출시 87 이후 무시됩니다.

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

  • URL

    UrlFilter 선택사항

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

ResponseCookie

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

속성

  • 도메인

    문자열(선택사항)

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

  • 만료일

    문자열(선택사항)

    만료 쿠키 속성의 값입니다.

  • httpOnly

    문자열(선택사항)

    HttpOnly 쿠키 속성이 있습니다.

  • maxAge

    숫자 선택사항

    Max-Age 쿠키 속성의 값

  • 이름

    문자열(선택사항)

    쿠키의 이름입니다.

  • 경로

    문자열(선택사항)

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

  • 보안

    문자열(선택사항)

    보안 쿠키 속성이 있습니다.

  • 값

    문자열(선택사항)

    쿠키 값은 큰따옴표로 묶을 수 있습니다.

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 매개변수는 다음과 같습니다. 

    (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는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 여러 이벤트를 연결하는 데 사용될 수 있습니다.

      • 각 단계에서

        단계

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

      • 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