설명
참고: 이 API는 지원 중단되었습니다. 대신 declarativeNetRequest
API를 확인하세요. chrome.declarativeWebRequest
API를 사용하여 진행 중인 요청을 가로채거나 차단하거나 수정합니다. 자바스크립트 엔진이 아닌 브라우저에서 평가되는 규칙을 등록할 수 있으므로 chrome.webRequest
API보다 훨씬 빠릅니다. 이를 통해 왕복 지연 시간을 줄이고 효율성을 높일 수 있습니다.
권한
declarativeWebRequest
이 API를 호스트 권한과 함께 사용하려면 확장 프로그램 매니페스트에서 'declarativeWebRequest' 권한을 선언해야 합니다.
{
"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
이벤트 객체에 규칙을 등록할 수 있습니다.
선언적 웹 요청 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에 설명된 대로 우선순위와 연결될 수 있습니다. 이 메커니즘을 사용하여 예외를 표현할 수 있습니다. 다음 예시에서는 '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
같은 이름의 다른 쿠키가 이미 있는 경우 요청에 쿠키를 추가하거나 쿠키를 재정의합니다. 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
number 선택사항
쿠키 수명에 관한 포괄적 하한값입니다 (현재 시간 이후 초 단위로 지정됨). 만료일 및 시간이 '현재 + 연령 하한값' 이상으로 설정된 쿠키만 이 기준을 충족합니다. 세션 쿠키는 이 필터의 기준을 충족하지 않습니다. 쿠키 수명은 'max-age' 또는 'expires' 쿠키 속성으로 계산됩니다. 둘 다 지정된 경우 'max-age'를 사용하여 쿠키 수명을 계산합니다.
-
ageUpperBound
number 선택사항
쿠키 수명에 관한 포괄적 상한값입니다 (현재 시간 이후 초 단위로 지정됨). 만료일 및 시간이 [지금, 현재 + ageUpperBound] 간격인 쿠키만 이 기준을 충족합니다. 만료 날짜/시간이 과거인 세션 쿠키와 쿠키는 이 필터의 기준을 충족하지 않습니다. 쿠키 수명은 'max-age' 또는 'expires' 쿠키 속성으로 계산됩니다. 둘 다 지정된 경우 'max-age'를 사용하여 쿠키 수명을 계산합니다.
-
도메인
문자열 선택사항
도메인 쿠키 속성의 값입니다.
-
만료일
문자열 선택사항
만료 쿠키 속성의 값입니다.
-
httpOnly
문자열 선택사항
HttpOnly 쿠키 속성이 있어야 합니다.
-
maxAge
number 선택사항
Max-Age 쿠키 속성의 값
-
이름
문자열 선택사항
쿠키의 이름입니다.
-
경로
문자열 선택사항
경로 쿠키 속성의 값입니다.
-
보안
문자열 선택사항
보안 쿠키 속성의 존재 여부
-
sessionCookie
부울 선택사항
세션 쿠키를 필터링합니다. 세션 쿠키의 전체 기간은 'max-age' 또는 'expires' 속성에 지정되어 있지 않습니다.
-
값
문자열 선택사항
쿠키의 값으로, 큰따옴표를 사용하여 패딩할 수 있습니다.
HeaderFilter
다양한 기준에 따라 요청 헤더를 필터링합니다. 여러 기준은 결합으로 평가됩니다.
속성
-
nameContains
string | string[] 선택사항
헤더 이름에 지정된 모든 문자열이 포함된 경우 일치합니다.
-
nameEquals
문자열 선택사항
헤더 이름이 지정된 문자열과 같은 경우 일치합니다.
-
namePrefix
문자열 선택사항
헤더 이름이 지정된 문자열로 시작하는 경우 일치합니다.
-
nameSuffix
문자열 선택사항
헤더 이름이 지정된 문자열로 끝나는 경우 일치합니다.
-
valueContains
string | string[] 선택사항
헤더 값에 지정된 모든 문자열이 포함된 경우 일치합니다.
-
valueEquals
문자열 선택사항
헤더 값이 지정된 문자열과 같은 경우 일치합니다.
-
valuePrefix
문자열 선택사항
헤더 값이 지정된 문자열로 시작하는 경우 일치합니다.
-
valueSuffix
문자열 선택사항
헤더 값이 지정된 문자열로 끝나는 경우 일치합니다.
IgnoreRules
지정된 기준과 일치하는 모든 규칙을 마스킹합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: IgnoreRules) => {...}
-
인수
-
returns
-
-
hasTag
문자열 선택사항
설정하면 지정된 태그가 있는 규칙이 무시됩니다. 이러한 무시는 지속되지 않으며, 동일한 네트워크 요청 단계의 규칙과 작업에만 영향을 미칩니다. 규칙은 우선순위의 내림차순으로 실행됩니다. 이 작업은 현재 규칙보다 우선순위가 낮은 규칙에 영향을 줍니다. 우선순위가 같은 규칙은 무시되거나 무시되지 않을 수 있습니다.
-
lowerPriorityThan
number 선택사항
설정하면 지정된 값보다 우선순위가 낮은 규칙이 무시됩니다. 이 경계는 지속되지 않으며, 동일한 네트워크 요청 단계의 규칙과 해당 작업에만 영향을 미칩니다.
RedirectByRegEx
URL에 정규 표현식을 적용하여 요청을 리디렉션합니다. 정규 표현식은 RE2 구문을 사용합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: RedirectByRegEx) => {...}
-
returns
-
-
출처:
문자열
캡처 그룹을 포함할 수 있는 일치 패턴입니다. 캡처 그룹은 JavaScript 정규 표현식에 더 가깝기 위해 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[] 선택사항
응답의 MIME 미디어 유형 (HTTP Content-Type 헤더)이 목록에 포함되어 있으면 일치합니다.
-
excludeContentType
string[] 선택사항
HTTP Content-Type 헤더에서 보낸 응답의 MIME 미디어 유형이 목록에 포함되지 않은 경우 일치합니다.
-
excludeRequestHeaders
HeaderFilter[] 선택사항
HeaderFilter와 일치하는 요청 헤더가 없는 경우 일치합니다.
-
excludeResponseHeaders
HeaderFilter[] 선택사항
헤더 필터 중 어느 것과도 일치하는 응답 헤더가 없는 경우 일치합니다.
-
firstPartyForCookiesUrl
UrlFilter 선택사항
지원 중단됨버전 82부터 무시되었습니다.
요청의 '퍼스트 파티' URL에 대해 UrlFilter의 조건이 충족되는 경우 일치합니다. 요청의 '퍼스트 파티' URL(있는 경우)은 요청의 타겟 URL과 다를 수 있으며, 서드 파티가 쿠키를 확인하기 위해 '퍼스트 파티'로 간주되는 URL을 설명합니다.
-
requestHeaders
HeaderFilter[] 선택사항
일부 요청 헤더가 헤더 필터 중 하나와 일치하는 경우 일치합니다.
-
resourceType
ResourceType[] 선택사항
요청의 요청 유형이 목록에 포함된 경우 일치합니다. 어떤 유형과도 일치하지 않는 요청은 필터링됩니다.
-
responseHeaders
HeaderFilter[] 선택사항
일부 응답 헤더가 헤더 필터 중 하나와 일치하는 경우 일치합니다.
-
단계
Stage[] 선택사항
단계를 설명하는 문자열 목록을 포함합니다. 허용되는 값은 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'입니다. 이 속성이 있으면 적용 가능한 단계를 나열된 단계로 제한합니다. 전체 조건은 모든 속성과 호환되는 단계에만 적용됩니다.
-
thirdPartyForCookies
부울 선택사항
지원 중단됨87 버전 이후 무시되었습니다.
true로 설정하면 서드 파티 쿠키 정책이 적용되는 요청과 일치합니다. false로 설정하면 다른 모든 요청과 일치합니다.
-
url
UrlFilter 선택사항
요청 URL에 대해 UrlFilter의 조건이 충족되는 경우 일치합니다.
ResponseCookie
HTTP 응답의 쿠키 사양입니다.
속성
-
도메인
문자열 선택사항
도메인 쿠키 속성의 값입니다.
-
만료일
문자열 선택사항
만료 쿠키 속성의 값입니다.
-
httpOnly
문자열 선택사항
HttpOnly 쿠키 속성이 있어야 합니다.
-
maxAge
number 선택사항
Max-Age 쿠키 속성의 값
-
이름
문자열 선택사항
쿠키의 이름입니다.
-
경로
문자열 선택사항
경로 쿠키 속성의 값입니다.
-
보안
문자열 선택사항
보안 쿠키 속성의 존재 여부
-
값
문자열 선택사항
쿠키의 값으로, 큰따옴표를 사용하여 패딩할 수 있습니다.
SendMessageToExtension
declarativeWebRequest.onMessage
이벤트를 트리거합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: SendMessageToExtension) => {...}
-
returns
-
-
메시지
문자열
이벤트 핸들러에 전달되는 사전의
message
속성에 전달되는 값입니다.
SetRequestHeader
지정된 이름의 요청 헤더를 지정된 값으로 설정합니다. 지정된 이름을 가진 헤더가 이전에 존재하지 않는 경우 새 헤더가 생성됩니다. 헤더 이름 비교는 항상 대소문자를 구분하지 않습니다. 각 요청 헤더 이름은 각 요청에서 한 번만 발생합니다.
속성
-
생성자
void
constructor
함수는 다음과 같습니다.(arg: SetRequestHeader) => {...}
-
returns
-
-
이름
문자열
HTTP 요청 헤더 이름입니다.
-
값
문자열
HTTP 요청 헤더 값입니다.
Stage
enum
"onBeforeSendHeaders"
"onHeadersReceived"
이벤트
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
선언적 웹 요청 API의 작업에서 declarativeWebRequest.SendMessageToExtension
를 통해 메시지가 전송되면 실행됩니다.
매개변수
-
callback
기능
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를 제공합니다.
작업