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 は、宣言型 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 によって拒否されます。また、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 をオーバーライドします。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

AddResponseCookie

レスポンスに Cookie を追加するか、同じ名前の別の Cookie がすでに存在する場合は Cookie をオーバーライドします。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

AddResponseHeader

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

プロパティ

  • コンストラクタ

    void

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

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

  • name

    文字列

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

  • value

    文字列

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

CancelRequest

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

プロパティ

EditRequestCookie

リクエストの Cookie を編集します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

  • コンストラクタ

    void

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

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

  • フィルタ

    RequestCookie

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

  • 更新日時

    RequestCookie

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

EditResponseCookie

レスポンスの Cookie を編集します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

  • コンストラクタ

    void

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

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

  • フィルタ

    FilterResponseCookie

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

  • 更新日時

    ResponseCookie

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

FilterResponseCookie

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

プロパティ

  • ageLowerBound

    number（省略可）

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

  • ageUpperBound

    number（省略可）

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

  • ドメイン

    string（省略可）

    ドメイン Cookie 属性の値。

  • 有効期限

    string（省略可）

    有効期限 Cookie 属性の値。

  • httpOnly

    string（省略可）

    HttpOnly Cookie 属性が存在すること。

  • maxAge

    number（省略可）

    Max-Age Cookie 属性の値

  • name

    string（省略可）

    Cookie の名前。

  • パス

    string（省略可）

    パス Cookie 属性の値。

  • 安全

    string（省略可）

    セキュア Cookie 属性が存在すること。

  • sessionCookie

    ブール値（省略可）

    セッション Cookie をフィルタします。セッション Cookie の「max-age」属性または「expires」属性に存続期間が指定されていません。

  • value

    string（省略可）

    Cookie の値。二重引用符でパディングできます。

HeaderFilter

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

プロパティ

  • nameContains

    string|string[] optional

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

  • nameEquals

    string（省略可）

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

  • namePrefix

    string（省略可）

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

  • nameSuffix

    string（省略可）

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

  • valueContains

    string|string[] optional

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

  • valueEquals

    string（省略可）

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

  • valuePrefix

    string（省略可）

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

  • valueSuffix

    string（省略可）

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

IgnoreRules

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

プロパティ

  • コンストラクタ

    void

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

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

  • hasTag

    string（省略可）

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

  • lowerPriorityThan

    number（省略可）

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

RedirectByRegEx

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

プロパティ

  • コンストラクタ

    void

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

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

  • からの

    文字列

    キャプチャ グループを含む可能性のある一致パターン。JavaScript 正規表現に近づけるために、キャプチャ グループは RE2 構文 (\1, \2, ...) ではなく Perl 構文 ($1, $2, ...) で参照されます。

  • たとえば

    文字列

    宛先のパターン。

RedirectRequest

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

プロパティ

  • コンストラクタ

    void

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

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

  • redirectUrl

    文字列

    リクエストのリダイレクト先の宛先。

RedirectToEmptyDocument

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

プロパティ

RedirectToTransparentImage

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

プロパティ

RemoveRequestCookie

リクエストの Cookie を削除します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

RemoveRequestHeader

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

プロパティ

RemoveResponseCookie

レスポンスの 1 つ以上の Cookie を削除します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。

プロパティ

RemoveResponseHeader

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

プロパティ

  • コンストラクタ

    void

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

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

  • name

    文字列

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

  • value

    string（省略可）

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

RequestCookie

HTTP リクエストにおける Cookie のフィルタまたは指定。

プロパティ

  • name

    string（省略可）

    Cookie の名前。

  • value

    string（省略可）

    Cookie の値。二重引用符でパディングできます。

RequestMatcher

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

プロパティ

  • コンストラクタ

    void

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

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

  • contentType

    string[] 省略可

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

  • excludeContentType

    string[] 省略可

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

  • excludeRequestHeaders

    HeaderFilter[] 省略可

    どのリクエスト ヘッダーとも、どの HeaderFilters とも一致しない場合に一致します。

  • excludeResponseHeaders

    HeaderFilter[] 省略可

    どのレスポンス ヘッダーも HeaderFilters によって一致しない場合に一致します。

  • firstPartyForCookiesUrl

    UrlFilter 省略可

    非推奨

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

    リクエストの「ファースト パーティ」URL について UrlFilter の条件が満たされた場合に一致します。リクエストの「ファースト パーティ」URL は、リクエストのターゲット URL とは異なる場合があります。これは、サードパーティが Cookie をチェックする目的で「ファースト パーティ」とみなされる URL です。

  • requestHeaders

    HeaderFilter[] 省略可

    リクエスト ヘッダーの一部が HeaderFilters の 1 つと一致する場合に一致します。

  • resourceType

    ResourceType[] 省略可

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

  • responseHeaders

    HeaderFilter[] 省略可

    レスポンス ヘッダーの一部が HeaderFilters の 1 つと一致する場合に一致します。

  • ステージ

    ステージ[] 省略可

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

  • thirdPartyForCookies

    ブール値（省略可）

    非推奨

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

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

  • URL

    UrlFilter 省略可

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

ResponseCookie

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

プロパティ

  • ドメイン

    string（省略可）

    ドメイン Cookie 属性の値。

  • 有効期限

    string（省略可）

    有効期限 Cookie 属性の値。

  • httpOnly

    string（省略可）

    HttpOnly Cookie 属性が存在すること。

  • maxAge

    number（省略可）

    Max-Age Cookie 属性の値

  • name

    string（省略可）

    Cookie の名前。

  • パス

    string（省略可）

    パス Cookie 属性の値。

  • 安全

    string（省略可）

    セキュア Cookie 属性が存在すること。

  • value

    string（省略可）

    Cookie の値。二重引用符でパディングできます。

SendMessageToExtension

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

プロパティ

SetRequestHeader

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

プロパティ

  • コンストラクタ

    void

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

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

  • name

    文字列

    HTTP リクエスト ヘッダー名。

  • value

    文字列

    HTTP リクエスト ヘッダーの値。

Stage

Enum

"onHeadersReceived"

"onAuthRequired"

イベント

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

宣言型ウェブ リクエスト API のアクションから declarativeWebRequest.SendMessageToExtension 経由でメッセージが送信されたときに呼び出されます。

パラメータ

  • callback

    機能

    callback パラメータは次のようになります。 

    (details: object)=>void

    • 詳細

      オブジェクト

      • documentId

        string（省略可）

        リクエストを行ったドキュメントの UUID。

      • ドキュメントが存在するライフサイクル。

      • frameId

        数値

        0 はリクエストがメインフレームで発生したことを示し、正の値はリクエストが発生したサブフレームの ID を示します。（サブ）フレームのドキュメントが読み込まれている場合（type が main_frame または sub_frame の場合）、frameId は、外フレームの ID ではなく、このフレームの ID を示します。フレーム ID はタブ内で一意です。

      • ナビゲーションが発生したフレームのタイプ。

      • message

        文字列

        呼び出し元スクリプトによって送信されたメッセージ。

      • method

        文字列

        標準の HTTP メソッド。

      • parentDocumentId

        string（省略可）

        このフレームを所有する親ドキュメントの 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