chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

설명

chrome.declarativeNetRequest API는 선언적 규칙을 지정하여 네트워크 요청을 차단하거나 수정하는 데 사용됩니다. 이를 통해 확장 프로그램은 네트워크 요청을 가로채거나 콘텐츠를 보지 않고도 네트워크 요청을 수정할 수 있으므로 개인 정보 보호가 강화됩니다.

권한

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

가용성

Chrome 84 이상

매니페스트

위에 설명된 권한 외에도 특정 유형의 규칙 세트(특히 정적 규칙 세트)는 "declarative_net_request" 매니페스트 키를 선언해야 합니다. 이 키는 "rule_resources"라는 단일 키가 있는 사전이어야 합니다. 이 키는 아래와 같이 Ruleset 유형의 딕셔너리를 포함하는 배열입니다. 'Ruleset'이라는 이름은 배열일 뿐이므로 매니페스트의 JSON에 표시되지 않습니다. 정적 규칙 세트는 이 문서의 뒷부분에서 설명합니다.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

개념 및 사용법

이 API를 사용하려면 규칙 세트를 하나 이상 지정하세요. 규칙 세트에는 규칙 배열이 포함됩니다. 단일 규칙은 다음 중 하나를 수행합니다.

  • 네트워크 요청을 차단합니다.
  • 스키마를 업그레이드합니다 (http에서 https로).
  • 일치하는 차단 규칙을 무효화하여 요청이 차단되지 않도록 합니다.
  • 네트워크 요청을 리디렉션합니다.
  • 요청 또는 응답 헤더를 수정합니다.

규칙 세트에는 세 가지 유형이 있으며, 약간 다른 방식으로 관리됩니다.

동적
브라우저 세션 및 확장 프로그램 업그레이드 전반에 걸쳐 유지되며 확장 프로그램이 사용되는 동안 JavaScript를 사용하여 관리됩니다.
세션
브라우저가 종료되고 새 버전의 확장 프로그램이 설치되면 삭제됩니다. 세션 규칙은 확장 프로그램이 사용 중인 동안 JavaScript를 사용하여 관리됩니다.
정적
확장 프로그램이 설치되거나 업그레이드될 때 패키징, 설치, 업데이트됩니다. 정적 규칙은 JSON 형식의 규칙 파일에 저장되며 매니페스트 파일에 나열됩니다.

다음 몇 섹션에서는 규칙 세트 유형을 자세히 설명합니다.

동적 및 세션 범위 규칙 세트

동적 및 세션 규칙 세트는 확장 프로그램이 사용 중인 동안 JavaScript를 사용하여 관리됩니다.

  • 동적 규칙은 브라우저 세션 및 확장 프로그램 업그레이드 전반에서 유지됩니다.
  • 세션 규칙은 브라우저가 종료되고 새 버전의 확장 프로그램이 설치될 때 삭제됩니다.

이러한 규칙 세트 유형은 각각 하나만 있습니다. 확장 프로그램은 규칙 한도를 초과하지 않는 한 updateDynamicRules() 및 updateSessionRules()를 호출하여 규칙을 동적으로 추가하거나 삭제할 수 있습니다. 규칙 한도에 대한 자세한 내용은 규칙 한도를 참조하세요. 코드 예시에서 이 예시를 확인할 수 있습니다.

정적 규칙 세트

동적 규칙 및 세션 규칙과 달리 정적 규칙은 확장 프로그램이 설치되거나 업그레이드될 때 패키징, 설치, 업데이트됩니다. 이러한 규칙은 JSON 형식의 규칙 파일에 저장되며, 위에서 설명한 대로 "declarative_net_request" 및 "rule_resources" 키와 하나 이상의 Ruleset 사전을 사용하여 확장 프로그램에 표시됩니다. Ruleset 사전에는 규칙 파일의 경로, 파일에 포함된 규칙 세트의 ID, 규칙 세트의 사용 설정 여부가 포함됩니다. 마지막 두 가지는 프로그래매틱 방식으로 규칙 세트를 사용 설정하거나 사용 중지할 때 중요합니다.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

규칙 파일을 테스트하려면 압축해제된 확장 프로그램을 로드합니다. 잘못된 정적 규칙에 관한 오류 및 경고는 압축해제된 확장 프로그램에만 표시됩니다. 패키징된 확장 프로그램의 잘못된 정적 규칙은 무시됩니다.

정적 규칙 및 규칙 세트 사용 설정 및 중지

개별 정적 규칙과 전체 정적 규칙 집합은 모두 런타임에 사용 설정하거나 사용 중지할 수 있습니다.

사용 설정된 정적 규칙 및 규칙 세트는 브라우저 세션 전반에서 유지됩니다. 둘 다 확장 프로그램 업데이트 전반에 걸쳐 유지되지 않습니다. 즉, 업데이트 후에는 규칙 파일에 남겨 두기로 선택한 규칙만 사용할 수 있습니다.

성능상의 이유로 한 번에 사용 설정할 수 있는 규칙 및 규칙 세트의 수에도 제한이 있습니다. getAvailableStaticRuleCount()을 호출하여 사용 설정할 수 있는 추가 규칙 수를 확인합니다. 규칙 한도에 대한 자세한 내용은 규칙 한도를 참조하세요.

정적 규칙을 사용 설정하거나 중지하려면 updateStaticRules()를 호출합니다. 이 메서드는 사용 설정하거나 사용 중지할 규칙의 ID 배열이 포함된 UpdateStaticRulesOptions 객체를 사용합니다. ID는 Ruleset 사전의 "id" 키를 사용하여 정의됩니다.

정적 규칙 세트를 사용 설정하거나 중지하려면 updateEnabledRulesets()를 호출합니다. 이 메서드는 사용 설정하거나 사용 중지할 규칙 세트의 ID 배열이 포함된 UpdateRulesetOptions 객체를 사용합니다. ID는 Ruleset 사전의 "id" 키를 사용하여 정의됩니다.

빌드 규칙

유형에 관계없이 규칙은 아래와 같이 네 개의 필드로 시작합니다. "id" 및 "priority" 키는 숫자를 사용하지만 "action" 및 "condition" 키는 여러 차단 및 리디렉션 조건을 제공할 수 있습니다. 다음 규칙은 "foo.com"에서 시작하여 "abc"를 하위 문자열로 포함하는 모든 URL로 전송되는 모든 스크립트 요청을 차단합니다.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

urlFilter 일치 문자

규칙의 "condition" 키는 지정된 도메인의 URL에 적용되는 "urlFilter" 키를 허용합니다. 패턴 일치 토큰을 사용하여 패턴을 만듭니다. 아래에 몇 가지 예시가 나와 있습니다.

urlFilter 매치 일치하지 않음
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

규칙 우선순위 지정

규칙은 웹페이지에서 전송된 요청에 의해 트리거됩니다. 여러 규칙이 특정 요청과 일치하는 경우 규칙의 우선순위를 지정해야 합니다. 이 섹션에서는 우선순위가 지정되는 방식을 설명합니다. 우선순위 지정은 두 단계로 진행됩니다.

  1. 우선순위는 확장 프로그램 내의 규칙에 따라 결정됩니다.
  2. 둘 이상의 확장 프로그램이 요청에 규칙을 적용할 수 있는 경우 특정 요청과 일치하는 모든 확장 프로그램에 우선순위가 결정됩니다.

이러한 방식으로 일치하는 것을 생각해 보세요. 특정 확장 프로그램이 우선순위를 지정하는 규칙은 다른 확장 프로그램의 규칙보다 우선순위가 지정됩니다.

확장 프로그램 내 규칙 우선순위 지정

단일 확장 프로그램 내에서 우선순위는 다음 프로세스를 사용하여 결정됩니다.

  1. 개발자가 정의한 우선순위 (즉, "priority" 필드)가 가장 높은 규칙이 반환됩니다.

  2. 개발자가 정의한 우선순위가 가장 높은 규칙이 두 개 이상 있는 경우 다음 순서로 "action" 필드를 사용하여 규칙의 우선순위가 지정됩니다.

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. 작업 유형이 block 또는 redirect가 아닌 경우 일치하는 modifyHeaders 규칙이 평가됩니다. 개발자가 정의한 우선순위가 allow 및 allowAllRequests에 지정된 우선순위보다 낮은 규칙이 있는 경우 이러한 규칙은 무시됩니다.

  4. 여러 규칙이 동일한 헤더를 수정하는 경우 개발자가 정의한 "priority" 필드와 지정된 작업에 따라 수정이 결정됩니다.

    • 규칙이 헤더에 추가되면 우선순위가 낮은 규칙은 해당 헤더에만 추가할 수 있습니다. 설정 및 삭제 작업은 허용되지 않습니다.
    • 규칙이 헤더를 설정하는 경우 우선순위가 낮은 규칙은 해당 헤더에만 추가할 수 있습니다. 다른 수정은 허용되지 않습니다.
    • 규칙이 헤더를 삭제하면 우선순위가 낮은 규칙은 헤더를 더 이상 수정할 수 없습니다.

확장 프로그램 간 규칙 우선순위 지정

하나의 확장 프로그램에만 요청과 일치하는 규칙이 있는 경우 해당 규칙이 적용됩니다. 하지만 두 개 이상의 확장 프로그램이 요청과 일치하는 경우 다음 프로세스가 사용됩니다.

  1. 규칙은 "action" 필드를 사용하여 다음 순서로 우선순위가 지정됩니다.

    1. block
    2. redirect 또는 upgradeScheme
    3. allow 또는 allowAllRequests

  2. 일치하는 규칙이 두 개 이상인 경우 가장 최근에 설치된 확장 프로그램이 우선 적용됩니다.

규칙 한도

브라우저에서 규칙을 로드하고 평가하는 데 성능 오버헤드가 있으므로 API를 사용할 때 몇 가지 제한사항이 적용됩니다. 한도는 사용 중인 규칙 유형에 따라 다릅니다.

정적 규칙

정적 규칙은 매니페스트 파일에 선언된 규칙 파일에 지정된 규칙입니다. 확장 프로그램은 "rule_resources" 매니페스트 키의 일부로 최대 50개의 정적 규칙 세트를 지정할 수 있지만 한 번에 10개의 규칙 세트만 사용 설정할 수 있습니다. 후자를 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS라고 합니다. 이러한 규칙 세트는 총 30,000개 이상의 규칙을 보장합니다. 이를 GUARANTEED_MINIMUM_STATIC_RULES라고 합니다.

그 이후에 사용할 수 있는 규칙의 수는 사용자의 브라우저에 설치된 모든 확장 프로그램에서 사용 설정된 규칙의 수에 따라 달라집니다. 런타임 시 getAvailableStaticRuleCount()를 호출하여 이 번호를 찾을 수 있습니다. 코드 예시에서 이 예시를 확인할 수 있습니다.

동적 및 세션 규칙

동적 규칙과 세션 규칙에 적용되는 한도는 정적 규칙보다 간단합니다. 두 항목의 총 개수는 5,000개를 초과할 수 없습니다. 이를 MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES라고 합니다.

정규식을 사용하는 규칙

모든 유형의 규칙에서 정규 표현식을 사용할 수 있지만 각 유형의 정규식 규칙 총 개수는 1, 000개를 초과할 수 없습니다. 이를 MAX_NUMBER_OF_REGEX_RULES라고 합니다.

또한 각 규칙은 컴파일된 후 2KB 미만이어야 합니다. 이는 규칙의 복잡성과 대략적으로 관련이 있습니다. 이 한도를 초과하는 규칙을 로드하려고 하면 아래와 같은 경고가 표시되고 규칙이 무시됩니다.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

서비스 워커와의 상호작용

declarativeNetRequest는 네트워크 스택에 도달하는 요청에만 적용됩니다. 여기에는 HTTP 캐시의 응답이 포함되지만 서비스 워커의 onfetch 핸들러를 통과하는 응답은 포함되지 않을 수 있습니다. declarativeNetRequest는 서비스 워커에서 생성되거나 CacheStorage에서 가져온 응답에 영향을 미치지 않지만 서비스 워커에서 이루어진 fetch() 호출에는 영향을 미칩니다.

웹 액세스 가능 리소스

declarativeNetRequest 규칙은 공개 리소스 요청에서 웹 액세스가 불가능한 리소스로 리디렉션할 수 없습니다. 이렇게 하면 오류가 트리거됩니다. 이는 지정된 웹 액세스 가능 리소스가 리디렉션 확장 프로그램에 의해 소유된 경우에도 마찬가지입니다. declarativeNetRequest의 리소스를 선언하려면 매니페스트의 "web_accessible_resources" 배열을 사용합니다.

예

코드 예시

동적 규칙 업데이트

다음 예시에서는 updateDynamicRules()를 호출하는 방법을 보여줍니다. updateSessionRules()의 절차도 동일합니다.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

정적 규칙 세트 업데이트

다음 예에서는 사용 가능한 정적 규칙 세트 수와 사용 설정된 정적 규칙 세트의 최대 수를 고려하면서 규칙 세트를 사용 설정 및 중지하는 방법을 보여줍니다. 필요한 정적 규칙 수가 허용된 수를 초과하는 경우 이 작업을 수행합니다. 이 작업을 수행하려면 일부 규칙 세트를 사용 중지한 상태로 일부 규칙 세트를 설치해야 합니다 (매니페스트 파일 내에서 "Enabled"를 false로 설정).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

규칙 예시

아래 예는 Chrome에서 확장 프로그램의 규칙에 우선순위를 지정하는 방법을 보여줍니다. 검토할 때 별도의 창에서 우선순위 지정 규칙을 여는 것이 좋습니다.

'priority' 키

이 예시에는 *://*.example.com/*에 대한 호스트 권한이 필요합니다.

특정 URL의 우선순위를 확인하려면 (개발자가 정의한) "priority" 키, "action" 키, "urlFilter" 키를 확인하세요. 이 예시는 아래에 표시된 규칙 파일 예시를 참조합니다.

https://google.com으로 이동
이 URL에는 ID가 1과 4인 두 가지 규칙이 적용됩니다. "block" 작업이 "redirect" 작업보다 우선순위가 높으므로 ID가 1인 규칙이 적용됩니다. 나머지 규칙은 더 긴 URL에 적용되므로 적용되지 않습니다.
https://google.com/1234로 이동
URL이 길어졌기 때문에 이제 ID가 1과 4인 규칙 외에도 ID가 2인 규칙이 일치합니다. "allow"의 우선순위가 "block" 및 "redirect"보다 높으므로 ID가 2인 규칙이 적용됩니다.
https://google.com/12345로 이동
네 가지 규칙이 모두 이 URL과 일치합니다. 개발자가 정의한 우선순위가 그룹에서 가장 높기 때문에 ID가 3인 규칙이 적용됩니다.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

리디렉션

아래 예시에서는 *://*.example.com/*에 대한 호스트 권한이 필요합니다.

다음 예는 example.com의 요청을 확장 프로그램 자체 내의 페이지로 리디렉션하는 방법을 보여줍니다. 확장 프로그램 경로 /a.jpg는 chrome-extension://EXTENSION_ID/a.jpg로 확인되며, 여기서 EXTENSION_ID는 확장 프로그램의 ID입니다. 이 작업을 실행하려면 매니페스트에서 /a.jpg를 웹 액세스 가능 리소스로 선언해야 합니다.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

다음은 "transform" 키를 사용하여 example.com의 하위 도메인으로 리디렉션합니다. 도메인 이름 앵커 ('||')를 사용하여 example.com의 모든 스키마가 포함된 요청을 가로챕니다. "transform"의 "scheme" 키는 하위 도메인으로의 리디렉션이 항상 'https'를 사용하도록 지정합니다.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

다음 예시에서는 정규 표현식을 사용하여 https://www.abc.xyz.com/path에서 https://abc.xyz.com/path로 리디렉션합니다. "regexFilter" 키에서 마침표가 이스케이프 처리되는 방식과 캡처 그룹이 'abc' 또는 'def'를 선택하는 방식을 확인합니다. "regexSubstitution" 키는 '\1'을 사용하여 정규 표현식의 첫 번째 반환된 일치 항목을 지정합니다. 이 경우 'abc'가 리디렉션된 URL에서 캡처되어 대체에 배치됩니다.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

헤더

다음 예에서는 기본 프레임과 모든 하위 프레임에서 모든 쿠키를 삭제합니다.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

유형

DomainType

요청이 시작된 프레임에 대해 퍼스트 파티인지 서드 파티인지 설명합니다. 요청이 시작된 프레임과 동일한 도메인 (eTLD+1)을 갖는 경우 퍼스트 파티 요청이라고 합니다.

열거형

"firstParty"
네트워크 요청이 시작된 프레임의 퍼스트 파티입니다.

'thirdParty'
네트워크 요청이 시작된 프레임의 서드 파티입니다.

ExtensionActionOptions

Chrome 88 이상

속성

  • displayActionCountAsBadgeText

    불리언 선택사항

    페이지의 작업 수를 확장 프로그램의 배지 텍스트로 자동 표시할지 여부입니다. 이 환경설정은 세션 간에 유지됩니다.

  • tabUpdate

    TabActionCountUpdate 선택사항

    Chrome 89 이상

    탭의 작업 수를 조정하는 방법에 관한 세부정보입니다.

GetDisabledRuleIdsOptions

Chrome 111 이상

속성

  • rulesetId

    문자열

    정적 Ruleset에 해당하는 ID입니다.

GetRulesFilter

Chrome 111 이상

속성

  • ruleIds

    number[] 선택사항

    지정된 경우 일치하는 ID가 있는 규칙만 포함됩니다.

HeaderInfo

Chrome 128 이상

속성

  • excludedValues

    string[] 선택사항

    지정된 경우 헤더가 있지만 해당 값에 이 목록의 요소가 하나 이상 포함되어 있으면 이 조건이 일치하지 않습니다. 이는 values와 동일한 일치 패턴 문법을 사용합니다.

  • 헤더

    문자열

    헤더의 이름입니다. 이 조건은 values 및 excludedValues가 모두 지정되지 않은 경우에만 이름과 일치합니다.

  • 값

    string[] 선택사항

    지정된 경우 헤더 값이 이 목록의 패턴 중 하나 이상과 일치하면 이 조건이 일치합니다. 이는 대소문자를 구분하지 않는 헤더 값 일치와 다음 구문을 지원합니다.

    '*' : 임의의 수의 문자와 일치합니다.

    '?' : 0개 또는 1개의 문자와 일치합니다.

    '*' 및 '?'는 백슬래시를 사용하여 이스케이프 처리할 수 있습니다(예: '\*' 및 '\?').

HeaderOperation

Chrome 86 이상

'modifyHeaders' 규칙에 가능한 작업을 설명합니다.

열거형

"append"
지정된 헤더에 새 항목을 추가합니다. 요청의 헤더를 수정할 때 이 작업은 특정 헤더에만 지원됩니다.

'set'
지정된 헤더에 새 값을 설정하고 이름이 같은 기존 헤더를 삭제합니다.

'remove'
지정된 헤더의 모든 항목을 삭제합니다.

IsRegexSupportedResult

Chrome 87 이상

속성

  • isSupported

    부울

  • reason

    UnsupportedRegexReason 선택사항

    정규 표현식이 지원되지 않는 이유를 지정합니다. isSupported가 false인 경우에만 제공됩니다.

MatchedRule

속성

  • ruleId

    숫자

    일치 규칙의 ID입니다.

  • rulesetId

    문자열

    이 규칙이 속한 Ruleset의 ID입니다. 동적 규칙 집합에서 발생한 규칙의 경우 DYNAMIC_RULESET_ID와 같습니다.

MatchedRuleInfo

속성

  • 규칙

    MatchedRule

  • tabId

    숫자

    탭이 아직 활성 상태인 경우 요청이 시작된 탭의 tabId입니다. 그 외의 경우 -1입니다.

  • timeStamp

    숫자

    규칙이 일치한 시간입니다. 타임스탬프는 시간의 JavaScript 규칙, 즉 에포크 이후의 밀리초 수에 해당합니다.

MatchedRuleInfoDebug

속성

MatchedRulesFilter

속성

  • minTimeStamp

    number 선택사항

    지정된 경우 지정된 타임스탬프 이후의 규칙만 일치시킵니다.

  • tabId

    number 선택사항

    지정된 경우 지정된 탭의 규칙만 일치시킵니다. -1로 설정하면 활성 탭과 연결되지 않은 규칙과 일치합니다.

ModifyHeaderInfo

Chrome 86 이상

속성

  • 헤더

    문자열

    수정할 헤더의 이름입니다.

  • 헤더에서 수행할 작업입니다.

  • 값

    문자열 선택사항

    헤더의 새 값입니다. append 및 set 작업에 지정해야 합니다.

QueryKeyValue

속성

  • 키

    문자열

  • replaceOnly

    불리언 선택사항

    Chrome 94 이상

    true이면 쿼리 키가 이미 있는 경우에만 대체됩니다. 그렇지 않으면 키가 누락된 경우에도 추가됩니다. 기본값은 false입니다.

  • 값

    문자열

QueryTransform

속성

  • addOrReplaceParams

    QueryKeyValue[] 선택사항

    추가하거나 바꿀 쿼리 키-값 쌍의 목록입니다.

  • removeParams

    string[] 선택사항

    삭제할 쿼리 키 목록입니다.

Redirect

속성

  • extensionPath

    문자열 선택사항

    확장 프로그램 디렉터리를 기준으로 하는 경로입니다. '/'로 시작해야 합니다.

  • regexSubstitution

    문자열 선택사항

    regexFilter를 지정하는 규칙의 대체 패턴입니다. URL 내에서 regexFilter와 처음 일치하는 항목이 이 패턴으로 대체됩니다. regexSubstitution 내에서 백슬래시로 이스케이프 처리된 숫자 (\1~\9)를 사용하여 해당 캡처 그룹을 삽입할 수 있습니다. \0은 전체 일치 텍스트를 나타냅니다.

  • 변환

    URLTransform 선택사항

    수행할 URL 변환입니다.

  • URL

    문자열 선택사항

    리디렉션 URL입니다. JavaScript URL로의 리디렉션은 허용되지 않습니다.

RegexOptions

Chrome 87 이상

속성

  • isCaseSensitive

    불리언 선택사항

    지정된 regex의 대소문자 구분 여부입니다. 기본값은 true입니다.

  • regex

    문자열

    확인할 정규 표현식입니다.

  • requireCapturing

    불리언 선택사항

    지정된 regex에 캡처가 필요한지 여부입니다. 캡처는 regexSubstition 작업을 지정하는 리디렉션 규칙에만 필요합니다. 기본값은 false입니다.

RequestDetails

속성

  • documentId

    문자열 선택사항

    Chrome 106 이상

    이 요청이 프레임에 대한 요청인 경우 프레임 문서의 고유 식별자입니다.

  • documentLifecycle

    DocumentLifecycle 선택사항

    Chrome 106 이상

    프레임 문서의 수명 주기(요청이 프레임에 대한 것인 경우)

  • frameId

    숫자

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

  • frameType

    FrameType 선택사항

    Chrome 106 이상

    이 요청이 프레임에 대한 요청인 경우 프레임의 유형입니다.

  • initiator

    문자열 선택사항

    요청이 시작된 출처입니다. 리디렉션을 통해 변경되지 않습니다. 불투명한 출처인 경우 'null' 문자열이 사용됩니다.

  • method

    문자열

    표준 HTTP 메서드입니다.

  • parentDocumentId

    문자열 선택사항

    Chrome 106 이상

    이 요청이 프레임에 대한 것이고 상위 요소가 있는 경우 프레임의 상위 문서에 대한 고유 식별자입니다.

  • parentFrameId

    숫자

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

  • requestId

    문자열

    요청 ID입니다. 요청 ID는 브라우저 세션 내에서 고유합니다.

  • tabId

    숫자

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

  • 유형

    ResourceType

    요청의 리소스 유형입니다.

  • URL

    문자열

    요청의 URL입니다.

RequestMethod

Chrome 91 이상

네트워크 요청의 HTTP 요청 메서드를 설명합니다.

열거형

'connect'

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

네트워크 요청의 리소스 유형을 설명합니다.

열거형

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

'webbundle'

"other"

Rule

속성

  • action

    RuleAction

    이 규칙이 일치할 때 수행할 작업입니다.

  • 상태

    RuleCondition

    이 규칙이 트리거되는 조건입니다.

  • id

    숫자

    규칙을 고유하게 식별하는 ID입니다. 필수이며 1 이상이어야 합니다.

  • 우선순위

    number 선택사항

    규칙 우선순위입니다. 기본값은 1입니다. 지정된 경우 1 이상이어야 합니다.

RuleAction

속성

  • 리디렉션

    리디렉션 선택사항

    리디렉션이 수행되는 방식을 설명합니다. 리디렉션 규칙에만 유효합니다.

  • requestHeaders

    ModifyHeaderInfo[] 선택사항

    Chrome 86 이상

    요청에 대해 수정할 요청 헤더입니다. RuleActionType이 'modifyHeaders'인 경우에만 유효합니다.

  • responseHeaders

    ModifyHeaderInfo[] 선택사항

    Chrome 86 이상

    요청에 대해 수정할 응답 헤더입니다. RuleActionType이 'modifyHeaders'인 경우에만 유효합니다.

  • 수행할 작업 유형입니다.

RuleActionType

지정된 RuleCondition이 일치하는 경우 수행할 작업 종류를 설명합니다.

열거형

'block'
네트워크 요청을 차단합니다.

'redirect'
네트워크 요청을 리디렉션합니다.

"allow"
네트워크 요청을 허용합니다. 요청과 일치하는 허용 규칙이 있으면 요청이 가로채지지 않습니다.

"upgradeScheme"
요청이 http 또는 ftp인 경우 네트워크 요청 URL의 스키마를 https로 업그레이드합니다.

'modifyHeaders'
네트워크 요청에서 요청/응답 헤더를 수정합니다.

'allowAllRequests'
프레임 요청 자체를 포함하여 프레임 계층 구조 내의 모든 요청을 허용합니다.

RuleCondition

속성

  • domainType

    DomainType 선택사항

    네트워크 요청이 시작된 도메인에 대해 퍼스트 파티인지 서드 파티인지 지정합니다. 생략하면 모든 요청이 수락됩니다.

  • 도메인

    string[] 선택사항

    Chrome 101부터 지원 중단됨

    대신 initiatorDomains 사용

    이 규칙은 domains 목록에서 시작된 네트워크 요청과만 일치합니다.

  • excludedDomains

    string[] 선택사항

    Chrome 101부터 지원 중단됨

    대신 excludedInitiatorDomains 사용

    이 규칙은 excludedDomains 목록에서 시작된 네트워크 요청과 일치하지 않습니다.

  • excludedInitiatorDomains

    string[] 선택사항

    Chrome 101 이상

    이 규칙은 excludedInitiatorDomains 목록에서 시작된 네트워크 요청과 일치하지 않습니다. 목록이 비어 있거나 생략된 경우 제외되는 도메인이 없습니다. 이 설정은 initiatorDomains보다 우선 적용됩니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 이는 요청 URL이 아닌 요청 개시자와 일치합니다.
    • 나열된 도메인의 하위 도메인도 제외됩니다.
  • excludedRequestDomains

    string[] 선택사항

    Chrome 101 이상

    도메인이 excludedRequestDomains 목록의 도메인과 일치하는 경우 규칙이 네트워크 요청과 일치하지 않습니다. 목록이 비어 있거나 생략된 경우 제외되는 도메인이 없습니다. 이 설정은 requestDomains보다 우선 적용됩니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 나열된 도메인의 하위 도메인도 제외됩니다.
  • excludedRequestMethods

    RequestMethod[] 선택사항

    Chrome 91 이상

    규칙과 일치하지 않는 요청 메서드 목록입니다. requestMethods 및 excludedRequestMethods 중 하나만 지정해야 합니다. 둘 다 지정하지 않으면 모든 요청 메서드가 일치합니다.

  • excludedResourceTypes

    ResourceType[] 선택사항

    규칙과 일치하지 않는 리소스 유형 목록입니다. resourceTypes 및 excludedResourceTypes 중 하나만 지정해야 합니다. 둘 다 지정하지 않으면 'main_frame'을 제외한 모든 리소스 유형이 차단됩니다.

  • excludedResponseHeaders

    HeaderInfo[] 선택사항

    Chrome 128 이상

    요청이 이 목록의 응답 헤더 조건과 일치하는 경우 규칙이 일치하지 않습니다 (지정된 경우). excludedResponseHeaders 및 responseHeaders가 모두 지정된 경우 excludedResponseHeaders 속성이 우선 적용됩니다.

  • excludedTabIds

    number[] 선택사항

    Chrome 92 이상

    규칙과 일치하지 않아야 하는 tabs.Tab.id 목록입니다. ID가 tabs.TAB_ID_NONE이면 탭에서 시작되지 않은 요청은 제외됩니다. 세션 범위 규칙에만 지원됩니다.

  • excludedTopDomains

    string[] 선택사항

    Chrome 145 이상

    연결된 최상위 프레임의 도메인이 excludedTopDomains 목록의 도메인과 일치하는 경우 규칙이 네트워크 요청과 일치하지 않습니다. 목록이 비어 있거나 생략된 경우 제외되는 도메인이 없습니다. 이 설정은 topDomains보다 우선 적용됩니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 나열된 도메인의 하위 도메인도 제외됩니다.
    • 연결된 최상위 프레임이 없는 요청 (예: ServiceWorker에서 시작된 요청)의 경우 요청 개시자의 도메인이 대신 고려됩니다.
  • initiatorDomains

    string[] 선택사항

    Chrome 101 이상

    이 규칙은 initiatorDomains 목록에서 시작된 네트워크 요청과만 일치합니다. 목록을 생략하면 모든 도메인의 요청에 규칙이 적용됩니다. 빈 목록은 허용되지 않습니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 이는 요청 URL이 아닌 요청 개시자와 일치합니다.
    • 나열된 도메인의 하위 도메인도 일치합니다.
  • isUrlFilterCaseSensitive

    불리언 선택사항

    urlFilter 또는 regexFilter (지정된 항목)의 대소문자 구분 여부입니다. 기본값은 false입니다.

  • regexFilter

    문자열 선택사항

    네트워크 요청 URL과 일치하는 정규 표현식입니다. 이는 RE2 문법을 따릅니다.

    참고: urlFilter 또는 regexFilter 중 하나만 지정할 수 있습니다.

    참고: regexFilter는 ASCII 문자로만 구성되어야 합니다. 이는 호스트가 퓨니코드 형식으로 인코딩된 URL (국제화된 도메인의 경우)과 일치하며, 다른 ASCII가 아닌 문자는 UTF-8로 URL 인코딩됩니다.

  • requestDomains

    string[] 선택사항

    Chrome 101 이상

    이 규칙은 도메인이 requestDomains 목록의 도메인과 일치하는 경우에만 네트워크 요청과 일치합니다. 목록을 생략하면 모든 도메인의 요청에 규칙이 적용됩니다. 빈 목록은 허용되지 않습니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 나열된 도메인의 하위 도메인도 일치합니다.
  • requestMethods

    RequestMethod[] 선택사항

    Chrome 91 이상

    규칙과 일치할 수 있는 HTTP 요청 메서드 목록입니다. 빈 목록은 허용되지 않습니다.

    참고: requestMethods 규칙 조건을 지정하면 HTTP(S)가 아닌 요청도 제외되지만 excludedRequestMethods를 지정하면 제외되지 않습니다.

  • resourceTypes

    ResourceType[] 선택사항

    규칙과 일치할 수 있는 리소스 유형 목록입니다. 빈 목록은 허용되지 않습니다.

    참고: allowAllRequests 규칙에 지정해야 하며 sub_frame 및 main_frame 리소스 유형만 포함할 수 있습니다.

  • responseHeaders

    HeaderInfo[] 선택사항

    Chrome 128 이상

    요청이 이 목록의 응답 헤더 조건과 일치하는 경우 규칙이 일치합니다 (지정된 경우).

  • tabIds

    number[] 선택사항

    Chrome 92 이상

    규칙과 일치해야 하는 tabs.Tab.id 목록입니다. tabs.TAB_ID_NONE ID는 탭에서 시작되지 않은 요청과 일치합니다. 빈 목록은 허용되지 않습니다. 세션 범위 규칙에만 지원됩니다.

  • topDomains

    string[] 선택사항

    Chrome 145 이상

    연결된 최상위 프레임의 도메인이 topDomains 목록의 도메인과 일치하는 경우에만 규칙이 네트워크 요청과 일치합니다. 목록을 생략하면 규칙이 모든 최상위 프레임 도메인과 연결된 요청에 적용됩니다. 빈 목록은 허용되지 않습니다.

    참고:

    • 'a.example.com'과 같은 하위 도메인도 허용됩니다.
    • 항목은 ASCII 문자로만 구성되어야 합니다.
    • 국제화된 도메인에는 퓨니코드 인코딩을 사용합니다.
    • 나열된 도메인의 하위 도메인도 일치합니다.
    • 연결된 최상위 프레임이 없는 요청 (예: ServiceWorker에서 시작된 요청)의 경우 요청 개시자의 도메인이 대신 고려됩니다.
  • urlFilter

    문자열 선택사항

    네트워크 요청 URL과 일치하는 패턴입니다. 지원되는 구성:

    '*' : 와일드 카드: 임의의 수의 문자와 일치합니다.

    '|' : 왼쪽/오른쪽 앵커: 패턴의 양쪽 끝에 사용되는 경우 각각 URL의 시작/끝을 지정합니다.

    '||' : 도메인 이름 앵커: 패턴의 시작 부분에 사용되는 경우 URL의 (하위) 도메인 시작을 지정합니다.

    '^' : 구분자 문자: 문자, 숫자 또는 _, -, ., % 중 하나를 제외한 모든 문자와 일치합니다. 이는 URL의 끝과도 일치합니다.

    따라서 urlFilter은 (선택사항인 왼쪽/도메인 이름 앵커) + 패턴 + (선택사항인 오른쪽 앵커)로 구성됩니다.

    생략하면 모든 URL이 일치합니다. 빈 문자열은 허용되지 않습니다.

    ||*로 시작하는 패턴은 허용되지 않습니다. 대신 *를 사용합니다.

    참고: urlFilter 또는 regexFilter 중 하나만 지정할 수 있습니다.

    참고: urlFilter는 ASCII 문자로만 구성되어야 합니다. 이는 호스트가 퓨니코드 형식으로 인코딩된 URL (국제화된 도메인의 경우)과 일치하며, 다른 ASCII가 아닌 문자는 UTF-8로 URL 인코딩됩니다. 예를 들어 요청 URL이 http://abc.рф?q=ф인 경우 urlFilter은 URL http://abc.xn--p1ai/?q=%D1%84와 일치합니다.

RuleConditionKeys

Chrome 145 이상

열거형

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

속성

  • 운영중

    부울

    규칙 세트가 기본적으로 사용 설정되어 있는지 여부입니다.

  • id

    문자열

    규칙 세트를 고유하게 식별하는 비어 있지 않은 문자열입니다. '_'로 시작하는 ID는 내부용으로 예약되어 있습니다.

  • 경로

    문자열

    확장 프로그램 디렉터리를 기준으로 한 JSON 규칙 세트의 경로입니다.

RulesMatchedDetails

속성

  • rulesMatchedInfo

    MatchedRuleInfo[]

    지정된 필터와 일치하는 규칙입니다.

TabActionCountUpdate

Chrome 89 이상

속성

  • 증가

    숫자

    탭의 작업 수를 늘릴 값입니다. 음수 값은 개수를 감소시킵니다.

  • tabId

    숫자

    작업 수를 업데이트할 탭입니다.

TestMatchOutcomeResult

Chrome 103 이상

속성

  • matchedRules

    MatchedRule[]

    가상 요청과 일치하는 규칙 (있는 경우)입니다.

TestMatchRequestDetails

Chrome 103 이상

속성

  • initiator

    문자열 선택사항

    가상 요청의 이니시에이터 URL (있는 경우)입니다.

  • method

    RequestMethod 선택사항

    가상 요청의 표준 HTTP 메서드입니다. HTTP 요청의 경우 기본값은 'get'이며 HTTP가 아닌 요청의 경우 무시됩니다.

  • responseHeaders

    객체 선택사항

    Chrome 129 이상

    요청이 전송되기 전에 차단되거나 리디렉션되지 않는 경우 가상 응답에서 제공하는 헤더입니다. 헤더 이름을 문자열 값 목록에 매핑하는 객체로 표현됩니다. 지정하지 않으면 가상 응답은 빈 응답 헤더를 반환하며, 이는 헤더가 없는 경우와 일치하는 규칙과 일치할 수 있습니다. 예: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number 선택사항

    가상 요청이 발생하는 탭의 ID입니다. 실제 탭 ID와 일치할 필요는 없습니다. 기본값은 -1이며, 이는 요청이 탭과 관련이 없음을 의미합니다.

  • topUrl

    문자열 선택사항

    Chrome 145 이상

    요청과 연결된 최상위 프레임 URL (있는 경우)입니다.

  • 유형

    ResourceType

    가상 요청의 리소스 유형입니다.

  • URL

    문자열

    가상 요청의 URL입니다.

UnsupportedRegexReason

Chrome 87 이상

지정된 정규 표현식이 지원되지 않는 이유를 설명합니다.

열거형

"syntaxError"
정규 표현식의 문법이 잘못되었거나 RE2 문법에서 사용할 수 없는 기능을 사용합니다.

'memoryLimitExceeded'
정규 표현식이 메모리 한도를 초과합니다.

UpdateRuleOptions

Chrome 87 이상

속성

  • addRules

    Rule[] 선택사항

    추가할 규칙입니다.

  • removeRuleIds

    number[] 선택사항

    삭제할 규칙의 ID입니다. 잘못된 ID는 무시됩니다.

UpdateRulesetOptions

Chrome 87 이상

속성

  • disableRulesetIds

    string[] 선택사항

    사용 중지해야 하는 정적 Ruleset에 해당하는 ID 집합입니다.

  • enableRulesetIds

    string[] 선택사항

    사용 설정해야 하는 정적 Ruleset에 해당하는 ID 집합입니다.

UpdateStaticRulesOptions

Chrome 111 이상

속성

  • disableRuleIds

    number[] 선택사항

    사용 중지할 Ruleset의 규칙에 해당하는 ID 집합입니다.

  • enableRuleIds

    number[] 선택사항

    사용 설정할 Ruleset의 규칙에 해당하는 ID 집합입니다.

  • rulesetId

    문자열

    정적 Ruleset에 해당하는 ID입니다.

URLTransform

속성

  • fragment

    문자열 선택사항

    요청의 새 프래그먼트입니다. 비어 있거나(이 경우 기존 프래그먼트가 삭제됨) '#'로 시작해야 합니다.

  • 호스트

    문자열 선택사항

    요청의 새 호스트입니다.

  • 비밀번호

    문자열 선택사항

    요청의 새 비밀번호입니다.

  • 경로

    문자열 선택사항

    요청의 새 경로입니다. 비어 있으면 기존 경로가 삭제됩니다.

  • 포트

    문자열 선택사항

    요청의 새 포트입니다. 비어 있으면 기존 포트가 삭제됩니다.

  • query

    문자열 선택사항

    요청의 새 쿼리입니다. 비어 있거나(이 경우 기존 쿼리가 삭제됨) '?'로 시작해야 합니다.

  • queryTransform

    QueryTransform 선택사항

    쿼리 키-값 쌍을 추가, 삭제 또는 교체합니다.

  • 스키마

    문자열 선택사항

    요청의 새 스키마입니다. 허용되는 값은 'http', 'https', 'ftp', 'chrome-extension'입니다.

  • 사용자 이름

    문자열 선택사항

    요청의 새 사용자 이름입니다.

속성

DYNAMIC_RULESET_ID

확장 프로그램에서 추가한 동적 규칙의 규칙 세트 ID입니다.

값

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules 호출을 실행할 수 있는 시간 간격(분)입니다. 추가 호출은 즉시 실패하고 runtime.lastError를 설정합니다. 참고: 사용자 동작과 연결된 getMatchedRules 호출은 할당량에서 제외됩니다.

값

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 이상

사용 설정된 정적 규칙 세트에서 확장 프로그램에 보장되는 최소 정적 규칙 수입니다. 이 한도를 초과하는 규칙은 전역 정적 규칙 한도에 반영됩니다.

값

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

GETMATCHEDRULES_QUOTA_INTERVAL 기간 내에 getMatchedRules를 호출할 수 있는 횟수입니다.

값

20

MAX_NUMBER_OF_DYNAMIC_RULES

확장 프로그램에서 추가할 수 있는 동적 규칙의 최대 개수입니다.

값

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 이상

확장 프로그램이 한 번에 사용 설정할 수 있는 정적 Rulesets의 최대 개수입니다.

값

50

MAX_NUMBER_OF_REGEX_RULES

확장 프로그램에서 추가할 수 있는 정규 표현식 규칙의 최대 개수입니다. 이 한도는 동적 규칙 집합과 규칙 리소스 파일에 지정된 규칙에 대해 별도로 평가됩니다.

값

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 이상

확장 프로그램에서 추가할 수 있는 세션 범위 규칙의 최대 개수입니다.

값

5,000

MAX_NUMBER_OF_STATIC_RULESETS

확장 프로그램이 "rule_resources" 매니페스트 키의 일부로 지정할 수 있는 최대 정적 Rulesets 수입니다.

값

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 이상

확장 프로그램에서 추가할 수 있는 '안전하지 않은' 동적 규칙의 최대 개수입니다.

값

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 이상

확장 프로그램에서 추가할 수 있는 '안전하지 않은' 세션 범위 규칙의 최대 개수입니다.

값

5,000

SESSION_RULESET_ID

Chrome 90 이상

확장 프로그램에서 추가한 세션 범위 규칙의 규칙 세트 ID입니다.

값

"_session"

메서드

getAvailableStaticRuleCount()

Promise Chrome 89 이상 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

전역 정적 규칙 한도에 도달하기 전에 확장 프로그램에서 사용 설정할 수 있는 정적 규칙의 수를 반환합니다.

매개변수

  • callback

    함수 선택사항

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

    (count: number) => void

    • 개수

      숫자

반환 값

  • <number> 약속

    Chrome 91 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getDisabledRuleIds()

Promise Chrome 111 이상 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

지정된 Ruleset에서 현재 사용 중지된 정적 규칙 목록을 반환합니다.

매개변수

  • 쿼리할 규칙 집합을 지정합니다.

  • callback

    함수 선택사항

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

반환 값

  • 약속<number[]>

    해당 규칙 세트의 사용 중지된 규칙에 해당하는 ID 목록으로 확인되는 프로미스입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

확장 프로그램의 현재 동적 규칙 집합을 반환합니다. 호출자는 선택적으로 filter를 지정하여 가져온 규칙 목록을 필터링할 수 있습니다.

매개변수

  • filter

    GetRulesFilter 선택사항

    Chrome 111 이상

    가져온 규칙 목록을 필터링하는 객체입니다.

  • callback

    함수 선택사항

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

    (rules: Rule[]) => void

반환 값

  • Promise<Rule[]>

    Chrome 91 이상

    동적 규칙 집합으로 확인되는 프로미스입니다. 일시적인 내부 오류가 발생하면 프로미스가 거부될 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

현재 사용 설정된 정적 규칙 세트의 ID를 반환합니다.

매개변수

  • callback

    함수 선택사항

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

    (rulesetIds: string[]) => void

    • rulesetIds

      문자열[]

반환 값

  • Promise<string[]>

    Chrome 91 이상

    ID 목록으로 확인되는 프로미스입니다. 여기서 각 ID는 사용 설정된 정적 Ruleset에 해당합니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getMatchedRules()

Promise 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): Promise<RulesMatchedDetails>

확장 프로그램과 일치하는 모든 규칙을 반환합니다. 호출자는 선택적으로 filter를 지정하여 일치하는 규칙 목록을 필터링할 수 있습니다. 이 메서드는 "declarativeNetRequestFeedback" 권한이 있거나 filter에 지정된 tabId에 대해 "activeTab" 권한이 부여된 확장 프로그램에서만 사용할 수 있습니다. 참고: 5분 이전에 일치한 활성 문서와 연결되지 않은 규칙은 반환되지 않습니다.

매개변수

반환 값

  • Chrome 91 이상

    일치하는 규칙 목록을 가져오면 확인되는 프로미스입니다. 오류가 발생하면 프로미스가 거부됩니다. 권한이 부족하거나 할당량을 초과하는 등 여러 가지 이유로 이 문제가 발생할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getSessionRules()

Promise Chrome 90 이상 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

확장 프로그램의 현재 세션 범위 규칙 집합을 반환합니다. 호출자는 선택적으로 filter를 지정하여 가져온 규칙 목록을 필터링할 수 있습니다.

매개변수

  • filter

    GetRulesFilter 선택사항

    Chrome 111 이상

    가져온 규칙 목록을 필터링하는 객체입니다.

  • callback

    함수 선택사항

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

    (rules: Rule[]) => void

반환 값

  • Promise<Rule[]>

    Chrome 91 이상

    세션 범위 규칙 집합으로 확인되는 프로미스입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

isRegexSupported()

Promise Chrome 87 이상 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

지정된 정규 표현식이 regexFilter 규칙 조건으로 지원되는지 확인합니다.

매개변수

반환 값

  • Chrome 91 이상

    정규 표현식이 지원되는지 여부와 지원되지 않는 경우 그 이유로 구성된 세부정보로 확인되는 프로미스입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setExtensionActionOptions()

Promise Chrome 88 이상 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

탭의 작업 수가 확장 프로그램 작업의 배지 텍스트로 표시되어야 하는지 구성하고 해당 작업 수를 늘리는 방법을 제공합니다.

매개변수

  • callback

    함수 선택사항

    Chrome 89 이상

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

    () => void

반환 값

  • 약속<void>

    Chrome 91 이상

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

testMatchOutcome()

Promise Chrome 103 이상 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

확장 프로그램의 declarativeNetRequest 규칙이 가상의 요청과 일치하는지 확인합니다. 참고: 확장 프로그램 개발 중에만 사용하도록 설계되었으므로 압축 해제된 확장 프로그램에만 사용할 수 있습니다.

매개변수

반환 값

  • 일치하는 규칙의 세부정보로 확인되는 프로미스입니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

확장 프로그램의 현재 동적 규칙 집합을 수정합니다. options.removeRuleIds에 나열된 ID가 있는 규칙이 먼저 삭제된 후 options.addRules에 지정된 규칙이 추가됩니다. 참고:

  • 이 업데이트는 단일 원자적 작업으로 수행됩니다. 즉, 지정된 모든 규칙이 추가 및 삭제되거나 오류가 반환됩니다.
  • 이러한 규칙은 브라우저 세션과 확장 프로그램 업데이트 전반에 걸쳐 유지됩니다.
  • 확장 프로그램 패키지의 일부로 지정된 정적 규칙은 이 함수를 사용하여 삭제할 수 없습니다.
  • MAX_NUMBER_OF_DYNAMIC_RULES는 확장 프로그램에서 추가할 수 있는 최대 동적 규칙 수입니다. 안전하지 않은 규칙 수는 MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES개를 초과할 수 없습니다.

매개변수

  • Chrome 87 이상
  • callback

    함수 선택사항

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

    () => void

반환 값

  • 약속<void>

    Chrome 91 이상

    업데이트가 완료되면 확인되는 프로미스입니다. 오류가 발생하면 프로미스가 거부되고 규칙 집합이 변경되지 않습니다. 이는 잘못된 규칙 형식, 중복 규칙 ID, 규칙 수 한도 초과, 내부 오류 등 여러 가지 이유로 발생할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

updateEnabledRulesets()

Promise 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): Promise<void>

확장 프로그램에 사용 설정된 정적 규칙 세트 집합을 업데이트합니다. options.disableRulesetIds에 ID가 나열된 규칙 세트가 먼저 삭제된 후 options.enableRulesetIds에 나열된 규칙 세트가 추가됩니다. 사용 설정된 정적 규칙 세트 집합은 세션 간에 유지되지만 확장 프로그램 업데이트 간에는 유지되지 않습니다. 즉, rule_resources 매니페스트 키는 각 확장 프로그램 업데이트에서 사용 설정된 정적 규칙 세트 집합을 결정합니다.

매개변수

  • Chrome 87 이상
  • callback

    함수 선택사항

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

    () => void

반환 값

  • 약속<void>

    Chrome 91 이상

    업데이트가 완료되면 확인되는 프로미스입니다. 오류가 발생하면 프로미스가 거부되고 사용 설정된 규칙 세트가 변경되지 않습니다. 이는 잘못된 규칙 세트 ID, 규칙 수 한도 초과, 내부 오류 등 여러 가지 이유로 발생할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

updateSessionRules()

Promise Chrome 90 이상 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

확장 프로그램의 현재 세션 범위 규칙 집합을 수정합니다. options.removeRuleIds에 나열된 ID가 있는 규칙이 먼저 삭제된 후 options.addRules에 지정된 규칙이 추가됩니다. 참고:

  • 이 업데이트는 단일 원자적 작업으로 수행됩니다. 즉, 지정된 모든 규칙이 추가 및 삭제되거나 오류가 반환됩니다.
  • 이러한 규칙은 세션 간에 유지되지 않으며 메모리에 백업됩니다.
  • MAX_NUMBER_OF_SESSION_RULES는 확장 프로그램에서 추가할 수 있는 최대 세션 규칙 수입니다.

매개변수

  • callback

    함수 선택사항

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

    () => void

반환 값

  • 약속<void>

    Chrome 91 이상

    업데이트가 완료되면 확인되는 프로미스입니다. 오류가 발생하면 프로미스가 거부되고 규칙 집합이 변경되지 않습니다. 이는 잘못된 규칙 형식, 중복된 규칙 ID, 규칙 수 한도 초과 등 여러 가지 이유로 발생할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

updateStaticRules()

Promise Chrome 111 이상 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

Ruleset에서 개별 정적 규칙을 사용 중지하거나 사용 설정합니다. 사용 중지된 Ruleset에 속한 규칙의 변경사항은 다음에 사용 설정될 때 적용됩니다.

매개변수

  • callback

    함수 선택사항

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

    () => void

반환 값

  • 약속<void>

    업데이트가 완료되면 확인되는 프로미스입니다. 오류가 발생하면 프로미스가 거부되고 사용 설정된 정적 규칙은 변경되지 않습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

이벤트

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

규칙이 요청과 일치할 때 실행됩니다. 디버깅 목적으로만 사용되므로 "declarativeNetRequestFeedback" 권한이 있는 압축해제된 확장 프로그램에만 사용할 수 있습니다.

매개변수