chrome.declarativeWebRequest

説明

注: この API は非推奨になりました。代わりに、declarativeNetRequest API をご覧ください。chrome.declarativeWebRequest API を使用すると、送信中のリクエストを傍受、ブロック、変更できます。登録したルールの評価は、JavaScript エンジンではなくブラウザで行われるため、ラウンドトリップ レイテンシが短縮されて効率が高まるので、chrome.webRequest API を使用するよりも大幅に高速です。

権限

declarativeWebRequest

この API を使用するには、ホスト権限とともに、拡張機能のマニフェストで「declarativeWebRequest」権限を宣言する必要があります。

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

対象

Beta チャンネル ≤ 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 にリダイレクトするルールを設定できません。

ルール

Declarative Web Request API は、Declarative API のコンセプトに沿っています。ルールは chrome.declarativeWebRequest.onRequest イベント オブジェクトに登録できます。

Declarative Web Request API は、RequestMatcher という 1 種類の照合条件をサポートしています。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 へのすべてのリクエストをキャンセルするには、2 つ目の条件を追加します。各条件は、指定されたすべてのアクションをトリガーするのに十分です。

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]);

条件とアクションの評価

Declarative Web Request API は、Web Request 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

リクエストに Cookie を追加します。同じ名前の別の Cookie がすでに存在する場合は、Cookie をオーバーライドします。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

AddResponseCookie

レスポンスに Cookie を追加します。同じ名前の別の Cookie がすでに存在する場合は、Cookie をオーバーライドします。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

AddResponseHeader

このウェブ リクエストのレスポンスにレスポンス ヘッダーを追加します。複数のレスポンス ヘッダーが同じ名前を共有している可能性があるため、レスポンス ヘッダーを置き換えるには、まずレスポンス ヘッダーを削除してから、新しいレスポンス ヘッダーを追加する必要があります。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • name

    文字列

    HTTP レスポンス ヘッダー名。

  • 値

    文字列

    HTTP レスポンス ヘッダー値。

CancelRequest

ネットワーク リクエストをキャンセルする宣言型イベント アクション。

プロパティ

EditRequestCookie

リクエストの 1 つ以上の Cookie を編集します。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • filter

    RequestCookie

    変更される Cookie のフィルタ。空のエントリはすべて無視されます。

  • 更新日時

    RequestCookie

    フィルタに一致した Cookie でオーバーライドされる属性。空の文字列に設定された属性は削除されます。

EditResponseCookie

レスポンスの 1 つ以上の Cookie を編集します。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • 変更される Cookie のフィルタ。空のエントリはすべて無視されます。

  • 更新日時

    ResponseCookie

    フィルタに一致した Cookie でオーバーライドされる属性。空の文字列に設定された属性は削除されます。

FilterResponseCookie

HTTP レスポンス内の Cookie のフィルタ。

プロパティ

  • ageLowerBound

    number 省略可

    Cookie の有効期間の下限（現在時刻から指定した秒数後）を含みます。有効期限が「現在 + ageLowerBound」以降に設定されている Cookie のみがこの条件を満たします。セッション Cookie はこのフィルタの条件を満たしていません。Cookie の有効期間は、Cookie 属性の「max-age」または「expires」のいずれかから計算されます。両方が指定されている場合は、'max-age' を使用して Cookie の有効期間が計算されます。

  • ageUpperBound

    number 省略可

    Cookie の有効期間の上限（現在時刻から数えた秒単位で指定）。この条件を満たすのは、有効期限の日時が [現在、現在 + ageUpperBound] の範囲内にある Cookie のみです。セッション Cookie と有効期限が過去の日時の Cookie は、このフィルタの条件を満たしません。Cookie の有効期間は、Cookie 属性の「max-age」または「expires」のいずれかから計算されます。両方が指定されている場合は、'max-age' を使用して Cookie の有効期間が計算されます。

  • ドメイン

    文字列 省略可

    Domain Cookie 属性の値。

  • 有効期限

    文字列 省略可

    Expires Cookie 属性の値。

  • httpOnly

    文字列 省略可

    HttpOnly Cookie 属性の有無。

  • maxAge

    number 省略可

    Max-Age Cookie 属性の値

  • name

    文字列 省略可

    Cookie の名前。

  • パス

    文字列 省略可

    Path Cookie 属性の値。

  • 安全

    文字列 省略可

    Secure Cookie 属性の有無。

  • sessionCookie

    boolean 省略可

    セッション Cookie をフィルタします。セッション Cookie には、max-age 属性または expires 属性で指定された有効期間がありません。

  • 値

    文字列 省略可

    Cookie の値。二重引用符で囲まれている場合があります。

HeaderFilter

さまざまな条件でリクエスト ヘッダーをフィルタします。複数の条件は連言として評価されます。

プロパティ

  • nameContains

    string | string[] 省略可

    ヘッダー名に指定されたすべての文字列が含まれている場合に一致します。

  • nameEquals

    文字列 省略可

    ヘッダー名が指定された文字列と等しい場合に一致します。

  • namePrefix

    文字列 省略可

    ヘッダー名が指定された文字列で始まる場合に一致します。

  • nameSuffix

    文字列 省略可

    ヘッダー名が指定された文字列で終わる場合に一致します。

  • valueContains

    string | string[] 省略可

    ヘッダー値に指定されたすべての文字列が含まれている場合に一致します。

  • valueEquals

    文字列 省略可

    ヘッダー値が指定された文字列と等しい場合に一致します。

  • valuePrefix

    文字列 省略可

    ヘッダー値が指定された文字列で始まる場合に一致します。

  • valueSuffix

    文字列 省略可

    ヘッダー値が指定された文字列で終わる場合に一致します。

IgnoreRules

指定した条件に一致するすべてのルールをマスクします。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • hasTag

    文字列 省略可

    設定すると、指定されたタグを含むルールは無視されます。この無視は永続化されず、同じネットワーク リクエスト ステージのルールとそのアクションにのみ影響します。ルールは優先度の降順で実行されます。この操作は、現在のルールよりも優先度の低いルールに影響します。同じ優先度のルールは無視される場合と無視されない場合があります。

  • lowerPriorityThan

    number 省略可

    設定されている場合、指定された値よりも優先度の低いルールは無視されます。この境界は永続化されず、同じネットワーク リクエスト ステージのルールとそのアクションにのみ影響します。

RedirectByRegEx

URL に正規表現を適用してリクエストをリダイレクトします。正規表現では RE2 構文を使用します。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • from

    文字列

    キャプチャ グループを含むことができる一致パターン。JavaScript の正規表現に近づけるため、RE2 構文（\1、\2、...）ではなく Perl 構文（$1、$2、...）でキャプチャ グループが参照されます。

  • に

    文字列

    宛先パターン。

RedirectRequest

ネットワーク リクエストをリダイレクトする宣言型イベント アクション。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • redirectUrl

    文字列

    リクエストがリダイレクトされる宛先。

RedirectToEmptyDocument

ネットワーク リクエストを空のドキュメントにリダイレクトする宣言型イベント アクション。

プロパティ

RedirectToTransparentImage

ネットワーク リクエストを透明な画像にリダイレクトする宣言型イベント アクション。

プロパティ

RemoveRequestCookie

リクエストの 1 つ以上の Cookie を削除します。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

RemoveRequestHeader

指定された名前のリクエスト ヘッダーを削除します。同じリクエストで同じヘッダー名を使用して SetRequestHeader と RemoveRequestHeader を使用しないでください。各リクエスト ヘッダー名は、各リクエストで 1 回だけ使用されます。

プロパティ

RemoveResponseCookie

レスポンスの 1 つ以上の Cookie を削除します。計算コストが低いため、Cookies API を使用することをおすすめします。

プロパティ

RemoveResponseHeader

指定された名前と値のレスポンス ヘッダーをすべて削除します。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • name

    文字列

    HTTP リクエスト ヘッダー名（大文字と小文字を区別しない）。

  • 値

    文字列 省略可

    HTTP リクエスト ヘッダー値（大文字と小文字は区別されません）。

RequestCookie

HTTP リクエスト内の Cookie のフィルタまたは仕様。

プロパティ

  • name

    文字列 省略可

    Cookie の名前。

  • 値

    文字列 省略可

    Cookie の値。二重引用符で囲まれている場合があります。

RequestMatcher

さまざまな条件でネットワーク イベントを照合します。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • contentType

    string[] 省略可

    レスポンスの MIME メディアタイプ（HTTP Content-Type ヘッダーから）がリストに含まれている場合に一致します。

  • excludeContentType

    string[] 省略可

    レスポンスの MIME メディアタイプ（HTTP Content-Type ヘッダーから）がリストに含まれていない場合に一致します。

  • excludeRequestHeaders

    HeaderFilter[] 省略可

    リクエスト ヘッダーのいずれも HeaderFilter のいずれとも一致しない場合に一致します。

  • excludeResponseHeaders

    HeaderFilter[] 省略可

    レスポンス ヘッダーのいずれも HeaderFilter のいずれとも一致しない場合に一致します。

  • firstPartyForCookiesUrl

    UrlFilter 省略可

    非推奨

    リリース 82 以降は無視されます。

    リクエストの「ファーストパーティ」URL で UrlFilter の条件が満たされた場合に一致します。リクエストの「ファーストパーティ」URL は、存在する場合、リクエストのターゲット URL と異なる可能性があり、Cookie のサードパーティ チェックのために「ファーストパーティ」と見なされるものを記述します。

  • requestHeaders

    HeaderFilter[] 省略可

    リクエスト ヘッダーの一部が HeaderFilter のいずれかと一致する場合に一致します。

  • resourceType

    ResourceType[] 省略可

    リクエストのリクエスト タイプがリストに含まれている場合に一致します。いずれのタイプにも一致しないリクエストは除外されます。

  • responseHeaders

    HeaderFilter[] 省略可

    レスポンス ヘッダーの一部が HeaderFilter のいずれかと一致する場合に一致します。

  • ステージ

    Stage[] 省略可

    ステージを説明する文字列のリストが含まれます。使用できる値は、'onBeforeRequest'、'onBeforeSendHeaders'、'onHeadersReceived'、'onAuthRequired' です。この属性が存在する場合、適用可能なステージはリストされているステージに限定されます。条件全体は、すべての属性と互換性のあるステージでのみ適用されます。

  • thirdPartyForCookies

    boolean 省略可

    非推奨

    リリース 87 以降は無視されます。

    true に設定すると、サードパーティ Cookie ポリシーの対象となるリクエストが照合されます。false に設定すると、他のすべてのリクエストと一致します。

  • URL

    UrlFilter 省略可

    リクエストの URL で UrlFilter の条件が満たされている場合に一致します。

ResponseCookie

HTTP レスポンスの Cookie の仕様。

プロパティ

  • ドメイン

    文字列 省略可

    Domain Cookie 属性の値。

  • 有効期限

    文字列 省略可

    Expires Cookie 属性の値。

  • httpOnly

    文字列 省略可

    HttpOnly Cookie 属性の有無。

  • maxAge

    number 省略可

    Max-Age Cookie 属性の値

  • name

    文字列 省略可

    Cookie の名前。

  • パス

    文字列 省略可

    Path Cookie 属性の値。

  • 安全

    文字列 省略可

    Secure Cookie 属性の有無。

  • 値

    文字列 省略可

    Cookie の値。二重引用符で囲まれている場合があります。

SendMessageToExtension

declarativeWebRequest.onMessage イベントをトリガーします。

プロパティ

SetRequestHeader

指定された名前のリクエスト ヘッダーを指定された値に設定します。指定した名前のヘッダーが以前に存在しなかった場合は、新しいヘッダーが作成されます。ヘッダー名の比較では、大文字と小文字は常に区別されません。各リクエスト ヘッダー名は、各リクエストで 1 回だけ使用されます。

プロパティ

  • コンストラクタ

    void

    constructor 関数は次のようになります。 

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

  • name

    文字列

    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 はブラウザ セッション内で一意です。そのため、同じリクエストの異なるイベントを関連付けるために使用できます。

      • 各段階で

        ステージ

        イベントがトリガーされたネットワーク リクエストのステージ。

      • 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