chrome.declarativeWebRequest

説明

注: この API は非推奨になりました。代わりに declarativeNetRequest API をご確認ください。chrome.declarativeWebRequest API を使用して、処理中のリクエストをインターセプト、ブロック、または変更します。JavaScript エンジンではなくブラウザで評価されるルールを登録できるため、ラウンドトリップ レイテンシが削減され、効率が向上するため、chrome.webRequest API よりもはるかに高速です。

権限

declarativeWebRequest

「declarativeWebRequest」を拡張機能のマニフェストで API とホスト権限。

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

対象

<ph type="x-smartling-placeholder"></ph> Beta チャンネル &amp;leq;MV2

マニフェスト

機密性の低い特定のアクションでは、ホスト権限が不要であることに注意してください。

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

SendMessageToExtension() アクションには、ネットワーク リクエストを行うすべてのホストに対するホスト権限が必要です。 を選択します。

他のすべてのアクションには、すべての URL に対するホスト権限が必要です。

たとえば、"https://*.google.com/*" が拡張機能の唯一のホスト権限である場合、そのような権限は 以下を行うルールを設定できます。

  • https://www.google.com または https://anything.else.com へのリクエストをキャンセルします。
  • https://something.else.com ではなく https://www.google.com に移動したときにメッセージを送信します。

この拡張機能では、https://www.google.com を https://mail.google.com にリダイレクトするルールを設定できません。

ルール

Declarative Web Request API は、Declarative API のコンセプトに従います。登録するには chrome.declarativeWebRequest.onRequest イベント オブジェクトに追加しています。

Declarative Web Request API がサポートする一致条件のタイプは、RequestMatcher のみです。「 RequestMatcher は、リストにあるすべての条件が満たされた場合に限り、ネットワーク リクエストを照合します。次の RequestMatcher は、ユーザーがネットワーク リクエストに https://www.example.com と入力すると、ネットワーク リクエストと一致します。 Ominibox:

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 へのすべてのリクエストをキャンセルするには、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 は、ウェブ リクエストのライフサイクル モデル（ 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 で説明されているように、優先度に関連付けることができます。このメカニズムは、 使用されます。次の例では、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

Cookie をリクエストに追加するか、同じ名前の Cookie がすでに存在する場合は Cookie をオーバーライドします。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

AddResponseCookie

Cookie をレスポンスに追加するか、同じ名前の Cookie がすでに存在する場合は Cookie をオーバーライドします。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

AddResponseHeader

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

プロパティ

  • コンストラクタ

    void

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

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

  • name

    文字列

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

  • 値

    文字列

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

CancelRequest

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

プロパティ

EditRequestCookie

リクエストの 1 つ以上の Cookie を編集します。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

  • コンストラクタ

    void

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

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

  • フィルタ

    RequestCookie

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

  • 更新日時

    RequestCookie

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

EditResponseCookie

レスポンスの 1 つ以上の Cookie を編集します。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

  • コンストラクタ

    void

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

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

  • フィルタ

    FilterResponseCookie

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

  • 更新日時

    ResponseCookie

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

FilterResponseCookie

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

プロパティ

  • ageLowerBound

    数値（省略可）

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

  • ageUpperBound

    数値（省略可）

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

  • ドメイン

    文字列（省略可）

    ドメイン Cookie 属性の値。

  • 有効期限

    文字列（省略可）

    有効期限 Cookie 属性の値。

  • httpOnly

    文字列（省略可）

    HttpOnly Cookie 属性の有無。

  • maxAge

    数値（省略可）

    Max-Age Cookie 属性の値

  • name

    文字列（省略可）

    Cookie の名前。

  • パス

    文字列（省略可）

    パスの Cookie 属性の値。

  • 安全

    文字列（省略可）

    セキュア Cookie 属性の有無。

  • セッション Cookie

    ブール値（省略可）

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

  • 値

    文字列（省略可）

    Cookie の値。二重引用符で囲む場合があります。

HeaderFilter

さまざまな条件のリクエスト ヘッダーをフィルタします。複数の基準は組み合わせとして評価されます。

プロパティ

  • nameContains

    string |文字列 [] 省略可

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

  • nameEquals

    文字列（省略可）

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

  • namePrefix

    文字列（省略可）

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

  • nameSuffix

    文字列（省略可）

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

  • valueContains

    string |文字列 [] 省略可

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

  • valueEquals

    文字列（省略可）

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

  • valuePrefix

    文字列（省略可）

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

  • valueSuffix

    文字列（省略可）

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

IgnoreRules

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

プロパティ

  • コンストラクタ

    void

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

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

  • hasTag

    文字列（省略可）

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

  • lowerPriorityThan

    数値（省略可）

    設定すると、指定した値よりも優先度の低いルールは無視されます。この境界は保持されません。影響を受けるのは、同じネットワーク リクエスト ステージのルールとそのアクションのみです。

RedirectByRegEx

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

プロパティ

  • コンストラクタ

    void

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

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

  • 元

    文字列

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

  • たとえば

    文字列

    宛先パターン。

RedirectRequest

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

プロパティ

  • コンストラクタ

    void

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

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

  • redirectUrl

    文字列

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

RedirectToEmptyDocument

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

プロパティ

RedirectToTransparentImage

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

プロパティ

RemoveRequestCookie

リクエストの 1 つ以上の Cookie を削除します。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

RemoveRequestHeader

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

プロパティ

RemoveResponseCookie

レスポンスの 1 つ以上の Cookie を削除します。Cookie API の使用が推奨されるのは、計算コストがかからないためです。

プロパティ

RemoveResponseHeader

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

プロパティ

  • コンストラクタ

    void

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

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

  • name

    文字列

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

  • 値

    文字列（省略可）

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

RequestCookie

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

プロパティ

  • name

    文字列（省略可）

    Cookie の名前。

  • 値

    文字列（省略可）

    Cookie の値。二重引用符で囲む場合があります。

RequestMatcher

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

プロパティ

  • コンストラクタ

    void

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

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

  • contentType

    文字列 [] 省略可

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

  • excludeContentType

    文字列 [] 省略可

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

  • excludeRequestHeaders

    HeaderFilter[] 省略可

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

  • excludeResponseHeaders

    HeaderFilter[] 省略可

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

  • firstPartyForCookiesUrl

    UrlFilter 省略可

    <ph type="x-smartling-placeholder"></ph> 非推奨

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

    「ファーストパーティ」に対して UrlFilter の条件が満たされている場合に一致します。リクエストの URL。「ファーストパーティ」リクエストの URL（存在する場合）は、リクエストのターゲット URL とは異なる場合があります。「ファースト パーティ」と見なされるものを指定します第三者による Cookie のチェックのために使用しています。

  • requestHeaders

    HeaderFilter[] 省略可

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

  • resourceType

    ResourceType[] 省略可

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

  • responseHeaders

    HeaderFilter[] 省略可

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

  • ステージ

    ステージ [] 省略可

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

  • thirdPartyForCookies

    ブール値（省略可）

    <ph type="x-smartling-placeholder"></ph> 非推奨

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

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

  • URL

    UrlFilter 省略可

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

ResponseCookie

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

プロパティ

  • ドメイン

    文字列（省略可）

    ドメイン Cookie 属性の値。

  • 有効期限

    文字列（省略可）

    有効期限 Cookie 属性の値。

  • httpOnly

    文字列（省略可）

    HttpOnly Cookie 属性の有無。

  • maxAge

    数値（省略可）

    Max-Age Cookie 属性の値

  • name

    文字列（省略可）

    Cookie の名前。

  • パス

    文字列（省略可）

    パスの Cookie 属性の値。

  • 安全

    文字列（省略可）

    セキュア 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 で構成される Declarative Event API を提供します。

条件

RequestMatcher

操作

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules