설명
참고: 이 API는 지원 중단되었습니다. 대신 declarativeNetRequest
API를 확인하세요. chrome.declarativeWebRequest
API를 사용하여 진행 중인 요청을 가로채거나 차단하거나 수정합니다. JavaScript 엔진이 아닌 브라우저에서 평가되는 규칙을 등록할 수 있으므로 왕복 지연 시간이 줄어들고 효율성이 높아지므로 chrome.webRequest
API보다 훨씬 빠릅니다.
권한
declarativeWebRequest
'declarativeWebRequest' 이 항목을 사용하려면 확장 프로그램 매니페스트의 권한이 필요합니다. API와 호스트 권한을 함께 제공합니다.
{
"name": "My extension",
...
"permissions": [
"declarativeWebRequest",
"*://*/*"
],
...
}
가용성
매니페스트
민감하지 않은 특정 작업 유형에는 호스트 권한이 필요하지 않습니다.
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를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: AddRequestCookie) => {...}
-
returns
-
-
요청에 추가할 쿠키입니다. 어떠한 입력란도 정의되지 않을 수 있습니다.
AddResponseCookie
응답에 쿠키를 추가하거나 동일한 이름의 다른 쿠키가 이미 있는 경우 쿠키를 재정의합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: AddResponseCookie) => {...}
-
returns
-
-
응답에 추가할 쿠키입니다. 이름과 값을 지정해야 합니다.
AddResponseHeader
이 웹 요청의 응답에 응답 헤더를 추가합니다. 여러 응답 헤더가 동일한 이름을 공유할 수 있으므로 하나를 대체하려면 먼저 응답 헤더를 삭제한 다음 새로 추가해야 합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: AddResponseHeader) => {...}
-
returns
-
-
이름
문자열
HTTP 응답 헤더 이름입니다.
-
값
문자열
HTTP 응답 헤더 값입니다.
CancelRequest
네트워크 요청을 취소하는 선언적 이벤트 작업입니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: CancelRequest) => {...}
-
returns
-
EditRequestCookie
하나 이상의 요청 쿠키를 수정합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: EditRequestCookie) => {...}
-
returns
-
-
filter
수정될 쿠키를 필터링합니다. 빈 항목은 모두 무시됩니다.
-
필터를 처리하는 쿠키에서 재정의되어야 하는 속성입니다. 빈 문자열로 설정된 속성은 삭제됩니다.
EditResponseCookie
하나 이상의 응답 쿠키를 수정합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: EditResponseCookie) => {...}
-
returns
-
-
filter
수정될 쿠키를 필터링합니다. 빈 항목은 모두 무시됩니다.
-
필터를 처리하는 쿠키에서 재정의되어야 하는 속성입니다. 빈 문자열로 설정된 속성은 삭제됩니다.
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) => {...}
-
인수
-
returns
-
-
hasTag
문자열(선택사항)
설정하면 지정된 태그가 있는 규칙이 무시됩니다. 이 무시는 지속되지 않으며, 동일한 네트워크 요청 단계의 규칙과 해당 작업에만 영향을 미칩니다. 규칙은 우선순위의 내림차순으로 실행됩니다. 이 작업은 현재 규칙보다 우선순위가 낮은 규칙에 영향을 줍니다. 우선순위가 같은 규칙은 무시될 수도 있고 무시하지 않을 수도 있습니다.
-
lowerPriorityThan
숫자 선택사항
설정하면 지정된 값보다 우선순위가 낮은 규칙이 무시됩니다. 이 경계는 지속되지 않으며, 동일한 네트워크 요청 단계의 규칙과 해당 작업에만 영향을 미칩니다.
RedirectByRegEx
URL에 정규 표현식을 적용하여 요청을 리디렉션합니다. 정규 표현식에는 RE2 구문이 사용됩니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RedirectByRegEx) => {...}
-
returns
-
-
출처:
문자열
캡처 그룹이 포함될 수 있는 일치 패턴 캡처 그룹은 자바스크립트 정규 표현식에 더 가까워지도록 RE2 구문(\1, \2, ...) 대신 Perl 구문($1, $2, ...)에서 참조됩니다.
-
to
문자열
대상 패턴입니다.
RedirectRequest
네트워크 요청을 리디렉션하는 선언적 이벤트 작업입니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RedirectRequest) => {...}
-
returns
-
-
redirectUrl
문자열
요청이 리디렉션되는 대상입니다.
RedirectToEmptyDocument
네트워크 요청을 빈 문서로 리디렉션하는 선언적 이벤트 작업입니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RedirectToEmptyDocument) => {...}
-
returns
-
RedirectToTransparentImage
네트워크 요청을 투명한 이미지로 리디렉션하는 선언적 이벤트 작업입니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RedirectToTransparentImage) => {...}
-
returns
-
RemoveRequestCookie
하나 이상의 요청 쿠키를 삭제합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RemoveRequestCookie) => {...}
-
returns
-
-
filter
삭제될 쿠키를 필터링합니다. 빈 항목은 모두 무시됩니다.
RemoveRequestHeader
지정된 이름의 요청 헤더를 삭제합니다. 같은 요청에서 헤더 이름이 같은 SetRequestHeader 및 RemoveRequestHeader를 사용하지 마세요. 각 요청 헤더 이름은 각 요청에서 한 번만 나타납니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RemoveRequestHeader) => {...}
-
returns
-
-
이름
문자열
HTTP 요청 헤더 이름 (대소문자를 구분하지 않음)
RemoveResponseCookie
하나 이상의 응답 쿠키를 삭제합니다. Cookies API를 사용하면 계산 비용이 저렴하기 때문에 Cookies API를 사용하는 것이 좋습니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RemoveResponseCookie) => {...}
-
returns
-
-
filter
삭제될 쿠키를 필터링합니다. 빈 항목은 모두 무시됩니다.
RemoveResponseHeader
지정된 이름과 값의 모든 응답 헤더를 삭제합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RemoveResponseHeader) => {...}
-
returns
-
-
이름
문자열
HTTP 요청 헤더 이름 (대소문자를 구분하지 않음)
-
값
문자열(선택사항)
HTTP 요청 헤더 값 (대소문자를 구분하지 않음)
RequestCookie
HTTP 요청의 쿠키 필터 또는 사양입니다.
속성
-
이름
문자열(선택사항)
쿠키의 이름입니다.
-
값
문자열(선택사항)
쿠키 값은 큰따옴표로 묶을 수 있습니다.
RequestMatcher
다양한 기준에 따라 네트워크 이벤트를 일치시킵니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RequestMatcher) => {...}
-
returns
-
-
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
이벤트를 트리거합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: SendMessageToExtension) => {...}
-
returns
-
-
메시지
문자열
이벤트 핸들러에 전달되는 사전의
message
속성으로 전달되는 값입니다.
SetRequestHeader
지정된 이름의 요청 헤더를 지정된 값으로 설정합니다. 지정된 이름의 헤더가 기존에 없었던 경우 새 헤더가 생성됩니다. 헤더 이름 비교에서는 항상 대소문자를 구분하지 않습니다. 각 요청 헤더 이름은 각 요청에서 한 번만 나타납니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: SetRequestHeader) => {...}
-
returns
-
-
이름
문자열
HTTP 요청 헤더 이름입니다.
-
값
문자열
HTTP 요청 헤더 값입니다.
Stage
열거형
'onBeforeRequest'
'onBeforeSendHeaders'
'onHeadersReceived'
'onAuthRequired'
이벤트
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
선언적 웹 요청 API의 작업에서 declarativeWebRequest.SendMessageToExtension
를 통해 메시지가 전송될 때 실행됩니다.
매개변수
-
콜백
함수
callback
매개변수는 다음과 같습니다.(details: object) => void
-
세부정보
객체
-
documentId
문자열(선택사항)
요청한 문서의 UUID입니다.
-
documentLifecycle
문서의 수명 주기입니다.
-
frameId
숫자
값 0은 요청이 메인 프레임에서 발생함을 나타냅니다. 양수 값은 요청이 발생하는 서브프레임의 ID를 나타냅니다. (하위) 프레임의 문서가 로드되면 (
type
이main_frame
또는sub_frame
인 경우)frameId
는 외부 프레임의 ID가 아니라 이 프레임의 ID를 나타냅니다. 프레임 ID는 탭 내에서 고유합니다. -
frameType
탐색이 발생한 프레임 유형입니다.
-
메시지
문자열
호출 스크립트에서 보낸 메시지입니다.
-
method
문자열
표준 HTTP 메서드입니다.
-
parentDocumentId
문자열(선택사항)
이 프레임을 소유한 상위 문서의 UUID입니다. 상위 항목이 없으면 설정되지 않습니다.
-
parentFrameId
숫자
요청을 전송한 프레임을 래핑하는 프레임의 ID입니다. 상위 프레임이 없으면 -1로 설정합니다.
-
requestId
문자열
요청의 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다. 따라서 동일한 요청의 여러 이벤트를 연결하는 데 사용될 수 있습니다.
-
각 단계에서
이벤트가 트리거된 네트워크 요청 단계입니다.
-
tabId
숫자
요청이 발생한 탭의 ID입니다. 요청이 탭과 관련이 없다면 -1로 설정합니다.
-
timeStamp
숫자
이 신호가 트리거된 시간이며, 에포크 이후의 경과 시간(밀리초)입니다.
-
요청된 리소스가 사용되는 방식입니다.
-
URL
문자열
-
-
onRequest
addRules
, removeRules
, getRules
로 구성된 선언적 이벤트 API를 제공합니다.
작업