Kebijakan PopulateCache

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Mengonfigurasi cara nilai yang di-cache harus ditulis saat runtime.

Kebijakan Populate Cache dirancang untuk menulis entri dalam cache tujuan umum jangka pendek. Kebijakan ini digunakan bersama dengan kebijakan Cache Lookup (untuk membaca entri cache) dan kebijakan Batalkan Cache (untuk membatalkan entri).

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Untuk menyimpan respons resource backend dalam cache, lihat kebijakan Cache Respons.

Referensi elemen

Berikut adalah elemen yang dapat Anda konfigurasi pada kebijakan ini.

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

Atribut <PopulateCache>

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

Atribut	Deskripsi	Default	Kehadiran
name	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.	T/A	Wajib
continueOnError	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini	false	Opsional
enabled	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.	benar	Opsional
async	Atribut ini tidak digunakan lagi.	false	Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>

Default	T/A Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran	Opsional
Jenis	String

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>

Default:	T/A
Kehadiran:	Wajib
Jenis:	T/A

<CacheKey> membuat nama setiap bagian data yang disimpan dalam cache.

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 <CacheResource>

Menentukan cache tempat pesan harus disimpan.

Hapus elemen ini sepenuhnya jika kebijakan ini (dan kebijakan LookupCache serta InvalidateCache yang sesuai) menggunakan cache bersama yang disertakan.

<CacheResource>cache_to_use</CacheResource>

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

Untuk mengetahui informasi selengkapnya tentang mengonfigurasi cache, lihat Caching tujuan umum.

Elemen <CacheKey>/<KeyFragment>

Menentukan nilai yang harus disertakan dalam kunci cache. Tentukan variabel yang akan di-dereferensikan dengan atribut ref, atau nilai tetap.

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

Default:	T/A
Kehadiran:	nol atau lebih
Jenis:	T/A

Saat runtime, Apigee membuat kunci cache dengan menambahkan nilai yang diperoleh dari elemen <Scope> atau elemen <Prefix>, ke gabungan nilai yang di-resolve dari setiap elemen <KeyFragment>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Atribut

Atribut	Jenis	Default	Wajib	Deskripsi
ref	string		Tidak	Variabel yang akan diambil nilainya. Tidak boleh digunakan jika elemen ini berisi nilai literal.

Elemen <CacheKey>/<Prefix>

Menentukan nilai tetap yang akan digunakan sebagai awalan kunci cache.

<Prefix>prefix_string</Prefix>

Default:	T/A
Kehadiran:	Opsional
Jenis:	String

Elemen <Prefix> menggantikan elemen <Scope>.

Saat runtime, Apigee membuat kunci cache dengan menambahkan nilai yang diperoleh dari elemen <Scope> atau elemen <Prefix>, ke gabungan nilai yang di-resolve dari setiap elemen <KeyFragment>. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan kunci cache.

Elemen <ExpirySettings>

Menentukan kapan entri cache harus berakhir masa berlakunya.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Default:	T/A
Kehadiran:	Wajib
Jenis:	T/A

Elemen turunan <ExpirySettings>

Gunakan tepat satu elemen turunan. Tabel berikut memberikan deskripsi elemen turunan <ExpirySettings>:

Elemen Turunan	Deskripsi
<TimeoutInSeconds>	Jumlah detik setelah entri cache harus berakhir. <ExpirySettings> <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds> </ExpirySettings> Elemen ini menggantikan elemen TimeoutInSec yang kini tidak digunakan lagi.
<ExpiryDate>	Menentukan tanggal saat entri cache harus habis masa berlakunya. Tentukan string dalam format mm-dd-yyyy. <ExpirySettings> <ExpiryDate ref="var-containing-date">expiry</ExpiryDate> </ExpirySettings> Jika tanggal yang ditentukan sudah berlalu, kebijakan akan menerapkan waktu aktif maksimum ke entri yang di-cache. Durasi maksimumnya adalah 30 hari.
<TimeOfDay>	Menentukan waktu dalam sehari saat entri cache harus berakhir. Tentukan string dalam bentuk HH:mm:ss, dengan HH mewakili jam dalam format 24 jam, di zona waktu UTC. Misalnya, 14:30:00 berarti 2:30 siang. <ExpirySettings> <TimeOfDay ref="var-containing-time">expiry</TimeOfDay> </ExpirySettings> Catatan: Tentukan waktu dalam zona waktu Coordinated Universal Time (UTC). Notasi waktu Isi Cache mengikuti notasi tanggal standar internasional yang ditentukan dalam Standar Internasional ISO 8601.

Anda hanya boleh menentukan salah satu elemen turunan yang memungkinkan. Jika Anda menentukan beberapa elemen, urutan prioritasnya adalah:TimeoutInSeconds, ExpiryDate, TimeOfDay.

Dengan setiap elemen turunan <ExpirySettings> di atas, jika Anda menentukan atribut ref opsional pada elemen turunan, kebijakan akan mengambil nilai habis masa berlaku dari variabel konteks bernama. Jika variabel tidak ditentukan, kebijakan akan menggunakan nilai teks literal elemen turunan.

Elemen <Scope>

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

<Scope>scope_enumeration</Scope>

Default:	"Eksklusif"
Kehadiran:	Opsional
Jenis:	String

Setelan <Scope> menentukan kunci cache yang ditambahkan di awal sesuai dengan nilai <Scope>. Misalnya, kunci cache akan berbentuk seperti berikut saat cakupan disetel ke Exclusive:

orgName__envName__apiProxyName__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

Global	Kunci cache dibagikan di semua proxy API yang di-deploy di lingkungan. Kunci cache ditambahkan dalam bentuk orgName __ envName __. Jika Anda menentukan entri <CacheKey> dengan <KeyFragment> apiAccessToken dan cakupan <Global>, setiap entri disimpan sebagai orgName__envName__apiAccessToken, diikuti dengan nilai token akses yang diserialkan. Untuk proxy API yang di-deploy di lingkungan bernama 'test' dalam organisasi bernama 'apifactory', token akses akan disimpan di bawah kunci cache berikut: apifactory__test__apiAccessToken.
Application	Nama proxy API digunakan sebagai awalan. Kunci cache diawali dalam bentuk orgName__envName__apiProxyName.
Proxy	Konfigurasi ProxyEndpoint digunakan sebagai awalan. Kunci cache diawali dalam bentuk orgName__envName__apiProxyName__proxyEndpointName .
Target	Konfigurasi TargetEndpoint digunakan sebagai awalan. Kunci cache yang ditambahkan dalam bentuk orgName__envName__apiProxyName__targetEndpointName .
Exclusive	Default. Ini adalah yang paling spesifik, sehingga menimbulkan risiko minimal terjadinya konflik namespace dalam cache tertentu. Awalan memiliki salah satu dari dua bentuk berikut: Jika kebijakan dilampirkan ke alur ProxyEndpoint, awalan memiliki bentuk ApiProxyName_ProxyEndpointName. Jika kebijakan dilampirkan di TargetEndpoint, awalan akan berbentuk ApiProxyName_TargetName. Kunci cache yang ditambahkan dalam bentuk orgName__envName__apiProxyName__proxyNameITargetName Misalnya, string lengkapnya mungkin terlihat seperti ini: apifactory__test__weatherapi__default__apiAccessToken .

Elemen <Source>

Menentukan variabel yang nilainya harus ditulis ke cache.

<Source>source_variable</Source>

Default:	T/A
Kehadiran:	Wajib
Jenis:	String

Catatan:

• Objek JSON disimpan secara eksklusif di cache dalam memori (L1).
• Jika Anda ingin menyimpan objek ini dalam cache persisten (L2), sebaiknya serialisasikan objek tersebut ke dalam format string.
• Dengan mengikuti praktik ini, Anda dapat menggunakan cache L2 secara efektif dan memaksimalkan efisiensi caching.
• Untuk informasi selengkapnya, lihat Internal cache.
  

Catatan penggunaan

Gunakan kebijakan ini untuk caching tujuan umum. Saat runtime, kebijakan <PopulateCache> menulis data dari variabel yang Anda tentukan di elemen <Source> ke cache yang Anda tentukan di elemen <CacheResource>. Anda dapat menggunakan elemen <CacheKey>, <Scope>, dan <Prefix> untuk menentukan kunci yang dapat Anda gunakan dari kebijakan <LookupCache> untuk mengambil nilai. Gunakan elemen <ExpirySettings> untuk mengonfigurasi kapan nilai yang di-cache harus berakhir.

Caching tujuan umum dengan kebijakan PopulateCache, kebijakan LookupCache, dan kebijakan InvalidateCache menggunakan cache yang Anda konfigurasi atau cache bersama yang disertakan secara default. Dalam sebagian besar kasus, cache bersama yang mendasarinya akan memenuhi kebutuhan Anda. Untuk menggunakan cache ini, cukup hapus elemen <CacheResource>.

Batas cache: Berbagai batas cache berlaku, seperti ukuran nama dan nilai, jumlah total cache, jumlah item dalam cache, dan masa berlaku.

Untuk mengetahui informasi selengkapnya tentang penyimpanan data yang mendasarinya, lihat Internal cache.

Tentang enkripsi cache

Apigee dan Apigee Hybrid (versi 1.4 dan yang lebih baru): Data Cache dan KVM selalu dienkripsi.

Kode error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode kerusakan	Status HTTP	Terjadi saat
policies.populatecache.EntryCannotBeCached	500	Entri tidak dapat di-cache. Objek pesan yang di-cache bukan instance class yang bersifat Serializable.

Error saat deployment

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

Tips: Perlu bantuan untuk mengatasi error? Klik di kolom Perbaiki untuk mengetahui informasi pemecahan masalah mendetail.

Nama error	Penyebab	Perbaiki
InvalidCacheResourceReference	Error ini terjadi jika elemen <CacheResource> dalam kebijakan PopulateCache ditetapkan ke nama yang tidak ada di lingkungan tempat proxy API di-deploy.
CacheNotFound	Cache yang ditentukan dalam elemen <CacheResource> tidak ada.

Variabel error

Variabel ini ditetapkan saat kebijakan ini memicu error. Untuk mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel	Dari mana	Contoh
fault.name="fault_name"	fault_name adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama error adalah bagian terakhir dari kode error.	fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed	policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error.	populatecache.POP-CACHE-1.failed = true

Contoh respons error

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

Contoh aturan error

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>