chrome.declarativeWebRequest

Deskripsi

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

Izin

declarativeWebRequest

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

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

Ketersediaan

Saluran beta ≤ MV2

Manifes

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

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Tindakan SendMessageToExtension() memerlukan izin host untuk setiap host yang permintaan jaringannya yang Anda inginkan 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 dapat menyiapkan aturan untuk:

  • Batalkan permintaan ke https://www.google.com atau https://anything.else.com.
  • Kirim pesan saat menavigasi ke 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 mendaftar ke objek peristiwa chrome.declarativeWebRequest.onRequest.

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

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 API Permintaan. Artinya, kondisi hanya dapat diuji pada tahap permintaan web tertentu dan, demikian juga, tindakan juga hanya dapat dieksekusi pada tahap tertentu. Tabel berikut mencantumkan yang kompatibel dengan kondisi dan tindakan.

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

Menggunakan prioritas untuk mengganti aturan

Aturan dapat dikaitkan dengan prioritas seperti yang dijelaskan dalam Events API. Mekanisme ini dapat berupa yang digunakan untuk mengekspresikan pengecualian. Contoh berikut memblokir semua permintaan ke gambar yang bernama evil.jpg kecuali di 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 permintaan tahap. Semua kondisi semua aturan akan dievaluasi pada setiap tahap permintaan web. Jika Tindakan IgnoreRules dijalankan, dan hanya berlaku untuk tindakan lain yang dieksekusi untuk permintaan web dalam tahap yang sama.

Jenis

AddRequestCookie

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

Properti

AddResponseCookie

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

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 secara komputasi lebih murah.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti ini: 

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

  • filter

    RequestCookie

    Filter cookie yang akan diubah. Semua entri kosong akan diabaikan.

  • modifikasi

    RequestCookie

    Atribut yang harus diganti dalam cookie yang menggunakan filter. Atribut yang ditetapkan ke string kosong akan dihapus.

EditResponseCookie

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

Properti

FilterResponseCookie

Filter cookie di Respons HTTP.

Properti

  • ageLowerBound

    angka opsional

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

  • ageUpperBound

    angka 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 [now, now + ageUpperBound] yang memenuhi kriteria ini. Cookie sesi dan cookie sesi dengan waktu tanggal habis masa berlaku yang sudah berlalu tidak memenuhi kriteria filter ini. Masa aktif cookie dihitung dari 'max-age' atau 'berakhir' atribut cookie. Jika keduanya ditentukan, 'max-age' digunakan untuk menghitung masa berlaku cookie.

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • expires

    string opsional

    Nilai atribut cookie Berakhir.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    angka opsional

    Nilai atribut cookie Usia Maks

  • nama

    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 aktif yang ditentukan dalam 'max-age' atau 'berakhir' .

  • nilai

    string opsional

    Nilai cookie, dapat diisi dengan tanda petik ganda.

HeaderFilter

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

Properti

  • nameContains

    string | string[] opsional

    Cocok jika nama header berisi semua string yang ditentukan.

  • nameEquals

    string opsional

    Cocok jika nama header sama dengan string yang ditentukan.

  • namePrefix

    string opsional

    Cocok jika nama header diawali dengan string yang ditentukan.

  • nameSuffix

    string opsional

    Cocok jika nama header diakhiri dengan string yang ditentukan.

  • valueContains

    string | string[] opsional

    Cocok jika nilai header berisi semua string yang ditentukan.

  • valueEquals

    string opsional

    Mencocokkan jika nilai header sama dengan string yang ditentukan.

  • valuePrefix

    string opsional

    Cocok jika nilai header dimulai 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 akan terlihat seperti ini: 

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

  • hasTag

    string opsional

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

  • lowerPriorityThan

    angka opsional

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

RedirectByRegEx

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

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti ini: 

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

  • dari

    string

    Pola pencocokan yang mungkin berisi grup tangkapan. Capture group dirujuk dalam sintaks Perl ($1, $2, ...) bukan sintaks RE2 (\1, \2, ...) agar 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 secara komputasi lebih murah.

Properti

RemoveRequestHeader

Menghapus header permintaan dengan 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 secara komputasi lebih murah.

Properti

RemoveResponseHeader

Menghapus semua header respons dari nama dan nilai yang ditentukan.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti ini: 

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

  • nama

    string

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

  • nilai

    string opsional

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

RequestCookie

Filter atau spesifikasi cookie di Permintaan HTTP.

Properti

  • nama

    string opsional

    Nama cookie.

  • nilai

    string opsional

    Nilai cookie, dapat diisi dengan tanda petik ganda.

RequestMatcher

Mencocokkan peristiwa jaringan berdasarkan berbagai kriteria.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti ini: 

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

  • contentType

    string[] opsional

    Mencocokkan jika jenis media MIME respons (dari header Content-Type HTTP) terdapat dalam daftar.

  • excludeContentType

    string[] opsional

    Cocok jika jenis media MIME respons (dari header Content-Type HTTP) tidak terdapat dalam daftar.

  • excludeRequestHeaders

    HeaderFilter[] opsional

    Cocok jika tidak ada header permintaan yang cocok oleh HeaderFilters mana pun.

  • excludeResponseHeaders

    HeaderFilter[] opsional

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

  • firstPartyForCookiesUrl

    UrlFilter opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 82.

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

  • requestHeaders

    HeaderFilter[] opsional

    Cocok jika beberapa header permintaan cocok dengan salah satu HeaderFilters.

  • resourceType

    ResourceType[] opsional

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

  • responseHeaders

    HeaderFilter[] opsional

    Cocok jika beberapa header respons cocok dengan salah satu HeaderFilters.

  • tahap

    Stage[] opsional

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

  • thirdPartyForCookies

    boolean opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 87.

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

  • url

    UrlFilter opsional

    Cocok jika kondisi UrlFilter terpenuhi untuk URL permintaan.

ResponseCookie

Spesifikasi cookie di Respons HTTP.

Properti

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • expires

    string opsional

    Nilai atribut cookie Berakhir.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    angka opsional

    Nilai atribut cookie Usia Maks

  • nama

    string opsional

    Nama cookie.

  • jalur

    string opsional

    Nilai atribut cookie Jalur.

  • aman

    string opsional

    Keberadaan atribut cookie Aman.

  • nilai

    string opsional

    Nilai cookie, dapat diisi dengan tanda petik ganda.

SendMessageToExtension

Memicu peristiwa declarativeWebRequest.onMessage.

Properti

SetRequestHeader

Menetapkan header permintaan nama yang ditentukan ke nilai yang ditentukan. Jika sebelumnya tidak ada header dengan nama yang ditentukan, 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"

"onHeaderReceived"

"onAuthRequired"

Acara

onMessage

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

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

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (details: object) => void

    • detail

      objek

      • documentId

        string opsional

        UUID dokumen yang membuat permintaan.

      • Siklus proses dokumen berada.

      • 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 adalah main_frame atau sub_frame), frameId menunjukkan ID frame ini, bukan ID frame luar. ID frame bersifat unik dalam satu 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. ID ini tidak disetel jika tidak ada 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. Akibatnya, keduanya dapat digunakan untuk mengaitkan berbagai peristiwa dari permintaan yang sama.

      • tahap

        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