chrome.declarativeWebRequest

Deskripsi

Catatan: API ini tidak digunakan lagi. Sebagai gantinya, lihat declarativeNetRequest API. Gunakan chrome.declarativeWebRequest API untuk menangkap, memblokir, atau mengubah permintaan yang sedang berlangsung. Ini jauh lebih cepat daripada chrome.webRequest API karena Anda dapat mendaftarkan aturan yang dievaluasi dalam browser bukan mesin JavaScript, yang mengurangi latensi bolak-balik dan memungkinkan efisiensi yang lebih tinggi.

Izin

declarativeWebRequest

Anda harus mendeklarasikan izin "deklaratifWebRequest" dalam manifes ekstensi untuk menggunakan API ini, beserta izin host.

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

Ketersediaan

Saluran beta ≤ MV2

Manifes

Perhatikan bahwa jenis tindakan non-sensitif tertentu tidak memerlukan izin host:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Tindakan SendMessageToExtension() memerlukan izin host untuk setiap host yang permintaan jaringannya ingin Anda picu untuk memicu pesan.

Semua tindakan lainnya memerlukan izin host untuk semua URL.

Misalnya, jika "https://*.google.com/*" adalah satu-satunya izin host yang dimiliki ekstensi, ekstensi tersebut dapat menyiapkan aturan untuk:

  • Membatalkan permintaan ke https://www.google.com atau https://anything.else.com.
  • Kirim pesan saat membuka https://www.google.com, tetapi tidak ke https://something.else.com.

Ekstensi tidak dapat menyiapkan aturan untuk mengalihkan https://www.google.com ke https://mail.google.com.

Aturan

Declarative Web Request API mengikuti konsep Declarative API. Anda dapat mendaftarkan aturan ke objek peristiwa chrome.declarativeWebRequest.onRequest.

Declarative Web Request API mendukung satu jenis kriteria pencocokan, yaitu RequestMatcher. RequestMatcher cocok dengan permintaan jaringan jika dan hanya jika semua kriteria yang tercantum terpenuhi. RequestMatcher berikut akan cocok dengan permintaan jaringan saat pengguna memasukkan https://www.example.com di ominibox:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

Permintaan ke https://www.example.com akan ditolak oleh RequestMatcher karena skema tersebut. Selain itu, semua permintaan untuk iframe tersemat akan ditolak karena resourceType.

Untuk membatalkan semua permintaan ke "example.com", Anda dapat menentukan aturan sebagai berikut:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Untuk membatalkan semua permintaan ke example.com dan foobar.com, Anda dapat menambahkan kondisi kedua, karena setiap kondisi cukup untuk memicu semua tindakan yang ditentukan:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Daftarkan aturan sebagai berikut:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Evaluasi kondisi dan tindakan

Declarative Web Request API mengikuti Model siklus proses untuk permintaan web dari Web Request API. Artinya, kondisi hanya dapat diuji pada tahap tertentu dari permintaan web, dan juga, tindakan hanya dapat dijalankan pada tahap tertentu. Tabel berikut mencantumkan tahap permintaan yang kompatibel dengan kondisi dan tindakan.

Tahap permintaan saat atribut kondisi dapat diproses.
Atribut kondisi onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Tahap permintaan saat tindakan dapat dijalankan.
Event onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Menggunakan prioritas untuk mengganti aturan

Aturan dapat dikaitkan dengan prioritas seperti yang dijelaskan di Events API. Mekanisme ini dapat digunakan untuk menyatakan pengecualian. Contoh berikut memblokir semua permintaan ke gambar bernama evil.jpg kecuali pada server "myserver.com".

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Perlu diketahui bahwa tindakan IgnoreRules tidak dipertahankan di seluruh tahap permintaan. Semua kondisi dari semua aturan akan dievaluasi pada setiap tahap permintaan web. Jika dijalankan, tindakan IgnoreRules hanya berlaku untuk tindakan lain yang dijalankan untuk permintaan web yang sama di tahap yang sama.

Jenis

AddRequestCookie

Menambahkan cookie ke permintaan atau mengganti cookie, jika ada cookie lain dengan nama yang sama sudah ada. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

AddResponseCookie

Menambahkan cookie ke respons atau mengganti cookie, jika ada cookie lain dengan nama yang sama sudah ada. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

AddResponseHeader

Menambahkan header respons ke respons permintaan web ini. Karena beberapa header respons mungkin memiliki nama yang sama, Anda harus menghapus terlebih dahulu, lalu menambahkan header respons baru untuk menggantikannya.

Properti

CancelRequest

Tindakan peristiwa deklaratif yang membatalkan permintaan jaringan.

Properti

EditRequestCookie

Mengedit satu atau beberapa cookie permintaan. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

EditResponseCookie

Mengedit satu atau beberapa cookie respons. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

FilterResponseCookie

Filter cookie di Respons HTTP.

Properti

  • ageLowerBound

    nomor opsional

    Batas bawah inklusif pada masa aktif cookie (ditentukan dalam detik setelah waktu saat ini). Hanya cookie dengan waktu tanggal habis masa berlaku yang ditetapkan ke 'now + ageLowerBound' atau nanti yang akan memenuhi kriteria ini. Cookie sesi tidak memenuhi kriteria filter ini. Masa berlaku cookie dihitung dari atribut cookie 'max-age' atau 'expires'. Jika keduanya ditentukan, 'max-age' digunakan untuk menghitung masa aktif cookie.

  • ageUpperBound

    nomor opsional

    Batas atas inklusif selama masa aktif cookie (ditentukan dalam detik setelah waktu saat ini). Hanya cookie dengan tanggal habis masa berlaku yang berada dalam interval [sekarang, sekarang + ageUpperBound] yang memenuhi kriteria ini. Cookie sesi dan cookie yang tanggal habis masa berlakunya adalah di masa lalu tidak memenuhi kriteria filter ini. Masa berlaku cookie dihitung dari atribut cookie 'max-age' atau 'expires'. Jika keduanya ditentukan, 'max-age' digunakan untuk menghitung masa aktif cookie.

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • tanggal akhir

    string opsional

    Nilai atribut Cookie kedaluwarsa.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    nomor opsional

    Nilai atribut cookie Usia Maksimal

  • name

    string opsional

    Nama cookie.

  • jalur

    string opsional

    Nilai atribut cookie Jalur.

  • aman

    string opsional

    Keberadaan atribut cookie Aman.

  • sessionCookie

    boolean opsional

    Memfilter cookie sesi. Cookie sesi tidak memiliki masa berlaku yang ditentukan dalam atribut 'max-age' atau 'expires' mana pun.

  • value

    string opsional

    Nilai cookie, dapat diberi padding dalam tanda kutip.

HeaderFilter

Memfilter header permintaan untuk berbagai kriteria. Beberapa kriteria dievaluasi sebagai konjungsi.

Properti

  • nameContains

    string|string[] optional

    Cocok jika nama header berisi semua string yang ditentukan.

  • nameEquals

    string opsional

    Cocok jika nama header sama dengan string yang ditentukan.

  • namePrefix

    string opsional

    Cocok jika nama header dimulai dengan string yang ditentukan.

  • nameSuffix

    string opsional

    Cocok jika nama header diakhiri dengan string yang ditentukan.

  • valueContains

    string|string[] optional

    Mencocokkan jika nilai header berisi semua string yang ditentukan.

  • valueEquals

    string opsional

    Cocok jika nilai header sama dengan string yang ditentukan.

  • valuePrefix

    string opsional

    Cocok jika nilai header diawali dengan string yang ditentukan.

  • valueSuffix

    string opsional

    Cocok jika nilai header diakhiri dengan string yang ditentukan.

IgnoreRules

Menyamarkan semua aturan yang cocok dengan kriteria yang ditentukan.

Properti

  • konstruktor

    void

    Fungsi constructor terlihat seperti: 

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

  • hasTag

    string opsional

    Jika ditetapkan, aturan dengan tag yang ditentukan akan diabaikan. Pengabaikan ini tidak akan dipertahankan. Hal ini hanya memengaruhi aturan dan tindakannya pada tahapan permintaan jaringan yang sama. Perhatikan bahwa aturan dijalankan dalam urutan menurun dari prioritasnya. Tindakan ini memengaruhi aturan dengan prioritas yang lebih rendah daripada aturan saat ini. Aturan dengan prioritas yang sama dapat atau tidak dapat diabaikan.

  • lowerPriorityThan

    nomor opsional

    Jika ditetapkan, aturan dengan prioritas yang lebih rendah dari nilai yang ditentukan akan diabaikan. Batas ini tidak dipertahankan. Batas ini hanya memengaruhi aturan dan tindakannya pada tahap permintaan jaringan yang sama.

RedirectByRegEx

Mengalihkan permintaan dengan menerapkan ekspresi reguler pada URL. Ekspresi reguler menggunakan sintaksis RE2.

Properti

  • konstruktor

    void

    Fungsi constructor terlihat seperti: 

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

  • dari

    string

    Pola pencocokan yang mungkin berisi grup tangkapan. Grup tangkapan dirujuk dalam sintaks Perl ($1, $2, ...) bukan sintaks RE2 (\1, \2, ...) untuk lebih dekat dengan Ekspresi Reguler JavaScript.

  • hingga

    string

    Pola tujuan.

RedirectRequest

Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan.

Properti

RedirectToEmptyDocument

Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan ke dokumen kosong.

Properti

RedirectToTransparentImage

Tindakan peristiwa deklaratif yang mengalihkan permintaan jaringan ke gambar transparan.

Properti

RemoveRequestCookie

Menghapus satu atau beberapa cookie permintaan. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

RemoveRequestHeader

Menghapus header permintaan nama yang ditentukan. Jangan gunakan SetRequestHeader dan RemoveRequestHeader dengan nama header yang sama pada permintaan yang sama. Setiap nama header permintaan hanya muncul sekali dalam setiap permintaan.

Properti

RemoveResponseCookie

Menghapus satu atau beberapa cookie respons. Perhatikan bahwa lebih baik menggunakan Cookies API karena lebih murah secara komputasi.

Properti

RemoveResponseHeader

Menghapus semua header respons dari nama dan nilai yang ditentukan.

Properti

  • konstruktor

    void

    Fungsi constructor terlihat seperti: 

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

  • name

    string

    Nama header permintaan HTTP (tidak peka huruf besar/kecil).

  • value

    string opsional

    Nilai header permintaan HTTP (tidak peka huruf besar/kecil).

RequestCookie

Filter atau spesifikasi cookie di Permintaan HTTP.

Properti

  • name

    string opsional

    Nama cookie.

  • value

    string opsional

    Nilai cookie, dapat diberi padding dalam tanda kutip.

RequestMatcher

Mencocokkan peristiwa jaringan menurut berbagai kriteria.

Properti

  • konstruktor

    void

    Fungsi constructor terlihat seperti: 

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

  • contentType

    string[] opsional

    Mencocokkan jika jenis media MIME respons (dari header Jenis Konten HTTP) terdapat dalam daftar.

  • excludeContentType

    string[] opsional

    Mencocokkan jika jenis media MIME respons (dari header Jenis Konten HTTP) tidak terdapat dalam daftar.

  • excludeRequestHeaders

    HeaderFilter[] opsional

    Mencocokkan jika tidak ada header permintaan yang cocok dengan HeaderFilters mana pun.

  • excludeResponseHeaders

    HeaderFilter[] opsional

    Mencocokkan jika tidak ada header respons yang cocok dengan HeaderFilters mana pun.

  • firstPartyForCookiesUrl

    UrlFilter opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 82.

    Mencocokkan jika kondisi UrlFilter terpenuhi untuk URL 'pihak pertama' permintaan. URL 'pihak pertama' permintaan, jika ada, dapat berbeda dengan URL target permintaan, dan menjelaskan apa yang dianggap sebagai 'pihak pertama' demi pemeriksaan cookie pihak ketiga.

  • requestHeaders

    HeaderFilter[] opsional

    Mencocokkan jika beberapa header permintaan cocok dengan salah satu HeaderFilters.

  • resourceType

    ResourceType[] opsional

    Cocok jika jenis permintaan permintaan ada dalam daftar. Permintaan yang tidak dapat cocok dengan jenis apa pun akan difilter.

  • responseHeaders

    HeaderFilter[] opsional

    Mencocokkan jika beberapa header respons cocok dengan salah satu HeaderFilters.

  • tahap

    Stage[] opsional

    Berisi daftar string yang menjelaskan stage. Nilai yang diizinkan adalah 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. Jika atribut ini ada, maka akan membatasi stage yang berlaku untuk stage yang tercantum di bawah. Perhatikan bahwa keseluruhan kondisi hanya berlaku dalam tahapan yang kompatibel dengan semua atribut.

  • thirdPartyForCookies

    boolean opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 87.

    Jika ditetapkan ke true, mencocokkan permintaan yang tunduk pada kebijakan cookie pihak ketiga. Jika disetel ke salah (false), cocok dengan semua permintaan lainnya.

  • url

    UrlFilter opsional

    Mencocokkan jika kondisi UrlFilter terpenuhi untuk URL permintaan.

ResponseCookie

Spesifikasi cookie di Respons HTTP.

Properti

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • tanggal akhir

    string opsional

    Nilai atribut Cookie kedaluwarsa.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    nomor opsional

    Nilai atribut cookie Usia Maksimal

  • name

    string opsional

    Nama cookie.

  • jalur

    string opsional

    Nilai atribut cookie Jalur.

  • aman

    string opsional

    Keberadaan atribut cookie Aman.

  • value

    string opsional

    Nilai cookie, dapat diberi padding dalam tanda kutip.

SendMessageToExtension

Memicu peristiwa declarativeWebRequest.onMessage.

Properti

SetRequestHeader

Menetapkan header permintaan dari nama yang ditentukan ke nilai yang ditentukan. Jika header dengan nama yang ditentukan sebelumnya tidak ada, header baru akan dibuat. Perbandingan nama header selalu tidak peka huruf besar/kecil. Setiap nama header permintaan hanya muncul sekali dalam setiap permintaan.

Properti

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onAuthRequired"

Peristiwa

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim melalui declarativeWebRequest.SendMessageToExtension dari tindakan API permintaan web deklaratif.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (details: object)=>void

    • detail

      objek

      • documentId

        string opsional

        UUID dokumen yang membuat permintaan.

      • Siklus proses tempat dokumen berada.

      • frameId

        angka

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

      • Jenis frame tempat navigasi terjadi.

      • pesan

        string

        Pesan yang dikirim oleh skrip panggilan.

      • method

        string

        Metode HTTP standar.

      • parentDocumentId

        string opsional

        UUID dokumen induk yang memiliki frame ini. Ini tidak disetel jika tidak ada induk.

      • parentFrameId

        angka

        ID frame yang menggabungkan frame yang mengirim permintaan. Tetapkan ke -1 jika tidak ada frame induk.

      • requestId

        string

        ID permintaan. ID permintaan bersifat unik dalam sesi browser. Akibatnya, peristiwa tersebut dapat digunakan untuk mengaitkan berbagai peristiwa dari permintaan yang sama.

      • stage

        Tahap

        Tahap permintaan jaringan saat peristiwa dipicu.

      • tabId

        angka

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

      • timeStamp

        angka

        Waktu saat sinyal ini dipicu, dalam milidetik sejak epoch.

      • Cara penggunaan resource yang diminta.

      • url

        string

onRequest

Menyediakan Declarative Event API yang terdiri dari addRules, removeRules, dan getRules.

Kondisi

RequestMatcher

Tindakan

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules