Deskripsi
chrome.declarativeNetRequest
API digunakan untuk memblokir atau mengubah permintaan jaringan dengan menentukan aturan deklaratif. Hal ini memungkinkan ekstensi mengubah permintaan jaringan tanpa mencegatnya dan melihat kontennya, sehingga memberikan lebih banyak privasi.
Izin
declarativeNetRequest
declarativeNetRequestWithHostAccess
"declarativeNetRequest
" dan "declarativeNetRequestWithHostAccess
" izin
menyediakan kemampuan yang sama. Perbedaan di antara keduanya adalah
ketika izin akses
diminta atau diberikan.
"declarativeNetRequest"
- Memicu peringatan izin pada waktu penginstalan, tetapi memberikan akses implisit ke
Aturan
allow
,allowAllRequests
, danblock
. Gunakan metode ini jika memungkinkan untuk menghindari perlu meminta akses penuh ke host. "declarativeNetRequestFeedback"
- Mengaktifkan fitur proses debug untuk ekstensi yang tidak dipaketkan, khususnya
getMatchedRules()
danonRuleMatchedDebug
. "declarativeNetRequestWithHostAccess"
- Peringatan izin tidak ditampilkan pada waktu penginstalan, tetapi Anda harus meminta host izin akses sebelum Anda dapat melakukan tindakan apa pun pada {i>host<i}. Ini adalah pilihan yang tepat jika Anda ingin menggunakan aturan permintaan net deklaratif yang telah memiliki izin {i>host<i} tanpa menghasilkan peringatan.
Ketersediaan
Manifes
Selain izin yang dijelaskan sebelumnya, jenis kumpulan aturan tertentu, khususnya kumpulan aturan statis, mengharuskan deklarasi kunci manifes "declarative_net_request"
, yang harus berupa kamus dengan kunci tunggal yang disebut "rule_resources"
. Kunci ini adalah array yang berisi kamus jenis Ruleset
, seperti yang ditunjukkan dalam berikut ini. (Perhatikan, nama 'Ruleset' tidak muncul dalam JSON manifes karena hanya berupa array.) Kumpulan aturan statis akan dijelaskan nanti dalam dokumen ini.
{
"name": "My extension",
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
}, {
"id": "ruleset_2",
"enabled": false,
"path": "rules_2.json"
}]
},
"permissions": [
"declarativeNetRequest",
"declarativeNetRequestFeedback",
],
"host_permissions": [
"http://www.blogger.com/*",
"http://*.google.com/*"
],
...
}
Aturan dan kumpulan aturan
Untuk menggunakan API ini, tentukan satu atau beberapa kumpulan aturan. Kumpulan aturan berisi kumpulan aturan. Satu aturan melakukan salah satu hal berikut:
- Memblokir permintaan jaringan.
- Upgrade skema (http ke https).
- Mencegah permintaan diblokir dengan mengabaikan aturan yang diblokir yang cocok.
- Mengalihkan permintaan jaringan.
- Ubah header permintaan atau respons.
Ada tiga jenis kumpulan aturan, yang dikelola dengan cara yang sedikit berbeda.
- Dinamis
- Pertahankan di seluruh sesi browser dan upgrade ekstensi serta dikelola menggunakan JavaScript saat ekstensi sedang digunakan.
- Sesi
- Dihapus saat browser dinonaktifkan dan saat ekstensi versi baru diinstal. Aturan sesi dikelola menggunakan JavaScript saat ekstensi sedang digunakan.
- Statis
- Dikemas, diinstal, dan diupdate saat ekstensi diinstal atau diupgrade. Aturan statis disimpan dalam file aturan berformat JSON dan tercantum dalam file manifes.
Kumpulan aturan dinamis dan cakupan sesi
Kumpulan aturan dinamis dan sesi dikelola menggunakan JavaScript saat ekstensi sedang digunakan.
- Aturan dinamis akan berlaku di seluruh sesi browser dan upgrade ekstensi.
- Aturan sesi dihapus saat browser dinonaktifkan dan saat ekstensi versi baru diinstal.
Hanya ada satu untuk setiap jenis kumpulan aturan ini. Ekstensi dapat menambahkan atau menghapus aturan ke aturan tersebut secara dinamis dengan memanggil updateDynamicRules()
dan updateSessionRules()
, asalkan batas aturan tidak terlampaui. Untuk mengetahui informasi tentang batas aturan, lihat Batas aturan. Anda dapat melihat contohnya di bagian contoh kode.
Kumpulan aturan statis
Tidak seperti aturan dinamis dan sesi, aturan statis dikemas, diinstal, dan diperbarui saat ekstensi diinstal atau diupgrade. Cookie disimpan dalam file aturan dalam format JSON, yang ditunjukkan ke ekstensi menggunakan kunci "declarative_net_request"
dan "rule_resources"
seperti yang dijelaskan di atas, serta satu atau beberapa kamus Ruleset
. Kamus Ruleset
berisi jalur ke file aturan, ID untuk kumpulan aturan yang terdapat dalam file, dan apakah kumpulan aturan diaktifkan atau dinonaktifkan. Dua yang terakhir penting saat Anda mengaktifkan atau menonaktifkan kumpulan aturan secara terprogram.
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
Untuk menguji file aturan, muat ekstensi Anda yang telah dibuka. Error dan peringatan tentang aturan statis yang tidak valid hanya ditampilkan untuk ekstensi yang tidak dipaketkan. Aturan statis yang tidak valid dalam paket ekstensi akan diabaikan.
Ulasan yang dipercepat
Perubahan pada kumpulan aturan statis mungkin memenuhi syarat untuk peninjauan yang lebih cepat. Lihat peninjauan yang dipercepat untuk perubahan yang memenuhi syarat.
Mengaktifkan dan menonaktifkan aturan dan kumpulan aturan statis
Aturan statis individual maupun kumpulan aturan statis lengkap dapat diaktifkan atau dinonaktifkan saat runtime.
Kumpulan aturan statis dan kumpulan aturan yang diaktifkan akan dipertahankan di seluruh sesi browser. Keduanya tidak dipertahankan di seluruh update ekstensi, yang berarti bahwa hanya aturan yang Anda pilih untuk dibiarkan dalam file aturan yang tersedia setelah update.
Karena alasan performa, ada juga batasan jumlah aturan dan kumpulan aturan yang dapat diaktifkan sekaligus. Panggil getAvailableStaticRuleCount()
untuk memeriksa jumlah aturan tambahan yang dapat diaktifkan. Untuk mengetahui informasi tentang batas aturan, lihat Batas aturan.
Untuk mengaktifkan atau menonaktifkan aturan statis, panggil updateStaticRules()
. Metode ini mengambil objek UpdateStaticRulesOptions
, yang berisi array ID aturan yang akan diaktifkan atau dinonaktifkan. ID ditentukan menggunakan kunci "id"
dari kamus Ruleset
. Ada batas maksimum 5.000 aturan statis yang dinonaktifkan.
Untuk mengaktifkan atau menonaktifkan kumpulan aturan statis, panggil updateEnabledRulesets()
. Metode ini mengambil objek UpdateRulesetOptions
, yang berisi array ID set aturan yang akan diaktifkan atau dinonaktifkan. ID ditentukan menggunakan kunci "id"
dari kamus Ruleset
.
Buat aturan
Apa pun jenisnya, aturan dimulai dengan empat kolom seperti yang ditunjukkan di bawah ini. Saat kunci "id"
dan "priority"
mengambil angka, kunci "action"
dan "condition"
dapat memberikan beberapa kondisi pemblokiran dan pengalihan. Aturan berikut memblokir semua permintaan skrip yang berasal dari "foo.com"
ke URL apa pun dengan "abc"
sebagai substring.
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
Pencocokan URL
Declarative Net Request memberikan kemampuan untuk mencocokkan URL dengan sintaksis atau ekspresi reguler yang cocok.
Sintaksis filter URL
Kunci "condition"
aturan memungkinkan kunci "urlFilter"
untuk bertindak pada URL dalam domain yang ditentukan. Anda dapat membuat pola menggunakan token pencocokan pola. Berikut beberapa contohnya.
urlFilter |
Kecocokan | Tidak cocok |
---|---|---|
"abc" |
https://abcd.com https://example.com/abcd |
https://ab.com |
"abc*d" |
https://abcd.com https://example.com/abcxyzd |
https://abc.com |
"||a.example.com" |
https://a.example.com/ https://b.a.example.com/xyz https://a.example.company |
https://example.com/ |
"|https*" |
https://example.com | http://example.com/ http://https.com |
"example*^123|" |
https://example.com/123 http://abc.com/example?123 |
https://example.com/1234 https://abc.com/example0123 |
Ekspresi reguler
Kondisi juga dapat menggunakan ekspresi reguler. Lihat
Tombol "regexFilter"
. Untuk mempelajari tentang
batasan yang berlaku untuk kondisi tersebut, lihat
Aturan yang menggunakan ekspresi reguler.
Menulis kondisi URL yang baik
Berhati-hatilah saat menulis aturan agar selalu cocok dengan seluruh domain. Jika tidak, aturan mungkin cocok dalam situasi yang tidak terduga. Misalnya, saat menggunakan {i>syntax<i} pencocokan pola:
google.com
salah cocok denganhttps://example.com/?param=google.com
||google.com
salah cocok denganhttps://google.company
https://www.google.com
salah cocok denganhttps://example.com/?param=https://www.google.com
Pertimbangkan untuk menggunakan:
||google.com/
, yang cocok dengan semua jalur dan semua subdomain.|https://www.google.com/
yang cocok dengan semua jalur dan tanpa subdomain.
Demikian pula, gunakan karakter ^
dan /
untuk menambatkan ekspresi reguler. Sebagai
contoh, ^https:\/\/www\.google\.com\/
cocok dengan jalur apa pun di
https://www.google.com.
Evaluasi aturan
Aturan DNR diterapkan oleh browser di berbagai tahap siklus proses permintaan jaringan.
Sebelum permintaan
Sebelum permintaan dibuat, ekstensi dapat memblokir atau mengalihkan (termasuk mengupgrade skema dari HTTP ke HTTPS) dengan aturan yang cocok.
Untuk setiap ekstensi, browser menentukan daftar aturan yang cocok. Aturan dengan tindakan modifyHeaders
tidak disertakan di sini karena akan ditangani nanti. Selain itu, aturan dengan kondisi responseHeaders
akan dipertimbangkan nanti (saat header respons tersedia) dan tidak disertakan.
Kemudian, untuk setiap ekstensi, Chrome akan memilih maksimal satu kandidat per permintaan. Chrome menemukan aturan yang cocok, dengan mengurutkan semua aturan yang cocok berdasarkan prioritas. Aturan dengan prioritas yang sama diurutkan berdasarkan tindakan (allow
atau allowAllRequests
> block
> upgradeScheme
> redirect
).
Jika kandidat adalah aturan allow
atau allowAllRequests
, atau frame tempat permintaan dibuat sebelumnya cocok dengan aturan allowAllRequests
dengan prioritas yang lebih tinggi atau sama dari ekstensi ini, permintaan tersebut "diizinkan" dan ekstensi tidak akan berpengaruh pada permintaan.
Jika lebih dari satu ekstensi ingin memblokir atau mengalihkan permintaan ini, satu tindakan yang harus dilakukan akan dipilih. Chrome melakukan hal ini dengan mengurutkan aturan sesuai urutan block
> redirect
atau upgradeScheme
> allow
atau allowAllRequests
. Jika dua aturan memiliki jenis yang sama, Chrome akan memilih aturan dari ekstensi yang terakhir diinstal.
Sebelum header permintaan dikirim
Sebelum Chrome mengirim header permintaan ke server, header akan diupdate berdasarkan aturan modifyHeaders
yang cocok.
Dalam satu ekstensi, Chrome membuat daftar perubahan yang akan dilakukan dengan menemukan semua aturan modifyHeaders
yang cocok. Sama seperti sebelumnya, hanya aturan yang memiliki prioritas lebih tinggi daripada aturan allow
atau allowAllRequests
yang cocok yang akan disertakan.
Aturan ini diterapkan oleh Chrome sesuai urutan sehingga aturan dari ekstensi yang baru diinstal akan selalu dievaluasi sebelum aturan dari ekstensi lama. Selain itu, aturan dengan prioritas yang lebih tinggi dari satu ekstensi selalu diterapkan sebelum aturan dengan prioritas yang lebih rendah dari ekstensi yang sama. Secara khusus, bahkan di seluruh ekstensi:
- Jika aturan ditambahkan ke header, aturan dengan prioritas yang lebih rendah hanya dapat ditambahkan ke header tersebut. Operasi penetapan dan penghapusan tidak diizinkan.
- Jika aturan menetapkan header, maka hanya aturan berprioritas lebih rendah dari ekstensi yang sama yang dapat ditambahkan ke header tersebut. Tidak ada modifikasi lain yang diizinkan.
- Jika aturan menghapus header, aturan dengan prioritas yang lebih rendah tidak dapat mengubah header lebih lanjut.
Setelah respons diterima
Setelah header respons diterima, Chrome akan mengevaluasi aturan dengan kondisi responseHeaders
.
Setelah mengurutkan aturan ini menurut action
dan priority
serta mengecualikan aturan apa pun yang dibuat redundan oleh aturan allow
atau allowAllRequests
yang cocok (hal ini terjadi sama dengan langkah-langkah di "Sebelum permintaan"), Chrome dapat memblokir atau mengalihkan permintaan atas nama ekstensi.
Perhatikan bahwa jika permintaan berhasil sampai ke tahap ini, permintaan telah dikirim ke server dan server telah menerima data seperti isi permintaan. Aturan pemblokiran atau pengalihan dengan kondisi header respons akan tetap berjalan, tetapi tidak dapat benar-benar memblokir atau mengalihkan permintaan.
Dalam kasus aturan pemblokiran, hal ini ditangani oleh halaman yang membuat permintaan menerima respons yang diblokir, dan Chrome menghentikan permintaan lebih awal. Untuk aturan pengalihan, Chrome akan membuat permintaan baru ke URL yang dialihkan. Pastikan untuk mempertimbangkan apakah perilaku ini memenuhi ekspektasi privasi untuk ekstensi Anda.
Jika permintaan tidak diblokir atau dialihkan, Chrome akan menerapkan aturan modifyHeaders
apa pun. Penerapan modifikasi pada header respons berfungsi dengan cara yang sama seperti yang dijelaskan dalam "Sebelum header permintaan dikirim". Menerapkan perubahan pada header permintaan tidak melakukan apa pun, karena permintaan telah dibuat.
Aturan yang aman
Aturan yang aman ditentukan sebagai aturan dengan tindakan block
, allow
,
allowAllRequests
atau upgradeScheme
. Aturan ini tunduk kepada
kuota aturan dinamis.
Batas aturan
Ada overhead kinerja untuk memuat dan mengevaluasi aturan di browser, jadi beberapa batasan berlaku saat menggunakan API. Batasnya tergantung pada jenis aturan yang Anda gunakan.
Aturan statis
Aturan statis adalah aturan yang ditentukan dalam file aturan yang dideklarasikan dalam file manifes. Ekstensi dapat menentukan hingga 100 kumpulan aturan statis sebagai bagian dari kunci manifes "rule_resources"
, tetapi hanya 50 dari kumpulan aturan tersebut yang dapat diaktifkan dalam satu waktu. Yang kedua disebut MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. Secara kolektif, kumpulan aturan tersebut dijamin setidaknya 30.000 aturan. Ini disebut GUARANTEED_MINIMUM_STATIC_RULES
.
Jumlah aturan yang tersedia setelah tanggal tersebut bergantung pada jumlah aturan yang diaktifkan oleh semua ekstensi yang diinstal di browser pengguna. Anda dapat menemukan nomor ini pada runtime dengan memanggil getAvailableStaticRuleCount()
. Anda dapat melihat contohnya di bagian contoh kode.
Aturan sesi
Ekstensi dapat memiliki maksimal 5.000 aturan sesi. Hal ini diekspos karena
MAX_NUMBER_OF_SESSION_RULES
Sebelum Chrome 120, ada batas 5.000 aturan dinamis dan sesi gabungan.
Aturan dinamis
Ekstensi dapat memiliki minimal 5.000 aturan dinamis. Hal ini diekspos karena
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
Mulai Chrome 121, ada batas lebih besar yang tersedia, yaitu 30.000 aturan untuk aturan dinamis yang aman.
ditampilkan sebagai MAX_NUMBER_OF_DYNAMIC_RULES
. Apa saja
aturan tidak aman yang ditambahkan dalam batas 5.000 juga akan diperhitungkan dalam batas ini.
Sebelum Chrome 120, ada batas gabungan 5.000 aturan dinamis dan aturan sesi.
Aturan yang menggunakan ekspresi reguler
Semua jenis aturan dapat menggunakan ekspresi reguler; Namun, jumlah total aturan ekspresi reguler dari setiap jenis tidak boleh melebihi 1.000. Langkah ini disebut MAX_NUMBER_OF_REGEX_RULES.
Selain itu, setiap aturan harus kurang dari 2 KB setelah dikompilasi. Hal ini kurang lebih berkorelasi dengan kompleksitas aturan. Jika Anda mencoba memuat aturan yang melebihi batas ini, Anda akan melihat peringatan seperti berikut dan aturan akan diabaikan.
rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.
Interaksi dengan pekerja layanan
DeklaratifNetRequest hanya berlaku untuk permintaan yang mencapai tumpukan jaringan. Ini termasuk respons dari cache HTTP, tetapi mungkin tidak termasuk respons yang melalui pengendali onfetch
pekerja layanan. deklaratifNetRequest tidak akan memengaruhi respons yang dihasilkan oleh pekerja layanan atau yang diambil dari CacheStorage
, tetapi akan memengaruhi panggilan ke fetch()
yang dilakukan di pekerja layanan.
Referensi yang dapat diakses dari web
Aturan deklaratifNetRequest tidak dapat mengalihkan dari permintaan resource publik ke resource yang tidak dapat diakses dari web. Tindakan tersebut akan memicu error. Hal ini berlaku meskipun resource yang dapat diakses web yang ditentukan dimiliki oleh ekstensi pengalihan. Guna mendeklarasikan resource untuk deklaratifNetRequest, gunakan array "web_accessible_resources"
manifes.
Modifikasi header
Operasi penambahan hanya didukung untuk header berikut: accept
, accept-encoding
, accept-language
, access-control-request-headers
, cache-control
, connection
, content-language
, cookie
, forwarded
, if-match
, if-none-match
, keep-alive
, range
, te
, trailer
, transfer-encoding
, upgrade
, user-agent
, via
, want-digest
, x-forwarded-for
.
Contoh
Contoh kode
Perbarui aturan dinamis
Contoh berikut menunjukkan cara memanggil updateDynamicRules()
. Prosedur untuk updateSessionRules()
sama.
// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);
// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
removeRuleIds: oldRuleIds,
addRules: newRules
});
Perbarui kumpulan aturan statis
Contoh berikut menunjukkan cara mengaktifkan dan menonaktifkan kumpulan aturan sekaligus mempertimbangkan jumlah kumpulan aturan statis yang tersedia dan jumlah maksimum kumpulan aturan statis yang diaktifkan. Anda akan melakukannya ketika jumlah aturan statis yang dibutuhkan melebihi jumlah yang diizinkan. Agar hal ini berfungsi, beberapa kumpulan aturan harus diinstal dengan beberapa kumpulan aturan dinonaktifkan (menetapkan "Enabled"
ke false
dalam file manifes).
async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
// Create the options structure for the call to updateEnabledRulesets()
let options = { enableRulesetIds: enableRulesetIds }
// Get the number of enabled static rules
const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
// Compare rule counts to determine if anything needs to be disabled so that
// new rules can be enabled
const proposedCount = enableRulesetIds.length;
if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
options.disableRulesetIds = disableCandidateIds
}
// Update the enabled static rules
await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}
Contoh aturan
Contoh berikut menggambarkan cara Chrome memprioritaskan aturan dalam ekstensi. Saat meninjaunya, sebaiknya Anda membuka aturan prioritas di jendela terpisah.
"Prioritas" tombol
Contoh ini memerlukan izin host untuk *://*.example.com/*
.
Untuk mengetahui prioritas URL tertentu, lihat kunci "priority"
(yang ditentukan developer), kunci "action"
, dan kunci "urlFilter"
. Contoh ini merujuk pada file aturan contoh yang ditunjukkan di bawah ini.
- Navigasi ke https://google.com
- Dua aturan mencakup URL ini: aturan dengan ID 1 dan 4. Aturan dengan ID 1 berlaku karena tindakan
"block"
memiliki prioritas lebih tinggi daripada tindakan"redirect"
. Aturan lainnya tidak berlaku karena aturan tersebut ditujukan untuk URL yang lebih panjang. - Navigasi ke https://google.com/1234
- Karena URL yang lebih panjang, aturan dengan ID 2 kini cocok selain aturan dengan ID 1 dan 4. Aturan dengan ID 2 berlaku karena
"allow"
memiliki prioritas yang lebih tinggi daripada"block"
dan"redirect"
. - Navigasi ke https://google.com/12345
- Keempat aturan cocok dengan URL ini. Aturan dengan ID 3 berlaku karena prioritas yang ditentukan developer adalah yang tertinggi di grup.
[
{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
},
{
"id": 2,
"priority": 1,
"action": { "type": "allow" },
"condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
},
{
"id": 3,
"priority": 2,
"action": { "type": "block" },
"condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
},
{
"id": 4,
"priority": 1,
"action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
"condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
},
]
Pengalihan
Contoh di bawah memerlukan izin host untuk *://*.example.com/*
.
Contoh berikut menunjukkan cara mengalihkan permintaan dari example.com ke halaman dalam ekstensi itu sendiri. Jalur ekstensi /a.jpg
me-resolve ke chrome-extension://EXTENSION_ID/a.jpg
, dengan EXTENSION_ID
adalah ID ekstensi Anda. Agar berfungsi, manifes harus mendeklarasikan /a.jpg
sebagai resource yang dapat diakses web.
{
"id": 1,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": {
"urlFilter": "||https://www.example.com/",
"resourceTypes": ["main_frame"]
}
}
Berikut ini menggunakan kunci "transform"
untuk mengalihkan ke subdomain example.com. Fungsi ini menggunakan anchor nama domain ("||") untuk menangkap permintaan dengan skema apa pun dari example.com. Kunci "scheme"
di "transform"
menentukan bahwa pengalihan ke subdomain akan selalu menggunakan "https".
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com/",
"resourceTypes": ["main_frame"]
}
}
Contoh berikut menggunakan ekspresi reguler untuk mengalihkan dari https://www.abc.xyz.com/path
ke https://abc.xyz.com/path
. Dalam kunci "regexFilter"
, perhatikan bagaimana periode di-escape dan grup yang menangkap memilih "abc" atau "def". Kunci "regexSubstitution"
menentukan kecocokan pertama yang ditampilkan dari ekspresi reguler menggunakan "\1". Dalam hal ini, "abc" diambil dari URL yang dialihkan dan
ditempatkan sebagai pengganti.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"regexSubstitution": "https://\\1.xyz.com/"
}
},
"condition": {
"regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
"resourceTypes": [
"main_frame"
]
}
}
Header
Contoh berikut menghapus semua cookie dari frame utama dan subframe.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
Jenis
DomainType
Ini menjelaskan apakah permintaan merupakan pihak pertama atau pihak ketiga dalam frame tempat permintaan berasal. Permintaan disebut sebagai pihak pertama jika memiliki domain yang sama (eTLD+1) dengan frame tempat permintaan berasal.
Enum
"firstParty"
Permintaan jaringan adalah pihak pertama dalam frame tempat permintaan tersebut berasal.
"thirdParty"
Permintaan jaringan adalah pihak ketiga dalam frame tempat permintaan tersebut berasal.
ExtensionActionOptions
Properti
-
displayActionCountAsBadgeText
boolean opsional
Apakah akan otomatis menampilkan jumlah tindakan untuk halaman sebagai teks badge ekstensi. Preferensi ini dipertahankan di seluruh sesi.
-
tabUpdate
TabActionCountUpdate opsional
Chrome 89 dan yang lebih baruDetail tentang cara menyesuaikan jumlah tindakan tab.
GetDisabledRuleIdsOptions
Properti
-
rulesetId
string
ID yang sesuai dengan
Ruleset
statis.
GetRulesFilter
Properti
-
ruleIds
number[] opsional
Jika ditentukan, hanya aturan dengan ID yang cocok yang disertakan.
HeaderInfo
Properti
-
excludedValues
string[] opsional
Jika ditentukan, kondisi ini tidak akan cocok jika header ada, tetapi nilainya berisi setidaknya satu elemen dalam daftar ini. Ini menggunakan sintaksis pola pencocokan yang sama dengan
values
. -
header
string
Nama {i>header<i}. Kondisi ini cocok pada nama hanya jika
values
danexcludedValues
tidak ditentukan. -
nilai
string[] opsional
Jika ditentukan, kondisi ini akan cocok jika nilai header cocok setidaknya dengan satu pola dalam daftar ini. Hal ini mendukung pencocokan nilai header yang tidak peka huruf besar/kecil dan konstruksi berikut:
'*' : Mencocokkan sejumlah karakter.
'?' : Mencocokkan nol atau satu karakter.
'*' dan '?' bisa di-escape dengan garis miring terbalik, mis. '\*' dan '\?'
HeaderOperation
Bagian ini menjelaskan kemungkinan operasi untuk "ModifyHeaders" aturan.
Enum
"append"
Menambahkan entri baru untuk header yang ditentukan. Operasi ini tidak didukung untuk header permintaan.
"set"
Menetapkan nilai baru untuk header yang ditentukan, menghapus header yang ada yang memiliki nama yang sama.
"remove"
Menghapus semua entri untuk header yang ditentukan.
IsRegexSupportedResult
Properti
-
isSupported
boolean
-
alasan
UnsupportedRegexReason opsional
Menentukan alasan mengapa ekspresi reguler tidak didukung. Hanya diberikan jika
isSupported
salah.
MatchedRule
Properti
-
ruleId
angka
ID aturan yang cocok.
-
rulesetId
string
ID
Ruleset
yang memiliki aturan ini. Untuk aturan yang berasal dari kumpulan aturan dinamis, nilainya akan sama denganDYNAMIC_RULESET_ID
.
MatchedRuleInfo
Properti
-
aturan
-
tabId
angka
TabId tab tempat permintaan berasal jika tab masih aktif. Selain -1.
-
timeStamp
angka
Waktu aturan dicocokkan. Stempel waktu akan sesuai dengan konvensi JavaScript untuk waktu, yaitu jumlah milidetik sejak epoch.
MatchedRuleInfoDebug
Properti
-
minta
Detail tentang permintaan yang cocok dengan aturan.
-
aturan
MatchedRulesFilter
Properti
-
minTimeStamp
angka opsional
Jika ditentukan, hanya akan cocok dengan aturan setelah stempel waktu yang diberikan.
-
tabId
angka opsional
Jika ditentukan, hanya cocok dengan aturan untuk tab yang ditentukan. Mencocokkan aturan yang tidak terkait dengan tab aktif jika ditetapkan ke -1.
ModifyHeaderInfo
Properti
-
header
string
Nama header yang akan diubah.
-
operasi
Operasi yang akan dijalankan pada header.
-
nilai
string opsional
Nilai baru untuk header. Harus ditetapkan untuk operasi
append
danset
.
QueryKeyValue
Properti
-
kunci
string
-
replaceOnly
boolean opsional
Chrome 94 dan yang lebih baruJika true (benar), kunci kueri akan diganti hanya jika sudah ada. Jika tidak, kunci juga akan ditambahkan. Nilai defaultnya adalah false (salah).
-
nilai
string
QueryTransform
Properti
-
addOrReplaceParams
QueryKeyValue[] opsional
Daftar pasangan nilai kunci kueri yang akan ditambahkan atau diganti.
-
removeParams
string[] opsional
Daftar kunci kueri yang akan dihapus.
Redirect
Properti
-
extensionPath
string opsional
Jalur yang terkait dengan direktori ekstensi. Harus diawali dengan '/'.
-
regexSubstitution
string opsional
Pola substitusi untuk aturan yang menentukan
regexFilter
. Kecocokan pertamaregexFilter
dalam URL akan diganti dengan pola ini. DalamregexSubstitution
, digit yang di-escape garis miring terbalik (\1 hingga \9) dapat digunakan untuk menyisipkan grup tangkapan yang sesuai. \0 merujuk pada keseluruhan teks yang cocok. -
dan mengubah teks tersebut
URLTransform opsional
Transformasi URL yang akan dijalankan.
-
url
string opsional
URL pengalihan. Pengalihan ke URL JavaScript tidak diizinkan.
RegexOptions
Properti
-
isCaseSensitive
boolean opsional
Apakah
regex
yang ditentukan peka huruf besar/kecil. Defaultnya adalah true (benar). -
ekspresi reguler
string
Expresson reguler yang akan diperiksa.
-
requireCapturing
boolean opsional
Apakah
regex
yang ditentukan memerlukan pengambilan gambar atau tidak. Pengambilan hanya diperlukan untuk aturan pengalihan yang menentukan tindakanregexSubstition
. Default-nya adalah salah.
RequestDetails
Properti
-
documentId
string opsional
Chrome 106 dan yang lebih baruID unik untuk dokumen frame, jika permintaan ini ditujukan untuk frame.
-
documentLifecycle
DocumentLifecycle opsional
Chrome 106 dan yang lebih baruSiklus proses dokumen frame, jika permintaan ini untuk frame.
-
frameId
angka
Nilai 0 menunjukkan bahwa permintaan terjadi di frame utama; nilai positif menunjukkan ID subframe tempat permintaan terjadi. Jika dokumen dari frame (sub) dimuat (
type
adalahmain_frame
atausub_frame
),frameId
menunjukkan ID frame ini, bukan ID frame luar. ID frame bersifat unik dalam satu tab. -
frameType
FrameType opsional
Chrome 106 dan yang lebih baruJenis frame, jika permintaan ini ditujukan untuk frame.
-
inisiator
string opsional
Asal tempat permintaan dimulai. Hal ini tidak berubah melalui pengalihan. Jika asal ini buram, string 'null' data yang akan digunakan.
-
method
string
Metode HTTP standar.
-
parentDocumentId
string opsional
Chrome 106 dan yang lebih baruID unik untuk dokumen induk frame, jika permintaan ini ditujukan untuk frame dan memiliki induk.
-
parentFrameId
angka
ID frame yang menggabungkan frame yang mengirim permintaan. Setel ke -1 jika tidak ada frame induk.
-
requestId
string
ID permintaan. ID permintaan bersifat unik dalam sesi browser.
-
tabId
angka
ID tab tempat permintaan terjadi. Tetapkan ke -1 jika permintaan tidak terkait dengan tab.
-
jenis
Jenis resource permintaan.
-
url
string
URL permintaan.
RequestMethod
Ini menjelaskan metode permintaan HTTP dari permintaan jaringan.
Enum
"hubungkan"
"hapus"
"dapatkan"
"head"
"opsi"
"patch"
"postingan"
"put"
"lainnya"
ResourceType
Ini menjelaskan jenis resource permintaan jaringan.
Enum
"main_frame"
"sub_frame"
"stylesheet"
"script"
"gambar"
"font"
"objek"
"xmlhttprequest"
"ping"
"csp_report"
"media"
"websocket"
"transport web"
"webbundle"
"lainnya"
Rule
Properti
-
action
Tindakan yang akan dilakukan jika aturan ini cocok.
-
kondisi
Kondisi yang memicu aturan ini.
-
id
angka
ID yang mengidentifikasi aturan secara unik. Wajib dan harus >= 1.
-
prioritas
angka opsional
Prioritas aturan. Default-nya adalah 1. Jika ditentukan, harus >= 1.
RuleAction
Properti
-
alihkan
Pengalihan opsional
Menjelaskan cara pengalihan harus dilakukan. Hanya valid untuk aturan pengalihan.
-
requestHeaders
ModifyHeaderInfo[] opsional
Chrome 86 dan yang lebih baruHeader permintaan yang akan diubah untuk permintaan. Hanya valid jika RuleActionType adalah "ModifyHeaders".
-
responseHeaders
ModifyHeaderInfo[] opsional
Chrome 86 dan yang lebih baruHeader respons yang akan diubah untuk permintaan. Hanya valid jika RuleActionType adalah "ModifyHeaders".
-
jenis
Jenis tindakan yang akan dilakukan.
RuleActionType
Menjelaskan jenis tindakan yang akan diambil jika RuleCondition tertentu cocok.
Enum
"blokir"
Memblokir permintaan jaringan.
"redirect"
Mengalihkan permintaan jaringan.
"allow"
Izinkan permintaan jaringan. Permintaan tidak akan dicegat jika ada aturan izinkan yang cocok.
"upgradeScheme"
Upgrade skema URL permintaan jaringan ke https jika permintaannya adalah http atau ftp.
"ModifyHeader"
Ubah header permintaan/respons dari permintaan jaringan.
"allowAllRequests"
Mengizinkan semua permintaan dalam hierarki frame, termasuk permintaan frame itu sendiri.
RuleCondition
Properti
-
domainType
DomainType opsional
Menentukan apakah permintaan jaringan merupakan pihak pertama atau pihak ketiga ke domain tempat permintaan berasal. Jika dihilangkan, semua permintaan diterima.
-
domains
string[] opsional
Tidak digunakan lagi sejak Chrome 101Gunakan
initiatorDomains
sebagai gantinyaAturan hanya akan cocok dengan permintaan jaringan yang berasal dari daftar
domains
. -
excludedDomains
string[] opsional
Tidak digunakan lagi sejak Chrome 101Gunakan
excludedInitiatorDomains
sebagai gantinyaAturan tidak akan cocok dengan permintaan jaringan yang berasal dari daftar
excludedDomains
. -
excludedInitiatorDomains
string[] opsional
Chrome 101 dan yang lebih baruAturan tidak akan cocok dengan permintaan jaringan yang berasal dari daftar
excludedInitiatorDomains
. Jika daftar kosong atau dihilangkan, tidak ada domain yang dikecualikan. Opsi ini lebih diutamakan daripadainitiatorDomains
.Catatan:
- Sub-domain seperti "a.example.com" juga diizinkan.
- Entri hanya boleh berisi karakter ASCII.
- Gunakan encoding punycode untuk domain internasional.
- URL ini cocok dengan inisiator permintaan, bukan URL permintaan.
- Sub-domain dari domain yang tercantum juga dikecualikan.
-
excludedRequestDomains
string[] opsional
Chrome 101 dan yang lebih baruAturan tidak akan cocok dengan permintaan jaringan jika domain cocok dengan permintaan dari daftar
excludedRequestDomains
. Jika daftar kosong atau dihilangkan, tidak ada domain yang dikecualikan. Opsi ini lebih diutamakan daripadarequestDomains
.Catatan:
- Sub-domain seperti "a.example.com" juga diizinkan.
- Entri hanya boleh berisi karakter ASCII.
- Gunakan encoding punycode untuk domain internasional.
- Sub-domain dari domain yang tercantum juga dikecualikan.
-
excludedRequestMethods
RequestMethod[] opsional
Chrome 91 dan yang lebih baruDaftar metode permintaan yang tidak akan cocok dengan aturan. Hanya
requestMethods
danexcludedRequestMethods
yang harus ditentukan. Jika tidak satu pun dari keduanya ditentukan, semua metode permintaan akan cocok. -
excludedResourceTypes
ResourceType[] opsional
Daftar jenis resource yang tidak cocok dengan aturan. Hanya
resourceTypes
danexcludedResourceTypes
yang harus ditentukan. Jika tidak ada yang ditentukan, semua jenis resource kecuali "main_frame" diblokir. -
excludedResponseHeaders
HeaderInfo[] opsional
Chrome 128 dan yang lebih baruAturan tidak cocok jika permintaan cocok dengan kondisi header respons apa pun dalam daftar ini (jika ditentukan). Jika
excludedResponseHeaders
danresponseHeaders
ditentukan, propertiexcludedResponseHeaders
akan diprioritaskan. -
excludedTabIds
number[] opsional
Chrome 92 dan yang lebih baruDaftar
tabs.Tab.id
yang tidak boleh cocok dengan aturan. IDtabs.TAB_ID_NONE
tidak mencakup permintaan yang tidak berasal dari tab. Hanya didukung untuk aturan cakupan sesi. -
initiatorDomains
string[] opsional
Chrome 101 dan yang lebih baruAturan hanya akan cocok dengan permintaan jaringan yang berasal dari daftar
initiatorDomains
. Jika daftar dihapus, aturan akan diterapkan ke permintaan dari semua domain. Daftar kosong tidak diizinkan.Catatan:
- Sub-domain seperti "a.example.com" juga diizinkan.
- Entri hanya boleh berisi karakter ASCII.
- Gunakan encoding punycode untuk domain internasional.
- URL ini cocok dengan inisiator permintaan, bukan URL permintaan.
- Sub-domain dari domain yang tercantum juga cocok.
-
isUrlFilterCaseSensitive
boolean opsional
Apakah
urlFilter
atauregexFilter
(mana saja yang ditentukan) peka huruf besar/kecil. Defaultnya adalah false. -
regexFilter
string opsional
Ekspresi reguler yang akan dicocokkan dengan URL permintaan jaringan. Kode ini mengikuti sintaksis RE2.
Catatan: Hanya satu dari
urlFilter
atauregexFilter
yang dapat ditentukan.Catatan:
regexFilter
harus terdiri dari karakter ASCII saja. Ini dicocokkan dengan URL tempat host dienkodekan dalam format punycode (untuk domain yang diinternasionalkan) dan karakter non-ASCII lainnya dienkode ke URL dengan kode utf-8. -
requestDomains
string[] opsional
Chrome 101 dan yang lebih baruAturan hanya akan cocok dengan permintaan jaringan jika domain cocok dengan permintaan dari daftar
requestDomains
. Jika daftar dihapus, aturan akan diterapkan ke permintaan dari semua domain. Daftar kosong tidak diizinkan.Catatan:
- Sub-domain seperti "a.example.com" juga diizinkan.
- Entri hanya boleh berisi karakter ASCII.
- Gunakan encoding punycode untuk domain internasional.
- Sub-domain dari domain yang tercantum juga cocok.
-
requestMethods
RequestMethod[] opsional
Chrome 91 dan yang lebih baruDaftar metode permintaan HTTP yang dapat cocok dengan aturan. Daftar kosong tidak diizinkan.
Catatan: Menentukan kondisi aturan
requestMethods
juga akan mengecualikan permintaan non-HTTP, sedangkan menetapkanexcludedRequestMethods
tidak akan mengecualikannya. -
resourceTypes
ResourceType[] opsional
Daftar jenis resource yang dapat cocok dengan aturan tersebut. Daftar kosong tidak diizinkan.
Catatan: hal ini harus ditentukan untuk aturan
allowAllRequests
dan hanya dapat menyertakan jenis resourcesub_frame
danmain_frame
. -
responseHeaders
HeaderInfo[] opsional
Chrome 128 dan yang lebih baruAturan cocok jika permintaan cocok dengan kondisi header respons apa pun dalam daftar ini (jika ditentukan).
-
tabIds
number[] opsional
Chrome 92 dan yang lebih baruDaftar
tabs.Tab.id
yang harus cocok dengan aturan. IDtabs.TAB_ID_NONE
cocok dengan permintaan yang tidak berasal dari tab. Daftar kosong tidak diizinkan. Hanya didukung untuk aturan cakupan sesi. -
urlFilter
string opsional
Pola yang dicocokkan dengan URL permintaan jaringan. Konstruksi yang didukung:
'*' : Karakter pengganti: Mencocokkan sejumlah karakter.
'|' : Anchor kiri/kanan: Jika digunakan di salah satu ujung pola, menentukan awal/akhir URL.
'||' : Anchor nama domain: Jika digunakan di awal pola, tentukan awal (sub-domain) URL.
'^' : Karakter pemisah: Karakter ini cocok dengan apa pun kecuali huruf, angka, atau salah satu dari berikut:
_
,-
,.
, atau%
. URL ini juga cocok dengan bagian akhir URL.Oleh karena itu,
urlFilter
terdiri dari bagian-bagian berikut: (Anchor nama Kiri/Domain opsional) + pola + (Anchor Kanan opsional).Jika dihilangkan, semua URL akan dicocokkan. String kosong tidak diizinkan.
Pola yang dimulai dengan
||*
tidak diizinkan. Sebagai gantinya, gunakan*
.Catatan: Hanya satu dari
urlFilter
atauregexFilter
yang dapat ditentukan.Catatan:
urlFilter
harus terdiri dari karakter ASCII saja. Ini dicocokkan dengan URL tempat host dienkodekan dalam format punycode (untuk domain yang diinternasionalkan) dan karakter non-ASCII lainnya dienkode ke URL dengan kode utf-8. Misalnya, jika URL permintaan adalah http://abc.Pjj?q=ser,urlFilter
akan dicocokkan dengan URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
Properti
-
diaktifkan
boolean
Apakah kumpulan aturan diaktifkan secara default.
-
id
string
String yang tidak kosong secara unik mengidentifikasi kumpulan aturan. ID yang diawali dengan '_' disediakan untuk penggunaan internal.
-
jalur
string
Jalur kumpulan aturan JSON relatif terhadap direktori ekstensi.
RulesMatchedDetails
Properti
-
rulesMatchedInfo
Aturan yang cocok dengan filter yang diberikan.
TabActionCountUpdate
Properti
-
penambahan
angka
Jumlah yang akan digunakan untuk menambah jumlah tindakan tab. Nilai negatif akan mengurangi jumlahnya.
-
tabId
angka
Tab yang akan digunakan untuk memperbarui jumlah tindakan.
TestMatchOutcomeResult
Properti
-
matchedRules
Aturan (jika ada) yang cocok dengan permintaan hipotesis.
TestMatchRequestDetails
Properti
-
inisiator
string opsional
URL inisiator (jika ada) untuk permintaan fiktif.
-
method
RequestMethod opsional
Metode HTTP standar dari permintaan fiktif. Setelan defaultnya adalah "get" untuk permintaan HTTP dan diabaikan untuk permintaan non-HTTP.
-
responseHeaders
objek opsional
TertundaHeader yang diberikan oleh respons hipotesis jika permintaan tidak diblokir atau dialihkan sebelum dikirim. Direpresentasikan sebagai objek yang memetakan nama header ke daftar nilai string. Jika tidak ditentukan, respons hipotesis akan menampilkan header respons kosong, yang dapat mencocokkan aturan yang cocok dengan header yang tidak ada. Mis.
{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}
-
tabId
angka opsional
ID tab tempat permintaan hipotetis terjadi. Tidak harus sesuai dengan ID tab sebenarnya. Defaultnya adalah -1, artinya permintaan tidak terkait dengan tab.
-
jenis
Jenis resource permintaan hipotetis.
-
url
string
URL permintaan hipotesis.
UnsupportedRegexReason
Menjelaskan alasan mengapa ekspresi reguler tertentu tidak didukung.
Enum
"syntaxError"
Ekspresi reguler salah secara sintaksis, atau menggunakan fitur yang tidak tersedia di sintaksis RE2.
"memoryLimitExceeded"
Ekspresi reguler melebihi batas memori.
UpdateRuleOptions
Properti
-
addRules
Aturan[] opsional
Aturan untuk ditambahkan.
-
removeRuleIds
number[] opsional
ID aturan yang akan dihapus. ID yang tidak valid akan diabaikan.
UpdateRulesetOptions
Properti
UpdateStaticRulesOptions
Properti
URLTransform
Properti
-
fragmen
string opsional
Fragmen baru untuk permintaan. Harus kosong, jika fragmen yang ada akan dihapus; atau harus diawali dengan '#'.
-
host
string opsional
Host baru untuk permintaan.
-
sandi
string opsional
Sandi baru untuk permintaan.
-
jalur
string opsional
Jalur baru untuk permintaan. Jika kosong, jalur yang ada akan dihapus.
-
port
string opsional
Port baru untuk permintaan. Jika kosong, port yang ada akan dihapus.
-
kueri
string opsional
Kueri baru untuk permintaan. Harus kosong, dalam hal ini kueri yang ada akan dihapus; atau harus diawali dengan '?'.
-
queryTransform
QueryTransform opsional
Menambahkan, menghapus, atau mengganti pasangan nilai kunci kueri.
-
skema
string opsional
Skema baru untuk permintaan. Nilai yang diizinkan adalah "http", "https", "ftp" dan "chrome-extension".
-
nama pengguna
string opsional
Nama pengguna baru untuk permintaan.
Properti
DYNAMIC_RULESET_ID
ID kumpulan aturan untuk aturan dinamis yang ditambahkan oleh ekstensi.
Nilai
"_dinamis"
GETMATCHEDRULES_QUOTA_INTERVAL
Interval waktu saat panggilan MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
dapat dilakukan, yang ditentukan dalam menit. Panggilan lainnya akan langsung gagal dan tetapkan runtime.lastError
. Catatan: Panggilan getMatchedRules
yang terkait dengan gestur pengguna dikecualikan dari kuota.
Nilai
10
GUARANTEED_MINIMUM_STATIC_RULES
Jumlah minimum aturan statis yang dijamin untuk suatu ekstensi di seluruh kumpulan aturan statis yang diaktifkan. Setiap aturan yang melebihi batas ini akan diperhitungkan dalam batas aturan statis global.
Nilai
30.000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Berapa kali getMatchedRules
dapat dipanggil dalam jangka waktu GETMATCHEDRULES_QUOTA_INTERVAL
.
Nilai
20
MAX_NUMBER_OF_DYNAMIC_RULES
Jumlah maksimum aturan dinamis yang dapat ditambahkan oleh ekstensi.
Nilai
30.000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
Jumlah maksimum Rulesets
statis yang dapat diaktifkan ekstensi pada satu waktu.
Nilai
50
MAX_NUMBER_OF_REGEX_RULES
Jumlah maksimum aturan ekspresi reguler yang dapat ditambahkan ekstensi. Batas ini dievaluasi secara terpisah untuk kumpulan aturan dinamis dan yang ditentukan di file resource aturan.
Nilai
1.000
MAX_NUMBER_OF_SESSION_RULES
Jumlah maksimum aturan cakupan sesi yang dapat ditambahkan oleh ekstensi.
Nilai
5.000
MAX_NUMBER_OF_STATIC_RULESETS
Jumlah maksimum Rulesets
statis yang dapat ditentukan ekstensi sebagai bagian dari kunci manifes "rule_resources"
.
Nilai
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
Jumlah maksimum "tidak aman" aturan dinamis yang dapat ditambahkan oleh ekstensi.
Nilai
5.000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
Jumlah maksimum "tidak aman" aturan cakupan sesi yang dapat ditambahkan oleh ekstensi.
Nilai
5.000
SESSION_RULESET_ID
ID kumpulan aturan untuk aturan cakupan sesi yang ditambahkan oleh ekstensi.
Nilai
"_session"
Metode
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
Menampilkan jumlah aturan statis yang dapat diaktifkan ekstensi sebelum batas aturan statis global tercapai.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(count: number) => void
-
jumlah
angka
-
Hasil
-
Promise<number>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
Menampilkan daftar aturan statis dalam Ruleset
tertentu yang saat ini dinonaktifkan.
Parameter
-
Menentukan kumpulan aturan yang akan dikueri.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(disabledRuleIds: number[]) => void
-
disabledRuleIds
angka[]
-
Hasil
-
Janji<number[]>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
Menampilkan kumpulan aturan dinamis saat ini untuk ekstensi. Pemanggil dapat secara opsional memfilter daftar aturan yang diambil dengan menentukan filter
.
Parameter
-
filter
GetRulesFilter opsional
Chrome 111 dan yang lebih baruObjek untuk memfilter daftar aturan yang diambil.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(rules: Rule[]) => void
-
rules
Aturan[]
-
Hasil
-
Promise<Aturan[]>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
Menampilkan ID untuk kumpulan set aturan statis yang aktif saat ini.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(rulesetIds: string[]) => void
-
rulesetIds
{i>string<i}[]
-
Hasil
-
Promise<string[]>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
Menampilkan semua aturan yang cocok untuk ekstensi. Pemanggil dapat secara opsional memfilter daftar aturan yang cocok dengan menentukan filter
. Metode ini hanya tersedia untuk ekstensi dengan izin "declarativeNetRequestFeedback"
atau memiliki izin "activeTab"
yang diberikan untuk tabId
yang ditentukan dalam filter
. Catatan: Aturan yang tidak terkait dengan dokumen aktif yang cocok lebih dari lima menit yang lalu tidak akan ditampilkan.
Parameter
-
filter
MatchedRulesFilter opsional
Objek untuk memfilter daftar aturan yang cocok.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(details: RulesMatchedDetails) => void
-
detail
-
Hasil
-
Promise<RulesMatchedDetails>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
Menampilkan kumpulan aturan cakupan sesi saat ini untuk ekstensi. Pemanggil dapat secara opsional memfilter daftar aturan yang diambil dengan menentukan filter
.
Parameter
-
filter
GetRulesFilter opsional
Chrome 111 dan yang lebih baruObjek untuk memfilter daftar aturan yang diambil.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(rules: Rule[]) => void
-
rules
Aturan[]
-
Hasil
-
Promise<Aturan[]>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
Memeriksa apakah ekspresi reguler yang diberikan akan didukung sebagai kondisi aturan regexFilter
.
Parameter
-
regexOptions
Ekspresi reguler yang akan diperiksa.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(result: IsRegexSupportedResult) => void
-
hasil
-
Hasil
-
Promise<IsRegexSupportedResult>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
Mengonfigurasi apakah jumlah tindakan untuk tab harus ditampilkan sebagai teks badge tindakan ekstensi dan dapat meningkatkan jumlah tindakan tersebut.
Parameter
-
callback
fungsi opsional
Chrome 89 dan yang lebih baruParameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
Memeriksa apakah salah satu aturan deklaratifNetRequest ekstensi cocok dengan permintaan fiktif. Catatan: Hanya tersedia untuk ekstensi yang belum dipaketkan karena hanya dimaksudkan untuk digunakan selama pengembangan ekstensi.
Parameter
-
minta
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(result: TestMatchOutcomeResult) => void
-
hasil
-
Hasil
-
Promise<TestMatchOutcomeResult>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
Mengubah kumpulan aturan dinamis saat ini untuk ekstensi. Aturan dengan ID yang tercantum di options.removeRuleIds
akan dihapus terlebih dahulu, lalu aturan yang diberikan dalam options.addRules
akan ditambahkan. Catatan:
- Update ini terjadi sebagai operasi atomik tunggal: semua aturan yang ditentukan ditambahkan dan dihapus, atau error akan ditampilkan.
- Aturan ini dipertahankan di seluruh sesi browser dan seluruh update ekstensi.
- Aturan statis yang ditentukan sebagai bagian dari paket ekstensi tidak dapat dihapus menggunakan fungsi ini.
MAX_NUMBER_OF_DYNAMIC_RULES
adalah jumlah maksimum aturan dinamis yang dapat ditambahkan oleh ekstensi. Jumlah aturan yang tidak aman tidak boleh lebih dariMAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
.
Parameter
-
opsiChrome 87 dan yang lebih baru
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
Memperbarui kumpulan aturan statis yang diaktifkan untuk ekstensi. Kumpulan aturan dengan ID yang tercantum dalam options.disableRulesetIds
akan dihapus terlebih dahulu, lalu kumpulan aturan yang tercantum dalam options.enableRulesetIds
akan ditambahkan.
Perhatikan bahwa kumpulan kumpulan aturan statis yang diaktifkan akan dipertahankan di seluruh sesi, tetapi tidak di seluruh update ekstensi, yaitu kunci manifes rule_resources
akan menentukan kumpulan aturan statis yang diaktifkan pada setiap update ekstensi.
Parameter
-
opsiChrome 87 dan yang lebih baru
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
Mengubah kumpulan aturan cakupan sesi saat ini untuk ekstensi. Aturan dengan ID yang tercantum di options.removeRuleIds
akan dihapus terlebih dahulu, lalu aturan yang diberikan dalam options.addRules
akan ditambahkan. Catatan:
- Update ini terjadi sebagai operasi atomik tunggal: semua aturan yang ditentukan ditambahkan dan dihapus, atau error akan ditampilkan.
- Aturan ini tidak dipertahankan di seluruh sesi dan dicadangkan di memori.
MAX_NUMBER_OF_SESSION_RULES
adalah jumlah maksimum aturan sesi yang dapat ditambahkan ekstensi.
Parameter
-
opsi
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 91 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
Menonaktifkan dan mengaktifkan setiap aturan statis di Ruleset
. Perubahan pada aturan milik Ruleset
yang dinonaktifkan akan berlaku saat kebijakan tersebut diaktifkan lagi.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
Acara
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
Diaktifkan saat aturan cocok dengan permintaan. Hanya tersedia untuk ekstensi yang belum dipaketkan dengan izin "declarativeNetRequestFeedback"
karena dimaksudkan untuk digunakan hanya untuk tujuan proses debug.
Parameter
-
callback
fungsi
Parameter
callback
terlihat seperti ini:(info: MatchedRuleInfoDebug) => void
-
info
-