説明
注: この API は非推奨になりました。代わりに declarativeNetRequest
API をご確認ください。chrome.declarativeWebRequest
API を使用して、処理中のリクエストをインターセプト、ブロック、または変更する。JavaScript エンジンではなくブラウザで評価されるルールを登録できるため、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
にリダイレクトするルールを設定できません。
ルール
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 の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: AddRequestCookie) => {...}
-
Cookie
リクエストに追加する Cookie。未定義のフィールドはありません。
AddResponseCookie
レスポンスに Cookie を追加するか、同じ名前の別の Cookie がすでに存在する場合は Cookie をオーバーライドします。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: AddResponseCookie) => {...}
-
Cookie
レスポンスに追加される Cookie。名前と値を指定する必要があります。
AddResponseHeader
このウェブ リクエストのレスポンスにレスポンス ヘッダーを追加します。複数のレスポンス ヘッダーが同じ名前を共有している可能性があるため、1 つを置き換えるには、まず新しいレスポンス ヘッダーを削除してから追加する必要があります。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: AddResponseHeader) => {...}
-
name
string
HTTP レスポンス ヘッダー名。
-
value
string
HTTP レスポンス ヘッダーの値。
CancelRequest
ネットワーク リクエストをキャンセルする宣言型イベント アクション。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: CancelRequest) => {...}
EditRequestCookie
リクエストの Cookie を編集します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: EditRequestCookie) => {...}
-
フィルタ
変更される Cookie をフィルタします。空のエントリはすべて無視されます。
-
更新日時
フィルタを処理した Cookie でオーバーライドされる属性。空の文字列に設定されている属性は削除されます。
EditResponseCookie
レスポンスの Cookie を編集します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: EditResponseCookie) => {...}
-
フィルタ
変更される Cookie をフィルタします。空のエントリはすべて無視されます。
-
更新日時
フィルタを処理した 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[] 省略可
ヘッダー名に、指定された文字列がすべて含まれている場合に一致します。
-
nameEquals
string(省略可)
ヘッダー名が指定された文字列と等しい場合に一致します。
-
namePrefix
string(省略可)
ヘッダー名が指定された文字列で始まる場合に一致します。
-
nameSuffix
string(省略可)
ヘッダー名が指定された文字列で終わる場合に一致します。
-
valueContains
string | string[] 省略可
ヘッダー値に、指定された文字列がすべて含まれている場合に一致します。
-
valueEquals
string(省略可)
ヘッダー値が指定された文字列と等しい場合に一致します。
-
valuePrefix
string(省略可)
ヘッダー値が指定された文字列で始まる場合に一致します。
-
valueSuffix
string(省略可)
ヘッダー値が指定された文字列で終わる場合に一致します。
IgnoreRules
指定した条件に一致するすべてのルールをマスクします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: IgnoreRules) => {...}
-
引数
-
戻り値
-
-
hasTag
string(省略可)
設定すると、指定したタグを持つルールは無視されます。この無視は永続化されず、同じネットワーク リクエスト ステージのルールとそのアクションにのみ影響します。ルールは優先度の降順で実行されます。この操作は、現在のルールより優先度の低いルールに影響します。優先度が同じルールは、無視される場合と無視されない場合があります。
-
lowerPriorityThan
number(省略可)
設定した場合、優先度が指定した値よりも低いルールは無視されます。この境界は永続的なものではなく、同じネットワーク リクエスト ステージのルールとそのアクションにのみ影響します。
RedirectByRegEx
URL に正規表現を適用して、リクエストをリダイレクトします。正規表現では RE2 構文を使用します。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RedirectByRegEx) => {...}
-
取得元:
string
キャプチャ グループを含む可能性のある一致パターン。JavaScript 正規表現に近づけるために、キャプチャ グループは RE2 構文 (\1, \2, ...) ではなく Perl 構文 ($1, $2, ...) で参照されます。
-
たとえば
string
宛先のパターン。
RedirectRequest
ネットワーク リクエストをリダイレクトする宣言型イベント アクション。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RedirectRequest) => {...}
-
redirectUrl
string
リクエストのリダイレクト先の宛先。
RedirectToEmptyDocument
ネットワーク リクエストを空のドキュメントにリダイレクトする宣言型のイベント アクション。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RedirectToEmptyDocument) => {...}
RedirectToTransparentImage
ネットワーク リクエストを透明な画像にリダイレクトする宣言型イベント アクション。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RedirectToTransparentImage) => {...}
RemoveRequestCookie
リクエストの Cookie を削除します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RemoveRequestCookie) => {...}
-
フィルタ
削除する Cookie をフィルタします。空のエントリはすべて無視されます。
RemoveRequestHeader
指定された名前のリクエスト ヘッダーを削除します。同じリクエストで同じヘッダー名で SetRequestHeader と RemoveRequestHeader を使用しないでください。各リクエスト ヘッダー名は、各リクエストで 1 回だけ出現します。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RemoveRequestHeader) => {...}
-
name
string
HTTP リクエスト ヘッダー名(大文字と小文字は区別されません)。
RemoveResponseCookie
レスポンスの 1 つ以上の Cookie を削除します。なお、Cookie API の方が計算コストが抑えられるため、この方法をおすすめします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RemoveResponseCookie) => {...}
-
フィルタ
削除する Cookie をフィルタします。空のエントリはすべて無視されます。
RemoveResponseHeader
指定された名前と値のすべてのレスポンス ヘッダーを削除します。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: RemoveResponseHeader) => {...}
-
name
string
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
イベントをトリガーします。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: SendMessageToExtension) => {...}
-
メッセージ
string
イベント ハンドラに渡される辞書の
message
属性に渡される値。
SetRequestHeader
指定された名前のリクエスト ヘッダーを指定された値に設定します。指定された名前のヘッダーが存在しない場合は、新しいヘッダーが作成されます。ヘッダー名の比較で、大文字と小文字は区別されません。各リクエスト ヘッダー名は、各リクエストで 1 回だけ出現します。
プロパティ
-
コンストラクタ
void
constructor
関数は次のようになります。(arg: SetRequestHeader) => {...}
-
name
string
HTTP リクエスト ヘッダー名。
-
value
string
HTTP リクエスト ヘッダーの値。
Stage
列挙型
"onHeadersReceived"
"onAuthRequired"
イベント
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
宣言型ウェブ リクエスト API のアクションから declarativeWebRequest.SendMessageToExtension
経由でメッセージが送信されたときに呼び出されます。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(details: object) => void
-
詳細
オブジェクト
-
documentId
string(省略可)
リクエストを行ったドキュメントの UUID。
-
documentLifecycle
ドキュメントが存在するライフサイクル。
-
frameId
数値
0 はリクエストがメインフレームで発生したことを示し、正の値はリクエストが発生したサブフレームの ID を示します。(サブ)フレームのドキュメントが読み込まれている場合(
type
がmain_frame
またはsub_frame
の場合)、frameId
は、外フレームの ID ではなく、このフレームの ID を示します。フレーム ID はタブ内で一意です。 -
frameType
ナビゲーションが発生したフレームのタイプ。
-
メッセージ
string
呼び出し元スクリプトによって送信されたメッセージ。
-
method
string
標準の HTTP メソッド。
-
parentDocumentId
string(省略可)
このフレームを所有する親ドキュメントの UUID。親がない場合、この値は設定されません。
-
parentFrameId
数値
リクエストを送信したフレームをラップするフレームの ID。親フレームが存在しない場合は -1 に設定します。
-
requestId
string
リクエストの ID。リクエスト ID はブラウザ セッション内で一意です。その結果、同じリクエストの異なるイベントを関連付けるために使用できます。
-
各段階で
イベントがトリガーされたネットワーク リクエストのステージ。
-
tabId
数値
リクエストが行われるタブの ID。リクエストがタブに関連していない場合は -1 に設定します。
-
timeStamp
数値
このシグナルがトリガーされた時間(エポックからのミリ秒)。
-
リクエストされたリソースの使用方法。
-
url
string
-
-
onRequest
addRules
、removeRules
、getRules
で構成される宣言型イベント API を提供します。
アクション