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. API ini jauh lebih cepat daripada chrome.webRequest API karena Anda dapat mendaftarkan aturan yang dievaluasi di browser, bukan di mesin JavaScript, sehingga mengurangi latensi roundtrip dan memungkinkan efisiensi yang lebih tinggi.

Izin

declarativeWebRequest

Anda harus menyatakan izin "declarativeWebRequest" dalam manifes ekstensi untuk menggunakan API ini, beserta izin host.

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

Ketersediaan

Channel beta ≤ MV2

Manifes

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

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Tindakan SendMessageToExtension() memerlukan izin host untuk host mana pun yang permintaan jaringannya ingin Anda picu untuk menampilkan pesan.

Semua tindakan lainnya memerlukan izin host ke semua URL.

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

  • Membatalkan permintaan untuk https://www.google.com atau https://anything.else.com.
  • Mengirim 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 mendaftarkan aturan ke objek peristiwa chrome.declarativeWebRequest.onRequest.

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

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. Selain itu, semua permintaan untuk iframe sematan 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 sudah 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 permintaan web dan, demikian pula, tindakan hanya dapat dieksekusi pada tahap tertentu. Tabel berikut mencantumkan tahapan permintaan yang kompatibel dengan kondisi dan tindakan.

Tahap permintaan selama atribut kondisi dapat diproses.
Atribut kondisi onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Tahap permintaan selama tindakan dapat dieksekusi.
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 digunakan untuk menyatakan pengecualian. Contoh berikut memblokir semua permintaan ke gambar 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]);

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

Jenis

AddRequestCookie

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

Properti

AddResponseCookie

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

Properti

AddResponseHeader

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

Properti

CancelRequest

Tindakan peristiwa deklaratif yang membatalkan permintaan jaringan.

Properti

EditRequestCookie

Mengedit satu atau beberapa cookie permintaan. Perhatikan bahwa sebaiknya gunakan Cookies API karena API ini lebih murah secara komputasi.

Properti

EditResponseCookie

Mengedit satu atau beberapa cookie respons. Perhatikan bahwa sebaiknya gunakan Cookies API karena API ini lebih murah secara komputasi.

Properti

FilterResponseCookie

Filter cookie dalam Respons HTTP.

Properti

  • ageLowerBound

    nomor opsional

    Batas bawah inklusif pada masa aktif cookie (ditentukan dalam detik setelah waktu saat ini). Hanya cookie yang tanggal dan waktu habis masa berlakunya ditetapkan ke 'now + ageLowerBound' atau yang lebih baru yang 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' akan digunakan untuk menghitung masa aktif cookie.

  • ageUpperBound

    nomor opsional

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

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • expires

    string opsional

    Nilai atribut cookie Expires.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    nomor opsional

    Nilai atribut cookie Max-Age

  • nama

    string opsional

    Nama cookie.

  • jalur

    string opsional

    Nilai atribut cookie Path.

  • aman

    string opsional

    Keberadaan atribut cookie Secure.

  • sessionCookie

    boolean opsional

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

  • nilai

    string opsional

    Nilai cookie, dapat diapit dalam tanda kutip ganda.

HeaderFilter

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

Properti

  • nameContains

    string | string[] opsional

    Cocok jika nama header berisi semua string yang ditentukan.

  • nameEquals

    string opsional

    Cocok jika nama header sama dengan string yang ditentukan.

  • namePrefix

    string opsional

    Cocok jika nama header dimulai dengan string yang ditentukan.

  • nameSuffix

    string opsional

    Cocok jika nama header diakhiri dengan string yang ditentukan.

  • valueContains

    string | string[] opsional

    Cocok 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

Menutupi semua aturan yang cocok dengan kriteria yang ditentukan.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

    (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 prioritasnya secara menurun. 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 disetel, aturan dengan prioritas yang lebih rendah daripada nilai yang ditentukan akan diabaikan. Batas ini tidak dipertahankan, hanya memengaruhi aturan dan tindakannya pada tahap permintaan jaringan yang sama.

RedirectByRegEx

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

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

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

  • dari

    string

    Pola kecocokan yang dapat berisi grup tangkapan. Grup pengambilan dirujuk dalam sintaksis Perl ($1, $2, ...) dan bukan sintaksis 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 sebaiknya gunakan Cookies API karena API ini lebih murah secara komputasi.

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 satu kali dalam setiap permintaan.

Properti

RemoveResponseCookie

Menghapus satu atau beberapa cookie respons. Perhatikan bahwa sebaiknya gunakan Cookies API karena API ini lebih murah secara komputasi.

Properti

RemoveResponseHeader

Menghapus semua header respons dengan nama dan nilai yang ditentukan.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

    (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 dalam Permintaan HTTP.

Properti

  • nama

    string opsional

    Nama cookie.

  • nilai

    string opsional

    Nilai cookie, dapat diapit dalam tanda kutip ganda.

RequestMatcher

Mencocokkan peristiwa jaringan berdasarkan berbagai kriteria.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

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

  • contentType

    string[] opsional

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

  • excludeContentType

    string[] opsional

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

  • excludeRequestHeaders

    HeaderFilter[] opsional

    Cocok jika tidak ada header permintaan yang cocok dengan HeaderFilter mana pun.

  • excludeResponseHeaders

    HeaderFilter[] opsional

    Cocok jika tidak ada header respons yang cocok dengan HeaderFilter mana pun.

  • firstPartyForCookiesUrl

    UrlFilter opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 82.

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

  • requestHeaders

    HeaderFilter[] opsional

    Cocok jika beberapa header permintaan cocok dengan salah satu HeaderFilter.

  • resourceType

    ResourceType[] opsional

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

  • responseHeaders

    HeaderFilter[] opsional

    Cocok jika beberapa header respons cocok dengan salah satu HeaderFilter.

  • tahap

    Stage[] opsional

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

  • thirdPartyForCookies

    boolean opsional

    Tidak digunakan lagi

    Diabaikan sejak rilis 87.

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

  • url

    UrlFilter opsional

    Cocok jika kondisi UrlFilter terpenuhi untuk URL permintaan.

ResponseCookie

Spesifikasi cookie dalam Respons HTTP.

Properti

  • domain

    string opsional

    Nilai atribut cookie Domain.

  • expires

    string opsional

    Nilai atribut cookie Expires.

  • httpOnly

    string opsional

    Keberadaan atribut cookie HttpOnly.

  • maxAge

    nomor opsional

    Nilai atribut cookie Max-Age

  • nama

    string opsional

    Nama cookie.

  • jalur

    string opsional

    Nilai atribut cookie Path.

  • aman

    string opsional

    Keberadaan atribut cookie Secure.

  • nilai

    string opsional

    Nilai cookie, dapat diapit dalam tanda kutip ganda.

SendMessageToExtension

Memicu peristiwa declarativeWebRequest.onMessage.

Properti

SetRequestHeader

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

Properti

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Acara

onMessage

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

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

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (details: object) => void

    • detail

      objek

      • documentId

        string opsional

        UUID dokumen yang membuat permintaan.

      • Siklus proses dokumen.

      • 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.

      • Jenis frame tempat navigasi terjadi.

      • pesan

        string

        Pesan yang dikirim oleh skrip panggilan.

      • metode

        string

        Metode HTTP standar.

      • parentDocumentId

        string opsional

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

      • parentFrameId

        angka

        ID frame yang membungkus frame yang mengirim permintaan. Disetel ke -1 jika tidak ada frame induk.

      • requestId

        string

        ID permintaan. ID permintaan bersifat unik dalam sesi browser. Oleh karena itu, ID ini dapat digunakan untuk menghubungkan berbagai peristiwa dari permintaan yang sama.

      • tahap

        Tahap

        Tahap permintaan jaringan selama peristiwa dipicu.

      • tabId

        angka

        ID tab tempat permintaan dilakukan. Disetel 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