browser.declarativeNetRequest

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 privasi yang lebih baik.

Izin

declarativeNetRequest
declarativeNetRequestWithHostAccess

Izin "declarativeNetRequest" dan "declarativeNetRequestWithHostAccess" memberikan kemampuan yang sama. Perbedaan di antara keduanya adalah kapan izin diminta atau diberikan.

"declarativeNetRequest"
Memicu peringatan izin pada waktu penginstalan, tetapi memberikan akses implisit ke aturan allow, allowAllRequests, dan block. Gunakan ini jika memungkinkan untuk menghindari perlunya meminta akses penuh ke host.
"declarativeNetRequestFeedback"
Mengaktifkan fitur proses debug untuk ekstensi mode developer, khususnya getMatchedRules() dan onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Peringatan izin tidak ditampilkan pada waktu penginstalan, tetapi Anda harus meminta izin host sebelum dapat melakukan tindakan apa pun di host. Hal ini sesuai jika Anda ingin menggunakan aturan permintaan jaringan deklaratif dalam ekstensi yang sudah memiliki izin host tanpa membuat peringatan tambahan.

Ketersediaan

Chrome 84+ browser.* sejak Chrome 148

Manifes

Selain izin yang dijelaskan sebelumnya, jenis kumpulan aturan tertentu, khususnya kumpulan aturan statis, memerlukan deklarasi kunci manifes "declarative_net_request", yang harus berupa kamus dengan satu kunci bernama "rule_resources". Kunci ini adalah array yang berisi kamus jenis Ruleset, seperti yang ditunjukkan berikut ini. (Perhatikan bahwa nama 'Ruleset' tidak muncul di JSON manifes karena hanya berupa array.) Set aturan statis 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 set aturan

Untuk menggunakan API ini, tentukan satu atau beberapa ruleset. Set aturan berisi array aturan. Satu aturan melakukan salah satu hal berikut:

  • Memblokir permintaan jaringan.
  • Mengupgrade skema (http ke https).
  • Mencegah permintaan diblokir dengan meniadakan aturan yang diblokir yang cocok.
  • Mengalihkan permintaan jaringan.
  • Mengubah header permintaan atau respons.

Ada tiga jenis set aturan, yang dikelola dengan cara yang sedikit berbeda.

Dinamis
Bertahan di seluruh sesi browser dan upgrade ekstensi, serta dikelola menggunakan JavaScript saat ekstensi sedang digunakan.
Sesi
Dihapus saat browser dimatikan dan saat versi baru ekstensi diinstal. Aturan sesi dikelola menggunakan JavaScript saat ekstensi sedang digunakan.
Statis
Dipaketkan, diinstal, dan diupdate saat ekstensi diinstal atau diupgrade. Aturan statis disimpan dalam file aturan berformat JSON dan tercantum dalam file manifes.

Set aturan dinamis dan cakupan sesi

Aturan dinamis dan sesi dikelola menggunakan JavaScript saat ekstensi sedang digunakan.

  • Aturan dinamis tetap ada di seluruh sesi browser dan upgrade ekstensi.
  • Aturan sesi akan dihapus saat browser dimatikan dan saat versi baru ekstensi diinstal.

Hanya ada satu dari setiap jenis set aturan ini. Ekstensi dapat menambahkan atau menghapus aturan 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 dipaketkan, diinstal, dan diupdate saat ekstensi diinstal atau diupgrade. Aturan ini 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 ruleset yang terdapat dalam file, dan apakah ruleset diaktifkan atau dinonaktifkan. Dua yang terakhir penting saat Anda mengaktifkan atau menonaktifkan ruleset secara terprogram.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Untuk menguji file aturan, muat ekstensi yang belum dipaketkan. Error dan peringatan tentang aturan statis yang tidak valid hanya ditampilkan untuk ekstensi yang tidak dipaketkan. Aturan statis yang tidak valid dalam ekstensi yang dipaketkan akan diabaikan.

Peninjauan yang dipercepat

Perubahan pada aturan statis mungkin memenuhi syarat untuk peninjauan yang dipercepat. Lihat peninjauan yang dipercepat untuk perubahan yang memenuhi syarat.

Mengaktifkan dan menonaktifkan aturan dan ruleset statis

Aturan statis individual dan set aturan statis lengkap dapat diaktifkan atau dinonaktifkan saat runtime.

Kumpulan aturan dan set aturan statis yang diaktifkan akan dipertahankan di seluruh sesi browser. Keduanya tidak dipertahankan di seluruh update ekstensi, yang berarti hanya aturan yang Anda pilih untuk dibiarkan dalam file aturan yang tersedia setelah update.

Untuk alasan performa, ada juga batasan jumlah aturan dan set 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 menggunakan 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 ruleset statis, panggil updateEnabledRulesets(). Metode ini menggunakan objek UpdateRulesetOptions, yang berisi array ID ruleset yang akan diaktifkan atau dinonaktifkan. ID ditentukan menggunakan kunci "id" dari kamus Ruleset.

Aturan build

Apa pun jenisnya, aturan dimulai dengan empat kolom seperti yang ditunjukkan berikut. Meskipun kunci "id" dan "priority" menggunakan 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 mana 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 pencocokan pola atau ekspresi reguler.

Sintaksis filter URL

Kunci "condition" aturan memungkinkan kunci "urlFilter" untuk bertindak pada URL di domain yang ditentukan. Anda 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 kunci "regexFilter". Untuk mempelajari batasan yang berlaku untuk kondisi ini, 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 Anda mungkin cocok dalam situasi yang tidak terduga. Misalnya, saat menggunakan sintaksis pencocokan pola:

  • google.com salah mencocokkan https://example.com/?param=google.com
  • ||google.com salah mencocokkan https://google.company
  • https://www.google.com salah mencocokkan https://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 mengaitkan ekspresi reguler. Misalnya, ^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) permintaan tersebut 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 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 kandidatnya 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 akan "diizinkan" dan ekstensi tidak akan berpengaruh pada permintaan.

Jika lebih dari satu ekstensi ingin memblokir atau mengalihkan permintaan ini, satu tindakan yang akan diambil akan dipilih. Chrome melakukannya dengan mengurutkan aturan dalam urutan block > redirect atau upgradeScheme > allow atau allowAllRequests. Jika dua aturan memiliki jenis yang sama, Chrome akan memilih aturan dari ekstensi yang paling baru diinstal.

Sebelum header permintaan dikirim

Sebelum Chrome mengirim header permintaan ke server, header akan diperbarui berdasarkan aturan modifyHeaders yang cocok.

Dalam satu ekstensi, Chrome membuat daftar modifikasi 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 dalam urutan sedemikian rupa sehingga aturan dari ekstensi yang diinstal lebih baru selalu dievaluasi sebelum aturan dari ekstensi yang lebih lama. Selain itu, aturan dengan prioritas lebih tinggi dari satu ekstensi selalu diterapkan sebelum aturan dengan prioritas lebih rendah dari ekstensi yang sama. Khususnya, bahkan di seluruh ekstensi:

  • Jika aturan menambahkan ke header, aturan dengan prioritas lebih rendah hanya dapat menambahkan ke header tersebut. Operasi setel dan hapus tidak diizinkan.
  • Jika aturan menetapkan header, hanya aturan dengan prioritas lebih rendah dari ekstensi yang sama yang dapat menambahkan ke header tersebut. Tidak ada modifikasi lain yang diizinkan.
  • Jika aturan menghapus header, aturan dengan prioritas 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 berdasarkan action dan priority serta mengecualikan aturan yang dibuat redundan oleh aturan allow atau allowAllRequests yang cocok (hal ini terjadi secara identik dengan langkah-langkah di "Sebelum permintaan"), Chrome dapat memblokir atau mengalihkan permintaan atas nama ekstensi.

Perhatikan bahwa jika permintaan mencapai tahap ini, permintaan tersebut 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 memblokir atau mengalihkan permintaan.

Dalam kasus aturan pemblokiran, hal ini ditangani oleh halaman yang membuat permintaan yang menerima respons yang diblokir dan Chrome menghentikan permintaan lebih awal. Dalam kasus aturan pengalihan, Chrome 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 modifikasi pada header permintaan tidak akan berpengaruh, karena permintaan telah dibuat.

Aturan aman

Aturan aman didefinisikan sebagai aturan dengan tindakan block, allow, allowAllRequests, atau upgradeScheme. Aturan ini tunduk pada peningkatan kuota aturan dinamis.

Batas aturan

Ada overhead performa untuk memuat dan mengevaluasi aturan di browser, sehingga beberapa batasan berlaku saat menggunakan API. Batas bergantung 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 ruleset statis sebagai bagian dari kunci manifes "rule_resources", tetapi hanya 50 ruleset yang dapat diaktifkan sekaligus. Yang terakhir disebut MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Secara keseluruhan, set aturan tersebut dijamin memiliki minimal 30.000 aturan. Ini disebut GUARANTEED_MINIMUM_STATIC_RULES.

Jumlah aturan yang tersedia setelah itu bergantung pada jumlah aturan yang diaktifkan oleh semua ekstensi yang diinstal di browser pengguna. Anda dapat menemukan angka ini saat runtime dengan memanggil getAvailableStaticRuleCount(). Anda dapat melihat contohnya di bagian contoh kode.

Aturan sesi

Ekstensi dapat memiliki hingga 5.000 aturan sesi. Dukungan ini akan melalui 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. Dukungan ini akan melalui MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Mulai Chrome 121, ada batas yang lebih besar,yaitu 30.000 aturan yang tersedia untuk aturan dinamis aman, yang diekspos sebagai MAX_NUMBER_OF_DYNAMIC_RULES. Setiap aturan tidak aman yang ditambahkan dalam batas 5.000 juga akan dihitung dalam batas ini.

Sebelum Chrome 120, ada batas 5.000 aturan dinamis dan sesi gabungan.

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. Nilai ini disebut MAX_NUMBER_OF_REGEX_RULES.

Selain itu, setiap aturan harus berukuran kurang dari 2 KB setelah dikompilasi. Hal ini kira-kira berkorelasi dengan kompleksitas aturan. Jika Anda mencoba memuat aturan yang melebihi batas ini, Anda akan melihat peringatan seperti berikut dan aturan tersebut 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

declarativeNetRequest hanya berlaku untuk permintaan yang mencapai stack jaringan. Hal ini mencakup respons dari cache HTTP, tetapi mungkin tidak mencakup respons yang melewati pengendali onfetch service worker. declarativeNetRequest tidak akan memengaruhi respons yang dihasilkan oleh service worker atau diambil dari CacheStorage, tetapi akan memengaruhi panggilan ke fetch() yang dilakukan di service worker.

Resource yang dapat diakses web

Aturan declarativeNetRequest tidak dapat mengalihkan dari permintaan resource publik ke resource yang tidak dapat diakses web. Tindakan ini akan memicu error. Hal ini berlaku meskipun resource yang dapat diakses web yang ditentukan dimiliki oleh ekstensi pengalihan. Untuk mendeklarasikan resource untuk declarativeNetRequest, gunakan array "web_accessible_resources" manifes.

Modifikasi header

Operasi penambahan hanya didukung untuk header permintaan 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. Daftar yang diizinkan ini peka huruf besar/kecil (bug 449152902).

Saat menambahkan ke header permintaan atau header respons, browser akan menggunakan pemisah yang sesuai jika memungkinkan.

Contoh

Contoh kode

Memperbarui 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 browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await browser.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Memperbarui kumpulan aturan statis

Contoh berikut menunjukkan cara mengaktifkan dan menonaktifkan ruleset dengan mempertimbangkan jumlah ruleset statis yang tersedia dan jumlah maksimum ruleset statis yang diaktifkan. Anda dapat melakukannya jika jumlah aturan statis yang Anda perlukan melebihi jumlah yang diizinkan. Agar dapat berfungsi, beberapa ruleset Anda harus diinstal dengan beberapa ruleset 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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

Contoh aturan

Contoh berikut mengilustrasikan cara Chrome memprioritaskan aturan dalam ekstensi. Saat meninjaunya, Anda mungkin ingin membuka aturan prioritas di jendela terpisah.

Kunci "priority"

Contoh ini memerlukan izin host ke *://*.example.com/*.

Untuk mengetahui prioritas URL tertentu, lihat kunci "priority" (yang ditentukan developer), kunci "action", dan kunci "urlFilter". Contoh ini mengacu pada contoh file aturan yang ditampilkan di bawahnya.

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 yang lebih tinggi daripada tindakan "redirect". Aturan lainnya tidak berlaku karena 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 dalam 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 ke *://*.example.com/*.

Contoh berikut menunjukkan cara mengalihkan permintaan dari example.com ke halaman dalam ekstensi itu sendiri. Jalur ekstensi /a.jpg di-resolve ke chrome-extension://EXTENSION_ID/a.jpg, dengan EXTENSION_ID adalah ID ekstensi Anda. Agar hal ini 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. Aturan 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. Di kunci "regexFilter", perhatikan bagaimana titik di-escape dan grup tangkapan 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 dalam substitusi.

{
  "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 apa pun.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Jenis

DomainType

Hal ini menjelaskan apakah permintaan tersebut merupakan pihak pertama atau ketiga untuk frame tempat permintaan tersebut berasal. Permintaan dikatakan sebagai pihak pertama jika memiliki domain (eTLD+1) yang sama dengan frame tempat permintaan berasal.

Enum

"firstParty"
Permintaan jaringan adalah pihak pertama untuk frame tempat permintaan tersebut berasal.

"thirdParty"
Permintaan jaringan adalah pihak ketiga untuk frame tempat permintaan tersebut berasal.

ExtensionActionOptions

Chrome 88+ browser.* sejak Chrome 148

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+ browser.* sejak Chrome 148

    Detail tentang cara menyesuaikan jumlah tindakan tab.

GetDisabledRuleIdsOptions

Chrome 111+ browser.* sejak Chrome 148

Properti

  • rulesetId

    string

    ID yang sesuai dengan Ruleset statis.

GetRulesFilter

Chrome 111+ browser.* sejak Chrome 148

Properti

  • ruleIds

    number[] opsional

    Jika ditentukan, hanya aturan dengan ID yang cocok yang akan disertakan.

HeaderInfo

Chrome 128+ browser.* sejak Chrome 148

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 kecocokan yang sama dengan values.

  • header

    string

    Nama header. Kondisi ini cocok dengan nama hanya jika values dan excludedValues tidak ditentukan.

  • nilai

    string[] opsional

    Jika ditentukan, kondisi ini akan cocok jika nilai header cocok dengan setidaknya satu pola dalam daftar ini. Hal ini mendukung pencocokan nilai header yang tidak peka huruf besar/kecil serta konstruksi berikut:

    '*' : Mencocokkan sejumlah karakter.

    '?' : Cocok dengan nol atau satu karakter.

    '*' dan '?' dapat di-escape dengan garis miring terbalik, misalnya '\*' dan '\?'

HeaderOperation

Chrome 86+ browser.* sejak Chrome 148

Bagian ini menjelaskan kemungkinan operasi untuk aturan "modifyHeaders".

Enum

"append"
Menambahkan entri baru untuk header yang ditentukan. Saat mengubah header permintaan, operasi ini hanya didukung untuk header tertentu.

"set"
Menetapkan nilai baru untuk header yang ditentukan, sehingga menghapus header yang ada dengan nama yang sama.

"remove"
Menghapus semua entri untuk header yang ditentukan.

IsRegexSupportedResult

Chrome 87+ browser.* sejak Chrome 148

Properti

  • isSupported

    boolean

  • mampu bernalar

    UnsupportedRegexReason opsional

    Menentukan alasan ekspresi reguler tidak didukung. Hanya diberikan jika isSupported bernilai 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, nilai ini akan sama dengan DYNAMIC_RULESET_ID.

MatchedRuleInfo

Properti

  • aturan

    MatchedRule

  • tabId

    angka

    tabId dari tab tempat permintaan berasal jika tab masih aktif. Jika tidak, -1.

  • timeStamp

    angka

    Waktu saat aturan dicocokkan. Stempel waktu akan sesuai dengan konvensi JavaScript untuk waktu, yaitu jumlah milidetik sejak epoch.

MatchedRuleInfoDebug

Properti

MatchedRulesFilter

Properti

  • minTimeStamp

    number opsional

    Jika ditentukan, hanya mencocokkan aturan setelah stempel waktu yang diberikan.

  • tabId

    number opsional

    Jika ditentukan, hanya cocok dengan aturan untuk tab yang diberikan. Mencocokkan aturan yang tidak terkait dengan tab aktif jika ditetapkan ke -1.

ModifyHeaderInfo

Chrome 86+ browser.* sejak Chrome 148

Properti

  • header

    string

    Nama header yang akan diubah.

  • operasi

    HeaderOperation

    Operasi yang akan dilakukan pada header.

  • nilai

    string opsional

    Nilai baru untuk header. Harus ditentukan untuk operasi append dan set.

QueryKeyValue

Properti

  • kunci

    string

  • replaceOnly

    boolean opsional

    Chrome 94+ browser.* sejak Chrome 148

    Jika true, kunci kueri hanya akan diganti jika sudah ada. Jika tidak, kunci juga akan ditambahkan jika tidak ada. 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 relatif terhadap direktori ekstensi. Harus diawali dengan '/'.

  • regexSubstitution

    string opsional

    Pola substitusi untuk aturan yang menentukan regexFilter. Kecocokan pertama regexFilter dalam URL akan diganti dengan pola ini. Dalam regexSubstitution, angka yang di-escape dengan garis miring terbalik (\1 hingga \9) dapat digunakan untuk menyisipkan grup tangkapan yang sesuai. \0 merujuk ke keseluruhan teks yang cocok.

  • dan mengubah teks tersebut

    URLTransform opsional

    Transformasi URL yang akan dilakukan.

  • url

    string opsional

    URL pengalihan. Pengalihan ke URL JavaScript tidak diizinkan.

RegexOptions

Chrome 87+ browser.* sejak Chrome 148

Properti

  • isCaseSensitive

    boolean opsional

    Apakah regex yang ditentukan peka huruf besar/kecil. Defaultnya adalah true (benar).

  • ekspresi reguler

    string

    Ekspresi reguler yang akan diperiksa.

  • requireCapturing

    boolean opsional

    Apakah regex yang ditentukan memerlukan pengambilan. Pengambilan hanya diperlukan untuk aturan pengalihan yang menentukan tindakan regexSubstition. Default-nya adalah salah.

RequestDetails

Properti

  • documentId

    string opsional

    Chrome 106+ browser.* sejak Chrome 148

    ID unik untuk dokumen frame, jika permintaan ini ditujukan untuk frame.

  • documentLifecycle

    DocumentLifecycle opsional

    Chrome 106+ browser.* sejak Chrome 148

    Siklus proses dokumen frame, jika permintaan ini ditujukan untuk frame.

  • frameId

    angka

    Nilai 0 menunjukkan bahwa permintaan terjadi di frame utama; nilai positif menunjukkan ID subframe tempat permintaan terjadi. Jika dokumen (sub-)frame dimuat (type adalah main_frame atau sub_frame), frameId menunjukkan ID frame ini, bukan ID frame luar. ID frame bersifat unik dalam tab.

  • frameType

    FrameType opsional

    Chrome 106+ browser.* sejak Chrome 148

    Jenis frame, jika permintaan ini untuk frame.

  • inisiator

    string opsional

    Origin tempat permintaan dimulai. Hal ini tidak berubah melalui pengalihan. Jika ini adalah origin buram, string 'null' akan digunakan.

  • metode

    string

    Metode HTTP standar.

  • parentDocumentId

    string opsional

    Chrome 106+ browser.* sejak Chrome 148

    ID unik untuk dokumen induk frame, jika permintaan ini ditujukan untuk frame dan memiliki 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.

  • tabId

    angka

    ID tab tempat permintaan dilakukan. Tetapkan ke -1 jika permintaan tidak terkait dengan tab.

  • jenis

    ResourceType

    Jenis resource permintaan.

  • url

    string

    URL permintaan.

RequestMethod

Chrome 91+ browser.* sejak Chrome 148

Ini menjelaskan metode permintaan HTTP dari permintaan jaringan.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Ini menjelaskan jenis resource permintaan jaringan.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Properti

  • tindakan

    RuleAction

    Tindakan yang harus dilakukan jika aturan ini cocok.

  • Kondisi yang memicu aturan ini.

  • id

    angka

    ID yang secara unik mengidentifikasi aturan. Wajib dan harus >= 1.

  • prioritas

    number 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+ browser.* sejak Chrome 148

    Header permintaan yang akan diubah untuk permintaan. Hanya valid jika RuleActionType adalah "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] opsional

    Chrome 86+ browser.* sejak Chrome 148

    Header respons yang akan diubah untuk permintaan. Hanya valid jika RuleActionType adalah "modifyHeaders".

  • Jenis tindakan yang akan dilakukan.

RuleActionType

Menjelaskan jenis tindakan yang harus dilakukan jika RuleCondition tertentu cocok.

Enum

"block"
Memblokir permintaan jaringan.

"redirect"
Mengalihkan permintaan jaringan.

"allow"
Mengizinkan permintaan jaringan. Permintaan tidak akan dicegat jika ada aturan izinkan yang cocok dengannya.

"upgradeScheme"
Mengupgrade skema URL permintaan jaringan ke https jika permintaan tersebut adalah http atau ftp.

"modifyHeaders"
Mengubah 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 adalah pihak pertama atau pihak ketiga untuk domain asalnya. Jika dihilangkan, semua permintaan akan diterima.

  • domains

    string[] opsional

    Tidak digunakan lagi sejak Chrome 101

    Gunakan initiatorDomains sebagai gantinya

    Aturan hanya akan cocok dengan permintaan jaringan yang berasal dari daftar domains.

  • excludedDomains

    string[] opsional

    Tidak digunakan lagi sejak Chrome 101

    Gunakan excludedInitiatorDomains sebagai gantinya

    Aturan ini tidak akan cocok dengan permintaan jaringan yang berasal dari daftar excludedDomains.

  • excludedInitiatorDomains

    string[] opsional

    Chrome 101+ browser.* sejak Chrome 148

    Aturan ini tidak akan cocok dengan permintaan jaringan yang berasal dari daftar excludedInitiatorDomains. Jika daftar kosong atau dihilangkan, tidak ada domain yang dikecualikan. Tindakan ini lebih diprioritaskan daripada initiatorDomains.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Hal ini cocok dengan inisiator permintaan, bukan URL permintaan.
    • Subdomain dari domain yang tercantum juga dikecualikan.
  • excludedRequestDomains

    string[] opsional

    Chrome 101+ browser.* sejak Chrome 148

    Aturan tidak akan cocok dengan permintaan jaringan jika domain cocok dengan salah satu dari daftar excludedRequestDomains. Jika daftar kosong atau dihilangkan, tidak ada domain yang dikecualikan. Tindakan ini lebih diprioritaskan daripada requestDomains.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Subdomain dari domain yang tercantum juga dikecualikan.
  • excludedRequestMethods

    RequestMethod[] opsional

    Chrome 91+ browser.* sejak Chrome 148

    Daftar metode permintaan yang tidak akan cocok dengan aturan. Hanya salah satu dari requestMethods dan excludedRequestMethods yang harus ditentukan. Jika tidak ada yang ditentukan, semua metode permintaan akan dicocokkan.

  • excludedResourceTypes

    ResourceType[] opsional

    Daftar jenis resource yang tidak akan cocok dengan aturan. Hanya salah satu dari resourceTypes dan excludedResourceTypes yang harus ditentukan. Jika keduanya tidak ditentukan, semua jenis resource kecuali "main_frame" akan diblokir.

  • excludedResponseHeaders

    HeaderInfo[] opsional

    Chrome 128+ browser.* sejak Chrome 148

    Aturan tidak cocok jika permintaan cocok dengan kondisi header respons apa pun dalam daftar ini (jika ditentukan). Jika excludedResponseHeaders dan responseHeaders ditentukan, properti excludedResponseHeaders akan diprioritaskan.

  • excludedTabIds

    number[] opsional

    Chrome 92+ browser.* sejak Chrome 148

    Daftar tabs.Tab.id yang tidak boleh cocok dengan aturan. ID tabs.TAB_ID_NONE mengecualikan permintaan yang tidak berasal dari tab. Hanya didukung untuk aturan cakupan sesi.

  • excludedTopDomains

    string[] opsional

    Chrome 145+ browser.* sejak Chrome 148

    Aturan tidak akan cocok dengan permintaan jaringan jika domain frame tingkat teratas yang terkait cocok dengan salah satu domain dari daftar excludedTopDomains. Jika daftar kosong atau dihilangkan, tidak ada domain yang dikecualikan. Tindakan ini lebih diprioritaskan daripada topDomains.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Subdomain dari domain yang tercantum juga dikecualikan.
    • Untuk permintaan tanpa frame tingkat teratas terkait (misalnya, permintaan yang dimulai ServiceWorker), domain inisiator permintaan akan dipertimbangkan.
  • initiatorDomains

    string[] opsional

    Chrome 101+ browser.* sejak Chrome 148

    Aturan hanya akan cocok dengan permintaan jaringan yang berasal dari daftar initiatorDomains. Jika daftar dihilangkan, aturan akan diterapkan ke permintaan dari semua domain. Daftar kosong tidak diizinkan.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Hal ini cocok dengan inisiator permintaan, bukan URL permintaan.
    • Subdomain dari domain yang tercantum juga cocok.
  • isUrlFilterCaseSensitive

    boolean opsional

    Apakah urlFilter atau regexFilter (mana saja yang ditentukan) peka huruf besar/kecil. Defaultnya adalah false.

  • regexFilter

    string opsional

    Ekspresi reguler untuk dicocokkan dengan URL permintaan jaringan. Hal ini mengikuti sintaksis RE2.

    Catatan: Hanya salah satu dari urlFilter atau regexFilter yang dapat ditentukan.

    Catatan: regexFilter hanya boleh terdiri dari karakter ASCII. Ini dicocokkan dengan URL yang host-nya dienkode dalam format punycode (untuk domain internasional) dan karakter non-ASCII lainnya dienkode URL dalam UTF-8.

  • requestDomains

    string[] opsional

    Chrome 101+ browser.* sejak Chrome 148

    Aturan hanya akan mencocokkan permintaan jaringan jika domain cocok dengan salah satu domain dari daftar requestDomains. Jika daftar dihilangkan, aturan akan diterapkan ke permintaan dari semua domain. Daftar kosong tidak diizinkan.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Subdomain dari domain yang tercantum juga cocok.
  • requestMethods

    RequestMethod[] opsional

    Chrome 91+ browser.* sejak Chrome 148

    Daftar metode permintaan HTTP yang dapat dicocokkan dengan aturan. Daftar kosong tidak diizinkan.

    Catatan: Menentukan kondisi aturan requestMethods juga akan mengecualikan permintaan non-HTTP(S), sedangkan menentukan excludedRequestMethods tidak akan mengecualikannya.

  • resourceTypes

    ResourceType[] opsional

    Daftar jenis resource yang dapat dicocokkan dengan aturan. Daftar kosong tidak diizinkan.

    Catatan: ini harus ditentukan untuk aturan allowAllRequests dan hanya boleh menyertakan jenis resource sub_frame dan main_frame.

  • responseHeaders

    HeaderInfo[] opsional

    Chrome 128+ browser.* sejak Chrome 148

    Aturan cocok jika permintaan cocok dengan kondisi header respons apa pun dalam daftar ini (jika ditentukan).

  • tabIds

    number[] opsional

    Chrome 92+ browser.* sejak Chrome 148

    Daftar tabs.Tab.id yang harus cocok dengan aturan. ID tabs.TAB_ID_NONE cocok dengan permintaan yang tidak berasal dari tab. Daftar kosong tidak diizinkan. Hanya didukung untuk aturan cakupan sesi.

  • topDomains

    string[] opsional

    Chrome 145+ browser.* sejak Chrome 148

    Aturan hanya akan cocok dengan permintaan jaringan jika domain frame tingkat teratas yang terkait cocok dengan salah satu domain dari daftar topDomains. Jika daftar dihilangkan, aturan akan diterapkan ke permintaan yang terkait dengan semua domain frame level teratas. Daftar kosong tidak diizinkan.

    Catatan:

    • Subdomain seperti "a.example.com" juga diizinkan.
    • Entri hanya boleh terdiri dari karakter ASCII.
    • Gunakan encoding punycode untuk domain internasional.
    • Subdomain dari domain yang tercantum juga cocok.
    • Untuk permintaan tanpa frame tingkat teratas terkait (misalnya, permintaan yang dimulai ServiceWorker), domain inisiator permintaan akan dipertimbangkan.
  • urlFilter

    string opsional

    Pola yang dicocokkan dengan URL permintaan jaringan. Konstruksi yang didukung:

    '*' : Karakter pengganti: Cocok dengan jumlah karakter berapa pun.

    '|' : Anchor kiri/kanan: Jika digunakan di salah satu ujung pola, menentukan awal/akhir URL.

    '||' : Anchor nama domain: Jika digunakan di awal pola, menentukan awal (sub-)domain URL.

    '^' : Karakter pemisah: Karakter ini cocok dengan apa pun kecuali huruf, angka, atau salah satu dari berikut: _, -, ., atau %. Hal ini juga cocok dengan akhir URL.

    Oleh karena itu, urlFilter terdiri dari bagian-bagian berikut: (anchor nama Domain/Kiri opsional) + pola + (anchor Kanan opsional).

    Jika dihilangkan, semua URL akan dicocokkan. String kosong tidak diizinkan.

    Pola yang diawali dengan ||* tidak diizinkan. Sebagai gantinya, gunakan *.

    Catatan: Hanya salah satu dari urlFilter atau regexFilter yang dapat ditentukan.

    Catatan: urlFilter hanya boleh terdiri dari karakter ASCII. Ini dicocokkan dengan URL yang host-nya dienkode dalam format punycode (untuk domain internasional) dan karakter non-ASCII lainnya dienkode URL dalam UTF-8. Misalnya, jika URL permintaan adalah http://abc.рф?q=ф, urlFilter akan dicocokkan dengan URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+ browser.* sejak Chrome 148

Enum

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Properti

  • aktif

    boolean

    Apakah ruleset diaktifkan secara default.

  • id

    string

    String tidak kosong yang mengidentifikasi set aturan secara unik. ID yang diawali dengan '_' dicadangkan untuk penggunaan internal.

  • jalur

    string

    Jalur ruleset JSON yang relatif terhadap direktori ekstensi.

RulesMatchedDetails

Properti

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Aturan yang cocok dengan filter yang diberikan.

TabActionCountUpdate

Chrome 89+ browser.* sejak Chrome 148

Properti

  • penambahan

    angka

    Jumlah penambahan jumlah tindakan tab. Nilai negatif akan mengurangi jumlah.

  • tabId

    angka

    Tab yang jumlah tindakannya akan diperbarui.

TestMatchOutcomeResult

Chrome 103+ browser.* sejak Chrome 148

Properti

  • matchedRules

    MatchedRule[]

    Aturan (jika ada) yang cocok dengan permintaan hipotetis.

TestMatchRequestDetails

Chrome 103+ browser.* sejak Chrome 148

Properti

  • inisiator

    string opsional

    URL inisiator (jika ada) untuk permintaan hipotetis.

  • metode

    RequestMethod opsional

    Metode HTTP standar dari permintaan hipotetis. Setelan defaultnya adalah "get" untuk permintaan HTTP dan diabaikan untuk permintaan non-HTTP.

  • responseHeaders

    objek opsional

    Chrome 129+ browser.* sejak Chrome 148

    Header yang disediakan oleh respons hipotetis jika permintaan tidak diblokir atau dialihkan sebelum dikirim. Direpresentasikan sebagai objek yang memetakan nama header ke daftar nilai string. Jika tidak ditentukan, respons hipotetis akan menampilkan header respons kosong, yang dapat cocok dengan aturan yang cocok dengan tidak adanya header. Misalnya, {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number opsional

    ID tab tempat permintaan hipotetis terjadi. Tidak perlu sesuai dengan ID tab yang sebenarnya. Defaultnya adalah -1, yang berarti permintaan tidak terkait dengan tab.

  • topUrl

    string opsional

    Chrome 145+ browser.* sejak Chrome 148

    URL frame tingkat teratas terkait (jika ada) untuk permintaan.

  • jenis

    ResourceType

    Jenis resource permintaan hipotetis.

  • url

    string

    URL permintaan hipotetis.

UnsupportedRegexReason

Chrome 87+ browser.* sejak Chrome 148

Menjelaskan alasan ekspresi reguler tertentu tidak didukung.

Enum

"syntaxError"
Ekspresi reguler salah secara sintaksis, atau menggunakan fitur yang tidak tersedia dalam sintaksis RE2.

"memoryLimitExceeded"
Ekspresi reguler melebihi batas memori.

UpdateRuleOptions

Chrome 87+ browser.* sejak Chrome 148

Properti

  • addRules

    Rule[] opsional

    Aturan yang akan ditambahkan.

  • removeRuleIds

    number[] opsional

    ID aturan yang akan dihapus. ID yang tidak valid akan diabaikan.

UpdateRulesetOptions

Chrome 87+ browser.* sejak Chrome 148

Properti

  • disableRulesetIds

    string[] opsional

    Kumpulan ID yang sesuai dengan Ruleset statis yang harus dinonaktifkan.

  • enableRulesetIds

    string[] opsional

    Kumpulan ID yang sesuai dengan Ruleset statis yang harus diaktifkan.

UpdateStaticRulesOptions

Chrome 111+ browser.* sejak Chrome 148

Properti

  • disableRuleIds

    number[] opsional

    Kumpulan ID yang sesuai dengan aturan di Ruleset yang akan dinonaktifkan.

  • enableRuleIds

    number[] opsional

    Kumpulan ID yang sesuai dengan aturan di Ruleset yang akan diaktifkan.

  • rulesetId

    string

    ID yang sesuai dengan Ruleset statis.

URLTransform

Properti

  • fragmen

    string opsional

    Fragmen baru untuk permintaan. Harus kosong, yang berarti 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, yang berarti kueri yang ada akan dihapus; atau harus diawali dengan '?'.

  • queryTransform

    QueryTransform opsional

    Menambahkan, menghapus, atau mengganti key-value pair 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

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Interval waktu yang memungkinkan panggilan MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules dilakukan, ditentukan dalam menit. Panggilan tambahan akan langsung gagal dan menetapkan runtime.lastError. Catatan: Panggilan getMatchedRules yang terkait dengan gestur pengguna dikecualikan dari kuota.

Nilai

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+ browser.* sejak Chrome 148

Jumlah minimum aturan statis yang dijamin untuk ekstensi di seluruh kumpulan aturan statis yang diaktifkan. Aturan apa pun yang melebihi batas ini akan dihitung dalam batas aturan statis global.

Nilai

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Frekuensi 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

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+ browser.* sejak Chrome 148

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 oleh ekstensi. Batas ini dievaluasi secara terpisah untuk kumpulan aturan dinamis dan aturan yang ditentukan dalam file resource aturan.

Nilai

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+ browser.* sejak Chrome 148

Jumlah maksimum aturan cakupan sesi yang dapat ditambahkan oleh ekstensi.

Nilai

5000

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

Chrome 120+ browser.* sejak Chrome 148

Jumlah maksimum aturan dinamis "tidak aman" yang dapat ditambahkan oleh ekstensi.

Nilai

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+ browser.* sejak Chrome 148

Jumlah maksimum aturan cakupan sesi "tidak aman" yang dapat ditambahkan oleh ekstensi.

Nilai

5000

SESSION_RULESET_ID

Chrome 90+ browser.* sejak Chrome 148

ID ruleset untuk aturan cakupan sesi yang ditambahkan oleh ekstensi.

Nilai

"_session"

Metode

getAvailableStaticRuleCount()

Chrome 89+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

Menampilkan jumlah aturan statis yang dapat diaktifkan ekstensi sebelum batas aturan statis global tercapai.

Hasil

  • Promise<number>

    Chrome 91+ browser.* sejak Chrome 148

getDisabledRuleIds()

Chrome 111+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

Menampilkan daftar aturan statis di Ruleset tertentu yang saat ini dinonaktifkan.

Parameter

Hasil

  • Promise<number[]>

    Promise yang di-resolve dengan daftar ID yang sesuai dengan aturan yang dinonaktifkan dalam ruleset tersebut.

getDynamicRules()

browser.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Menampilkan kumpulan aturan dinamis saat ini untuk ekstensi. Pemanggil dapat memfilter daftar aturan yang diambil secara opsional dengan menentukan filter.

Parameter

  • filter

    GetRulesFilter opsional

    Chrome 111+ browser.* sejak Chrome 148

    Objek untuk memfilter daftar aturan yang diambil.

Hasil

  • Promise<Rule[]>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang di-resolve dengan kumpulan aturan dinamis. Promise dapat ditolak jika terjadi error internal sementara.

getEnabledRulesets()

browser.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

Menampilkan ID untuk kumpulan aturan statis yang diaktifkan saat ini.

Hasil

  • Promise<string[]>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang di-resolve dengan daftar ID, yang setiap ID-nya sesuai dengan Ruleset statis yang diaktifkan.

getMatchedRules()

browser.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

Menampilkan semua aturan yang cocok untuk ekstensi. Pemanggil dapat memfilter daftar aturan yang cocok secara opsional dengan menentukan filter. Metode ini hanya tersedia untuk ekstensi dengan izin "declarativeNetRequestFeedback" atau yang memiliki izin "activeTab" yang diberikan untuk tabId yang ditentukan di filter. Catatan: Aturan yang tidak terkait dengan dokumen aktif yang cocok lebih dari lima menit yang lalu tidak akan ditampilkan.

Parameter

Hasil

  • Chrome 91+ browser.* sejak Chrome 148

    Promise yang di-resolve setelah daftar aturan yang cocok diambil. Jika terjadi error, Promise akan ditolak. Hal ini dapat terjadi karena beberapa alasan, seperti izin yang tidak memadai, atau melebihi kuota.

getSessionRules()

Chrome 90+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Menampilkan kumpulan aturan cakupan sesi saat ini untuk ekstensi. Pemanggil dapat memfilter daftar aturan yang diambil secara opsional dengan menentukan filter.

Parameter

  • filter

    GetRulesFilter opsional

    Chrome 111+ browser.* sejak Chrome 148

    Objek untuk memfilter daftar aturan yang diambil.

Hasil

  • Promise<Rule[]>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang di-resolve dengan kumpulan aturan cakupan sesi.

isRegexSupported()

Chrome 87+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

Memeriksa apakah ekspresi reguler yang diberikan akan didukung sebagai kondisi aturan regexFilter.

Parameter

  • regexOptions

    RegexOptions

    Ekspresi reguler yang akan diperiksa.

Hasil

  • Chrome 91+ browser.* sejak Chrome 148

    Promise yang di-resolve dengan detail yang terdiri dari apakah ekspresi reguler didukung dan alasannya jika tidak.

setExtensionActionOptions()

Chrome 88+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

Mengonfigurasi apakah jumlah tindakan untuk tab harus ditampilkan sebagai teks badge tindakan ekstensi dan menyediakan cara untuk menambah jumlah tindakan tersebut.

Parameter

Hasil

  • Promise<void>

    Chrome 91+ browser.* sejak Chrome 148

testMatchOutcome()

Chrome 103+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Memeriksa apakah ada aturan declarativeNetRequest ekstensi yang cocok dengan permintaan hipotetis. Catatan: Hanya tersedia untuk ekstensi yang tidak dipaketkan karena ini hanya dimaksudkan untuk digunakan selama pengembangan ekstensi.

Parameter

Hasil

updateDynamicRules()

browser.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

Mengubah kumpulan aturan dinamis saat ini untuk ekstensi. Aturan dengan ID yang tercantum di options.removeRuleIds akan dihapus terlebih dahulu, lalu aturan yang diberikan di options.addRules akan ditambahkan. Catatan:

  • Pembaruan ini terjadi sebagai satu operasi atomik: semua aturan yang ditentukan ditambahkan dan dihapus, atau error ditampilkan.
  • Aturan ini dipertahankan di seluruh sesi browser dan di 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 tidak aman tidak boleh melebihi MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parameter

Hasil

  • Promise<void>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang diselesaikan setelah update selesai. Jika terjadi error, promise akan ditolak dan tidak ada perubahan yang akan dilakukan pada set aturan. Hal ini dapat terjadi karena beberapa alasan, seperti format aturan yang tidak valid, ID aturan duplikat, batas jumlah aturan terlampaui, error internal, dan lainnya.

updateEnabledRulesets()

browser.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Memperbarui kumpulan aturan statis yang diaktifkan untuk ekstensi. Ruleset dengan ID yang tercantum di options.disableRulesetIds akan dihapus terlebih dahulu, lalu ruleset yang tercantum di options.enableRulesetIds akan ditambahkan. Perhatikan bahwa 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

Hasil

  • Promise<void>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang diselesaikan setelah update selesai. Jika terjadi error, promise akan ditolak dan tidak ada perubahan yang akan dilakukan pada kumpulan ruleset yang diaktifkan. Hal ini dapat terjadi karena beberapa alasan, seperti ID ruleset yang tidak valid, batas jumlah aturan terlampaui, atau error internal.

updateSessionRules()

Chrome 90+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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 di options.addRules akan ditambahkan. Catatan:

  • Pembaruan ini terjadi sebagai satu operasi atomik: semua aturan yang ditentukan ditambahkan dan dihapus, atau error ditampilkan.
  • Aturan ini tidak dipertahankan di seluruh sesi dan didukung dalam memori.
  • MAX_NUMBER_OF_SESSION_RULES adalah jumlah maksimum aturan sesi yang dapat ditambahkan ekstensi.

Parameter

Hasil

  • Promise<void>

    Chrome 91+ browser.* sejak Chrome 148

    Promise yang diselesaikan setelah update selesai. Jika terjadi error, promise akan ditolak dan tidak ada perubahan yang akan dilakukan pada set aturan. Hal ini dapat terjadi karena beberapa alasan, seperti format aturan yang tidak valid, ID aturan duplikat, batas jumlah aturan terlampaui, dan lainnya.

updateStaticRules()

Chrome 111+ browser.* sejak Chrome 148 
browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

Menonaktifkan dan mengaktifkan aturan statis individual di Ruleset. Perubahan pada aturan yang termasuk dalam Ruleset yang dinonaktifkan akan diterapkan saat aturan tersebut diaktifkan kembali.

Parameter

Hasil

  • Promise<void>

    Promise yang di-resolve saat update selesai. Jika terjadi error, promise akan ditolak dan tidak ada perubahan yang akan dilakukan pada aturan statis yang diaktifkan.

Acara

onRuleMatchedDebug

browser.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Diaktifkan saat aturan cocok dengan permintaan. Hanya tersedia untuk ekstensi yang tidak dipaketkan dengan izin "declarativeNetRequestFeedback" karena ini dimaksudkan untuk digunakan hanya untuk tujuan proses debug.

Parameter