Deskripsi
Catatan: API ini tidak digunakan lagi. Sebagai gantinya, lihat declarativeNetRequest
API. Gunakan chrome.declarativeWebRequest
API untuk menangkap, memblokir, atau mengubah permintaan yang sedang berlangsung. Ini jauh lebih cepat daripada chrome.webRequest
API karena Anda dapat mendaftarkan aturan yang dievaluasi dalam browser, bukan mesin JavaScript, yang mengurangi latensi bolak-balik dan memungkinkan efisiensi yang lebih tinggi.
Izin
declarativeWebRequest
Anda harus mendeklarasikan izin "deklaratifWebRequest" dalam manifes ekstensi untuk menggunakan API ini, beserta izin host.
{
"name": "My extension",
...
"permissions": [
"declarativeWebRequest",
"*://*/*"
],
...
}
Ketersediaan
Manifes
Perhatikan bahwa jenis tindakan non-sensitif tertentu tidak memerlukan izin host:
CancelRequest
IgnoreRules
RedirectToEmptyDocument
RedirectToTransparentImage
Tindakan SendMessageToExtension()
memerlukan izin host untuk setiap host yang permintaan jaringannya
ingin Anda picu untuk memicu pesan.
Semua tindakan lainnya memerlukan izin host untuk semua URL.
Misalnya, jika "https://*.google.com/*"
adalah satu-satunya izin host yang dimiliki ekstensi, ekstensi tersebut dapat menyiapkan aturan untuk:
- Membatalkan permintaan ke
https://www.google.com
atauhttps://anything.else.com
. - Kirim pesan saat membuka
https://www.google.com
, tetapi tidak kehttps://something.else.com
.
Ekstensi tidak dapat menyiapkan aturan untuk mengalihkan https://www.google.com
ke https://mail.google.com
.
Aturan
Declarative Web Request API mengikuti konsep Declarative API. Anda dapat mendaftarkan aturan ke objek peristiwa chrome.declarativeWebRequest.onRequest
.
Declarative Web Request API mendukung satu jenis kriteria pencocokan, yaitu RequestMatcher
. RequestMatcher
cocok dengan permintaan jaringan jika dan hanya jika semua kriteria yang tercantum terpenuhi. RequestMatcher
berikut akan cocok dengan permintaan jaringan saat pengguna memasukkan https://www.example.com
di
ominibox:
var matcher = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com', schemes: ['http'] },
resourceType: ['main_frame']
});
Permintaan ke https://www.example.com
akan ditolak oleh RequestMatcher
karena skema tersebut.
Selain itu, semua permintaan untuk iframe tersemat akan ditolak karena resourceType
.
Untuk membatalkan semua permintaan ke "example.com", Anda dapat menentukan aturan sebagai berikut:
var rule = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
Untuk membatalkan semua permintaan ke example.com
dan foobar.com
, Anda dapat menambahkan kondisi kedua,
karena setiap kondisi cukup untuk memicu semua tindakan yang ditentukan:
var rule2 = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } }),
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
Daftarkan aturan sebagai berikut:
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
Evaluasi kondisi dan tindakan
Declarative Web Request API mengikuti Model siklus proses untuk permintaan web dari Web Request API. Artinya, kondisi hanya dapat diuji pada tahap tertentu dari permintaan web, dan juga, tindakan hanya dapat dijalankan pada tahap tertentu. Tabel berikut mencantumkan tahap permintaan yang kompatibel dengan kondisi dan tindakan.
Tahap permintaan saat atribut kondisi dapat diproses. | ||||
---|---|---|---|---|
Atribut kondisi | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
url |
✓ | ✓ | ✓ | ✓ |
resourceType |
✓ | ✓ | ✓ | ✓ |
contentType |
✓ | |||
excludeContentType |
✓ | |||
responseHeaders |
✓ | |||
excludeResponseHeaders |
✓ | |||
requestHeaders |
✓ | |||
excludeRequestHeaders |
✓ | |||
thirdPartyForCookies |
✓ | ✓ | ✓ | ✓ |
Tahap permintaan saat tindakan dapat dijalankan. | ||||
Acara | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
AddRequestCookie |
✓ | |||
AddResponseCookie |
✓ | |||
AddResponseHeader |
✓ | |||
CancelRequest |
✓ | ✓ | ✓ | ✓ |
EditRequestCookie |
✓ | |||
EditResponseCookie |
✓ | |||
IgnoreRules |
✓ | ✓ | ✓ | ✓ |
RedirectByRegEx |
✓ | ✓ | ||
RedirectRequest |
✓ | ✓ | ||
RedirectToEmptyDocument |
✓ | ✓ | ||
RedirectToTransparentImage |
✓ | ✓ | ||
RemoveRequestCookie |
✓ | |||
RemoveRequestHeader |
✓ | |||
RemoveResponseCookie |
✓ | |||
RemoveResponseHeader |
✓ | |||
SendMessageToExtension |
✓ | ✓ | ✓ | ✓ |
SetRequestHeader |
✓ |
Menggunakan prioritas untuk mengganti aturan
Aturan dapat dikaitkan dengan prioritas seperti yang dijelaskan di Events API. Mekanisme ini dapat digunakan untuk menyatakan pengecualian. Contoh berikut memblokir semua permintaan ke gambar bernama evil.jpg
kecuali pada server "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]);
Perlu diketahui bahwa tindakan IgnoreRules
tidak dipertahankan di seluruh tahap
permintaan. Semua kondisi dari semua aturan akan dievaluasi pada setiap tahap permintaan web. Jika
dijalankan, tindakan IgnoreRules
hanya berlaku untuk tindakan lain yang dijalankan untuk
permintaan web yang sama di tahap yang sama.
Jenis
AddRequestCookie
Menambahkan cookie ke permintaan atau mengganti cookie, jika ada cookie lain dengan nama yang sama sudah ada. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: AddRequestCookie) => {...}
-
arg
-
akan menampilkan
-
-
kue
Cookie yang akan ditambahkan ke permintaan. Tidak ada kolom yang tidak ditentukan.
AddResponseCookie
Menambahkan cookie ke respons atau mengganti cookie, jika ada cookie lain dengan nama yang sama sudah ada. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: AddResponseCookie) => {...}
-
akan menampilkan
-
-
kue
Cookie yang akan ditambahkan ke respons. Nama dan nilai harus ditentukan.
AddResponseHeader
Menambahkan header respons ke respons permintaan web ini. Karena beberapa header respons mungkin memiliki nama yang sama, Anda harus menghapus terlebih dahulu, lalu menambahkan header respons baru untuk menggantikannya.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: AddResponseHeader) => {...}
-
akan menampilkan
-
-
name
string
Nama header respons HTTP.
-
value
string
Nilai header respons HTTP.
CancelRequest
Tindakan peristiwa deklaratif yang membatalkan permintaan jaringan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: CancelRequest) => {...}
-
arg
-
akan menampilkan
-
EditRequestCookie
Mengedit satu atau beberapa cookie permintaan. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: EditRequestCookie) => {...}
-
akan menampilkan
-
-
filter
Filter untuk cookie yang akan diubah. Semua entri kosong akan diabaikan.
-
modifikasi
Atribut yang harus diganti dalam cookie yang menggunakan filter. Atribut yang disetel ke string kosong akan dihapus.
EditResponseCookie
Mengedit satu atau beberapa cookie respons. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: EditResponseCookie) => {...}
-
akan menampilkan
-
-
filter
Filter untuk cookie yang akan diubah. Semua entri kosong akan diabaikan.
-
modifikasi
Atribut yang harus diganti dalam cookie yang menggunakan filter. Atribut yang disetel ke string kosong akan dihapus.
FilterResponseCookie
Filter cookie di Respons HTTP.
Properti
-
ageLowerBound
nomor opsional
Batas bawah inklusif pada masa aktif cookie (ditentukan dalam detik setelah waktu saat ini). Hanya cookie dengan waktu tanggal habis masa berlaku yang ditetapkan ke 'now + ageLowerBound' atau nanti yang akan memenuhi kriteria ini. Cookie sesi tidak memenuhi kriteria filter ini. Masa berlaku cookie dihitung dari atribut cookie 'max-age' atau 'expires'. Jika keduanya ditentukan, 'max-age' digunakan untuk menghitung masa aktif cookie.
-
ageUpperBound
nomor opsional
Batas atas inklusif selama masa aktif cookie (ditentukan dalam detik setelah waktu saat ini). Hanya cookie dengan tanggal habis masa berlaku yang berada dalam interval [sekarang, sekarang + ageUpperBound] yang memenuhi kriteria ini. Cookie sesi dan cookie yang tanggal habis masa berlakunya adalah di masa lalu tidak memenuhi kriteria filter ini. Masa berlaku cookie dihitung dari atribut cookie 'max-age' atau 'expires'. Jika keduanya ditentukan, 'max-age' digunakan untuk menghitung masa aktif cookie.
-
domain
string opsional
Nilai atribut cookie Domain.
-
tanggal akhir
string opsional
Nilai atribut Cookie kedaluwarsa.
-
httpOnly
string opsional
Keberadaan atribut cookie HttpOnly.
-
maxAge
nomor opsional
Nilai atribut cookie Usia Maksimal
-
name
string opsional
Nama cookie.
-
jalur
string opsional
Nilai atribut cookie Jalur.
-
aman
string opsional
Keberadaan atribut cookie Aman.
-
sessionCookie
boolean opsional
Memfilter cookie sesi. Cookie sesi tidak memiliki masa berlaku yang ditentukan dalam atribut 'max-age' atau 'expires' mana pun.
-
value
string opsional
Nilai cookie, dapat diberi padding dalam tanda kutip.
HeaderFilter
Memfilter header permintaan untuk berbagai kriteria. Beberapa kriteria dievaluasi sebagai konjungsi.
Properti
-
nameContains
string | string[] opsional
Cocok jika nama header berisi semua string yang ditentukan.
-
nameEquals
string opsional
Cocok jika nama header sama dengan string yang ditentukan.
-
namePrefix
string opsional
Cocok jika nama header dimulai dengan string yang ditentukan.
-
nameSuffix
string opsional
Cocok jika nama header diakhiri dengan string yang ditentukan.
-
valueContains
string | string[] opsional
Mencocokkan jika nilai header berisi semua string yang ditentukan.
-
valueEquals
string opsional
Cocok jika nilai header sama dengan string yang ditentukan.
-
valuePrefix
string opsional
Cocok jika nilai header diawali dengan string yang ditentukan.
-
valueSuffix
string opsional
Cocok jika nilai header diakhiri dengan string yang ditentukan.
IgnoreRules
Menyamarkan semua aturan yang cocok dengan kriteria yang ditentukan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: IgnoreRules) => {...}
-
arg
-
akan menampilkan
-
-
hasTag
string opsional
Jika ditetapkan, aturan dengan tag yang ditentukan akan diabaikan. Pengabaikan ini tidak akan dipertahankan. Hal ini hanya memengaruhi aturan dan tindakannya pada tahapan permintaan jaringan yang sama. Perhatikan bahwa aturan dijalankan dalam urutan menurun dari prioritasnya. Tindakan ini memengaruhi aturan dengan prioritas yang lebih rendah daripada aturan saat ini. Aturan dengan prioritas yang sama dapat atau tidak dapat diabaikan.
-
lowerPriorityThan
nomor opsional
Jika ditetapkan, aturan dengan prioritas yang lebih rendah dari nilai yang ditentukan akan diabaikan. Batas ini tidak dipertahankan. Batas ini hanya memengaruhi aturan dan tindakannya pada tahap permintaan jaringan yang sama.
RedirectByRegEx
Mengalihkan permintaan dengan menerapkan ekspresi reguler pada URL. Ekspresi reguler menggunakan sintaksis RE2.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RedirectByRegEx) => {...}
-
arg
-
akan menampilkan
-
-
dari
string
Pola pencocokan yang mungkin berisi grup tangkapan. Grup tangkapan dirujuk dalam sintaks Perl ($1, $2, ...) bukan sintaks RE2 (\1, \2, ...) untuk lebih dekat dengan Ekspresi Reguler JavaScript.
-
hingga
string
Pola tujuan.
RedirectRequest
Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RedirectRequest) => {...}
-
arg
-
akan menampilkan
-
-
redirectUrl
string
Tujuan tempat permintaan dialihkan.
RedirectToEmptyDocument
Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan ke dokumen kosong.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RedirectToEmptyDocument) => {...}
-
akan menampilkan
-
RedirectToTransparentImage
Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan ke gambar transparan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RedirectToTransparentImage) => {...}
-
akan menampilkan
-
RemoveRequestCookie
Menghapus satu atau beberapa cookie permintaan. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RemoveRequestCookie) => {...}
-
akan menampilkan
-
-
filter
Filter untuk cookie yang akan dihapus. Semua entri kosong akan diabaikan.
RemoveRequestHeader
Menghapus header permintaan nama yang ditentukan. Jangan gunakan SetRequestHeader dan RemoveRequestHeader dengan nama header yang sama pada permintaan yang sama. Setiap nama header permintaan hanya muncul sekali dalam setiap permintaan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RemoveRequestHeader) => {...}
-
akan menampilkan
-
-
name
string
Nama header permintaan HTTP (tidak peka huruf besar/kecil).
RemoveResponseCookie
Menghapus satu atau beberapa cookie respons. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RemoveResponseCookie) => {...}
-
akan menampilkan
-
-
filter
Filter untuk cookie yang akan dihapus. Semua entri kosong akan diabaikan.
RemoveResponseHeader
Menghapus semua header respons dari nama dan nilai yang ditentukan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RemoveResponseHeader) => {...}
-
akan menampilkan
-
-
name
string
Nama header permintaan HTTP (tidak peka huruf besar/kecil).
-
value
string opsional
Nilai header permintaan HTTP (tidak peka huruf besar/kecil).
RequestCookie
Filter atau spesifikasi cookie di Permintaan HTTP.
Properti
-
name
string opsional
Nama cookie.
-
value
string opsional
Nilai cookie, dapat diberi padding dalam tanda kutip.
RequestMatcher
Mencocokkan peristiwa jaringan menurut berbagai kriteria.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: RequestMatcher) => {...}
-
arg
-
akan menampilkan
-
-
contentType
string[] opsional
Mencocokkan jika jenis media MIME respons (dari header Jenis Konten HTTP) terdapat dalam daftar.
-
excludeContentType
string[] opsional
Mencocokkan jika jenis media MIME respons (dari header Jenis Konten HTTP) tidak terdapat dalam daftar.
-
excludeRequestHeaders
HeaderFilter[] opsional
Mencocokkan jika tidak ada header permintaan yang cocok dengan HeaderFilters mana pun.
-
excludeResponseHeaders
HeaderFilter[] opsional
Mencocokkan jika tidak ada header respons yang cocok dengan HeaderFilters mana pun.
-
firstPartyForCookiesUrl
UrlFilter opsional
Tidak digunakan lagiDiabaikan sejak rilis 82.
Mencocokkan jika kondisi UrlFilter terpenuhi untuk URL 'pihak pertama' permintaan. URL 'pihak pertama' permintaan, jika ada, dapat berbeda dengan URL target permintaan, dan menjelaskan apa yang dianggap sebagai 'pihak pertama' demi pemeriksaan cookie pihak ketiga.
-
requestHeaders
HeaderFilter[] opsional
Mencocokkan jika beberapa header permintaan cocok dengan salah satu HeaderFilters.
-
resourceType
ResourceType[] opsional
Cocok jika jenis permintaan permintaan ada dalam daftar. Permintaan yang tidak dapat cocok dengan jenis apa pun akan difilter.
-
responseHeaders
HeaderFilter[] opsional
Mencocokkan jika beberapa header respons cocok dengan salah satu HeaderFilters.
-
tahap
Stage[] opsional
Berisi daftar string yang menjelaskan stage. Nilai yang diizinkan adalah 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. Jika atribut ini ada, maka akan membatasi stage yang berlaku untuk stage yang tercantum di bawah. Perhatikan bahwa keseluruhan kondisi hanya berlaku dalam tahapan yang kompatibel dengan semua atribut.
-
thirdPartyForCookies
boolean opsional
Tidak digunakan lagiDiabaikan sejak rilis 87.
Jika ditetapkan ke true, mencocokkan permintaan yang tunduk pada kebijakan cookie pihak ketiga. Jika disetel ke salah (false), cocok dengan semua permintaan lainnya.
-
url
UrlFilter opsional
Mencocokkan jika kondisi UrlFilter terpenuhi untuk URL permintaan.
ResponseCookie
Spesifikasi cookie di Respons HTTP.
Properti
-
domain
string opsional
Nilai atribut cookie Domain.
-
tanggal akhir
string opsional
Nilai atribut Cookie kedaluwarsa.
-
httpOnly
string opsional
Keberadaan atribut cookie HttpOnly.
-
maxAge
nomor opsional
Nilai atribut cookie Usia Maksimal
-
name
string opsional
Nama cookie.
-
jalur
string opsional
Nilai atribut cookie Jalur.
-
aman
string opsional
Keberadaan atribut cookie Aman.
-
value
string opsional
Nilai cookie, dapat diberi padding dalam tanda kutip.
SendMessageToExtension
Memicu peristiwa declarativeWebRequest.onMessage
.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: SendMessageToExtension) => {...}
-
akan menampilkan
-
-
pesan
string
Nilai yang akan diteruskan dalam atribut
message
kamus yang diteruskan ke pengendali peristiwa.
SetRequestHeader
Menetapkan header permintaan dari nama yang ditentukan ke nilai yang ditentukan. Jika header dengan nama yang ditentukan sebelumnya tidak ada, header baru akan dibuat. Perbandingan nama header selalu tidak peka huruf besar/kecil. Setiap nama header permintaan hanya muncul sekali dalam setiap permintaan.
Properti
-
konstruktor
void
Fungsi
constructor
terlihat seperti:(arg: SetRequestHeader) => {...}
-
arg
-
akan menampilkan
-
-
name
string
Nama header permintaan HTTP.
-
value
string
Nilai header permintaan HTTP.
Stage
Enum
"onBeforeRequest"
"onBeforeSendHeaders"
"onAuthRequired"
Acara
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
Diaktifkan saat pesan dikirim melalui declarativeWebRequest.SendMessageToExtension
dari tindakan API permintaan web deklaratif.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti:(details: object) => void
-
detail
objek
-
documentId
string opsional
UUID dokumen yang membuat permintaan.
-
documentLifecycle
Siklus proses tempat dokumen berada.
-
frameId
angka
Nilai 0 menunjukkan bahwa permintaan terjadi di frame utama; nilai positif menunjukkan ID subframe tempat permintaan terjadi. Jika dokumen bingkai (sub-) dimuat (
type
adalahmain_frame
atausub_frame
),frameId
menunjukkan ID bingkai ini, bukan ID bingkai luar. ID Frame bersifat unik di dalam tab. -
frameType
Jenis frame tempat navigasi terjadi.
-
pesan
string
Pesan yang dikirim oleh skrip panggilan.
-
method
string
Metode HTTP standar.
-
parentDocumentId
string opsional
UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.
-
parentFrameId
angka
ID frame yang menggabungkan frame yang mengirim permintaan. Tetapkan ke -1 jika tidak ada frame induk.
-
requestId
string
ID permintaan. ID permintaan bersifat unik dalam sesi browser. Akibatnya, peristiwa tersebut dapat digunakan untuk mengaitkan berbagai peristiwa dari permintaan yang sama.
-
stage
Tahap permintaan jaringan saat peristiwa dipicu.
-
tabId
angka
ID tab tempat permintaan terjadi. Tetapkan ke -1 jika permintaan tidak terkait dengan tab.
-
timeStamp
angka
Waktu saat sinyal ini dipicu, dalam milidetik sejak epoch.
-
Cara penggunaan resource yang diminta.
-
url
string
-
-
onRequest
Menyediakan Declarative Event API yang terdiri dari addRules
, removeRules
, dan getRules
.
Kondisi
Tindakan