Kebijakan ResponseCache

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Menyimpan data dalam cache dari resource backend, sehingga mengurangi jumlah permintaan ke resource. Saat aplikasi membuat permintaan ke URI yang sama, Anda dapat menggunakan kebijakan ini untuk menampilkan respons yang di-cache, bukan meneruskan permintaan tersebut ke server backend. Kebijakan ResponseCache dapat meningkatkan performa API Anda melalui pengurangan latensi dan traffic jaringan.

Anda mungkin akan merasa ResponseCache paling berguna saat data backend yang digunakan oleh API Anda hanya diperbarui secara berkala. Misalnya, bayangkan Anda memiliki API yang menampilkan data laporan cuaca yang diperbarui hanya setiap sepuluh menit. Dengan menggunakan ResponseCache untuk menampilkan respons yang di-cache di antara penyegaran, Anda dapat mengurangi jumlah permintaan yang mencapai backend. Tindakan ini juga mengurangi jumlah hop jaringan.

Untuk caching jangka pendek tujuan umum, pertimbangkan untuk menggunakan kebijakan Isi Cache. Kebijakan tersebut digunakan bersama dengan kebijakan Lookup Cache (untuk membaca entri cache) dan kebijakan Invalidate Cache (untuk menginvalidasi entri).

Contoh

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

Atribut <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

Tabel berikut menjelaskan atribut yang umum untuk semua elemen induk kebijakan:

&lt;DisplayName&gt; elemen

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI dengan nama natural language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Elemen <CacheKey>

Mengonfigurasi pointer unik ke bagian data yang disimpan dalam cache.

Kunci cache dibatasi hingga ukuran 2 KB.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

<CacheKey> membuat nama setiap bagian data yang disimpan dalam cache. Kunci sering kali ditetapkan menggunakan nilai dari header entity atau parameter kueri. Dalam kasus tersebut, Anda akan memiliki atribut ref elemen yang menentukan variabel yang berisi nilai kunci.

Saat runtime, nilai <KeyFragment> diawali dengan nilai elemen <Scope> atau nilai <Prefix>. Misalnya, berikut menghasilkan kunci cache UserToken__apiAccessToken__<value_of_client_id>:

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

Anda menggunakan elemen <CacheKey> bersama dengan <Prefix> dan <Scope>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Elemen <CacheLookupTimeoutInSeconds>

Menentukan jumlah detik setelah pencarian cache yang tidak berhasil akan dianggap sebagai cache tidak ditemukan. Jika hal ini terjadi, alur akan dilanjutkan di sepanjang jalur cache tidak ditemukan.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Elemen <CacheResource>

Menentukan cache tempat pesan harus disimpan. Hapus elemen ini untuk menggunakan cache bersama yang disertakan. Anda harus menentukan CacheResource menurut nama jika ingin dapat menghapus entri yang ada dalam cache secara administratif. Untuk mengetahui informasi selengkapnya, lihat Cache.

<CacheResource>cache_to_use</CacheResource>

Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi cache, lihat Membuat dan mengedit cache lingkungan.

Elemen <CacheKey>/<KeyFragment>

Menentukan nilai yang harus disertakan dalam kunci cache, sehingga membuat namespace untuk mencocokkan permintaan dengan respons yang di-cache.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Ini dapat berupa kunci (nama statis yang Anda berikan) atau nilai (entri dinamis yang ditetapkan dengan mereferensikan variabel). Semua fragmen yang ditentukan digabungkan (ditambah awalan) untuk membuat kunci cache.

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

Anda menggunakan elemen <KeyFragment> bersama dengan <Prefix> dan <Scope>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Atribut

Elemen <CacheKey>/<Prefix>

Menentukan nilai yang akan digunakan sebagai awalan kunci cache.

<Prefix>prefix_string</Prefix>

Gunakan nilai ini, bukan <Scope>, jika Anda ingin menentukan nilai Anda sendiri, bukan nilai yang di-enumerasi <Scope>. Jika ditentukan, <Prefix> menambahkan nilai kunci cache untuk entri yang ditulis ke cache. Nilai elemen <Prefix> menggantikan nilai elemen <Scope>.

Anda menggunakan elemen <Prefix> bersama dengan <CacheKey> dan <Scope>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Elemen <ExcludeErrorResponse>

Saat ini, secara default, kebijakan ini meng-cache respons HTTP dengan kode status apa pun yang mungkin. Artinya, respons berhasil dan error di-cache. Misalnya, respons dengan kode status 2xx dan 3xx di-cache secara default.

Tetapkan elemen ini ke true jika Anda tidak ingin meng-cache respons target dengan kode status error HTTP; hanya respons dengan kode status dari 200 hingga 205 yang akan di-cache jika elemen ini benar (true). Ini adalah satu-satunya kode status HTTP yang dihitung Edge sebagai kode "berhasil", dan Anda tidak dapat mengubah hubungan ini.

Untuk pembahasan pola Response Cache yang menggunakan elemen ini, lihat postingan komunitas ini.

Catatan: Dalam rilis mendatang (yang akan ditentukan), setelan default elemen ini akan berubah menjadi benar (true). Lihat Catatan Rilis Apigee untuk mengetahui detailnya.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Elemen <ExpirySettings>

Menentukan kapan entri cache harus habis masa berlakunya. Jika ada, <TimeoutInSeconds> akan menggantikan <TimeOfDay> dan <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Elemen <ExpirySettings>/<ExpiryDate>

Menentukan tanggal habis masa berlaku entri cache. Gunakan formulir mm-dd-yyyy. Jika ada, elemen seinduk ini, <TimeoutInSeconds>, akan menggantikan <ExpiryDate>.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Atribut

<ExpiryDate ref="" />

Elemen <ExpirySettings>/<TimeOfDay>

Waktu dalam sehari saat entri cache harus berakhir masa berlakunya. Gunakan formulir hh:mm:ss . Jika ada, elemen seinduk ini, <TimeoutInSeconds>, akan menggantikan <TimeOfDay>.

Masukkan waktu dalam format HH:mm:ss, dengan HH mewakili jam pada jam 24 jam. Misalnya, 14:30:00 untuk 14.30.

Untuk waktu dalam sehari, lokalitas dan zona waktu default akan bervariasi bergantung pada tempat kode dijalankan (yang tidak diketahui saat Anda mengonfigurasi kebijakan). Untuk mengetahui informasi tentang cara mengonfigurasi lokalitas, lihat Membuat dan mengedit cache lingkungan.

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Atribut

Elemen <ExpirySettings>/<TimeoutInSec>

Jumlah detik setelah entri cache harus berakhir.

Elemen <ExpirySettings>/<TimeoutInSeconds>

Jumlah detik setelah entri cache harus berakhir. Jika ada, elemen ini menggantikan elemen saudaranya, <TimeOfDay> dan <ExpiryDate>.

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

Catatan: Berikan nilai waktu tunggu default untuk digunakan jika ref tidak menerima nilai dari duration_variable.

Atribut

Elemen <Scope>

Enumerasi yang digunakan untuk membuat awalan untuk kunci cache saat elemen <Prefix> tidak disediakan dalam elemen <CacheKey>.

<Scope>scope_enumeration</Scope>

Setelan <Scope> menentukan kunci cache yang ditambahkan di awal sesuai dengan nilai <Scope>. Misalnya, kunci cache akan berbentuk seperti berikut saat cakupan ditetapkan ke Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

Jika elemen <Prefix> ada di <CacheKey>, elemen tersebut akan menggantikan nilai elemen <Scope>. Nilai yang valid mencakup enumerasi di bawah.

Anda menggunakan elemen <Scope> bersama dengan <CacheKey> dan <Prefix>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Nilai yang dapat diterima

apifactory__test__weatherapi__16__default__apiAccessToken

Elemen <SkipCacheLookup>

Menentukan ekspresi yang, jika bernilai benar saat runtime, menentukan bahwa pencarian cache harus dilewati dan cache harus dimuat ulang. Lihat juga video ini tentang penggunaan SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Dari contoh berikut, jika variabel bypass-cache disetel ke benar (true) di header masuk, pencarian cache dilewati dan cache diperbarui.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

Elemen <SkipCachePopulation>

Menentukan ekspresi yang, jika bernilai benar saat runtime, menentukan bahwa penulisan ke cache harus dilewati. Lihat juga video ini tentang penggunaan SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Misalnya, kode berikut akan melewati penulisan cache jika kode status respons adalah 400 atau lebih tinggi:

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

Elemen <UseAcceptHeader>

Setel ke true agar kunci cache entri cache respons ditambahkan dengan nilai dari header Accept respons.

Edge menggunakan header permintaan Accept, Accept-Encoding, Accept-Language dan Accept-Charset saat menghitung kunci cache. Pendekatan ini mencegah klien mendapatkan jenis media yang tidak mereka minta.

Misalnya, pertimbangkan jika dua permintaan masuk dari URL yang sama, dengan permintaan pertama menerima gzip dan permintaan kedua tidak. Permintaan pertama akan di-cache, dan entri yang di-cache akan (mungkin) berupa respons yang di-gzip. Permintaan kedua akan membaca nilai yang di-cache dan kemudian dapat menampilkan entri yang di-gzip ke klien yang tidak dapat membaca gzip.

Lihat Mengonfigurasi kunci cache untuk mengetahui informasi selengkapnya.

<UseAcceptHeader>false</UseAcceptHeader>

Elemen <UseResponseCacheHeaders>

Setel ke true agar header respons HTTP dipertimbangkan saat menetapkan "time to live" (TTL) respons dalam cache. Jika benar, Edge akan mempertimbangkan nilai header respons berikut, membandingkan nilai dengan nilai yang ditetapkan oleh <ExpirySettings> saat menetapkan time to live (TTL):

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

Lihat Menetapkan masa berlaku entri cache untuk mengetahui detail selengkapnya.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Catatan penggunaan

Ukuran maksimum untuk setiap objek yang di-cache adalah 256 KB. (Untuk mengetahui informasi mendetail tentang cara Edge memproses cache, lihat Internal cache.)

Melalui konfigurasi dalam kebijakan ResponseCache, Anda dapat membuat Edge menyertakan header respons HTTP dalam menetapkan masa berlaku entri cache dan kunci cache. Bagian ini menjelaskan cara menggunakan kebijakan dengan header untuk mengelola masa berlaku cache dan kunci cache.

Untuk mengetahui informasi selengkapnya tentang cara Edge menangani header respons dengan kebijakan ResponseCache, lihat Dukungan untuk header respons HTTP.

Menyetel masa berlaku entri cache

Seperti Kebijakan Populasi Cache, Anda dapat menetapkan masa berlaku entri cache respons (time to live (TTL)) menggunakan elemen <ExpirySettings>. Dalam kebijakan ResponseCache, Anda juga dapat membuat Edge mempertimbangkan header respons jika ada.

Untuk menggunakan header respons, Anda menetapkan nilai elemen <UseResponseCacheHeaders> ke benar. Setelan tersebut menyebabkan Edge mempertimbangkan header respons, membandingkannya dengan nilai yang ditetapkan oleh <ExpirySettings>, lalu menggunakan nilai terendah di antara keduanya. Saat mempertimbangkan header respons, Edge memilih nilai yang tersedia seperti yang dijelaskan di bawah:

Misalnya, bayangkan respons di-cache dengan nilai berikut:

• Tidak ada nilai Cache-Control s-maxage
• Nilai Cache-Control max-age sebesar 300
• Tanggal Expires dalam tiga hari
• Nilai <ExpirySettings> TimeoutInSeconds sebesar 600.

Dalam hal ini, nilai Cache-Control max-age akan digunakan untuk TTL karena lebih rendah dari nilai <ExpirySettings> dan karena tidak ada nilai Cache-Control s-maxage (yang lebih diutamakan daripada max-age).

Mengonfigurasi kunci cache

Seperti kebijakan cache tujuan umum seperti kebijakan Isi Cache, dengan ResponseCache, Anda menggunakan elemen <CacheKey> dan <Scope> untuk mengonfigurasi pembuatan kunci cache untuk entri cache. Dengan ResponseCache, Anda juga dapat membuat kunci cache lebih bermakna dengan menambahkan header Accept respons ke nilai kunci.

Untuk mengetahui informasi umum tentang cara mengonfigurasi kunci cache, lihat Bekerja dengan kunci cache. Untuk informasi tentang penggunaan header Accept, lihat <UseAcceptHeader>.

Tentang enkripsi cache

Edge untuk Cloud Publik: Cache dienkripsi hanya di organisasi yang mendukung PCI- dan HIPAA. Enkripsi untuk organisasi tersebut dikonfigurasi selama penyediaan organisasi.

Variabel alur

Variabel Flow bawaan berikut diisi saat kebijakan ResponseCache dijalankan. Untuk mengetahui informasi selengkapnya tentang variabel Flow, lihat Referensi variabel.

Kode error

Bagian ini menjelaskan pesan error dan variabel alur yang ditetapkan saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda sedang mengembangkan aturan fault untuk proxy. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Awalan kode error

T/A

Error runtime

Kebijakan ini tidak menampilkan error runtime apa pun.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Variabel kesalahan

T/A

Contoh respons error

T/A

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.