Kebijakan MonetizationLimitsCheck

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Catatan: Kebijakan MonetizationLimitsCheck hanya berlaku jika Anda telah mengaktifkan monetisasi Apigee di organisasi.

Ringkasan

Kebijakan MonetizationLimitsCheck memungkinkan Anda menerapkan batas monetisasi.

Secara khusus, kebijakan ini dipicu jika developer aplikasi yang mengakses API yang dimonetisasi belum membeli langganan untuk produk API terkait atau jika developer tidak memiliki saldo yang cukup. Dalam hal ini, kebijakan MonetizationLimitsCheck akan melaporkan kesalahan dan memblokir panggilan API. Untuk informasi selengkapnya, lihat Menerapkan langganan developer ke produk API.

Saat Anda melampirkan kebijakan MonetizationLimitsCheck ke proxy API, variabel alur mint.limitscheck.* dan mint.subscription_* akan terisi, seperti yang dijelaskan dalam referensi variabel alur mint.

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

Catatan: Meskipun menggunakan kebijakan MonetizationLimitsCheck, Anda mungkin developer prabayar akan diizinkan melakukan panggilan API berlebih dengan saldo dompet negatif. Untuk memahami kondisi di mana saldo developer akan menjadi negatif, lihat Saldo developer negatif.

<MonetizationLimitsCheck>

Menentukan kebijakan MonetizationLimitsCheck.

Nilai Default	T/A
Wajib?	Wajib
Jenis	Jenis kompleks
Elemen Induk	T/A
Elemen Turunan	<DisplayName> <FaultResponse> <IgnoreUnresolvedVariables>

Tabel berikut memberikan deskripsi tingkat tinggi untuk elemen turunan <MonetizationLimitsCheck>:

Elemen Turunan	Wajib?	Deskripsi
<DisplayName>	Opsional	Nama kustom untuk kebijakan.
<FaultResponse>	Opsional	Menentukan pesan respons yang ditampilkan ke klien yang meminta.
<IgnoreUnresolvedVariables>	Opsional	Mengabaikan error variabel yang belum terselesaikan dalam alur.

Elemen <MonetizationLimitsCheck> menggunakan sintaksis berikut:

Sintaks

<?xml version="1.0" encoding="UTF-8" standalone="no"?><MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
   <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
   <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
       </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>VALUE</IgnoreUnresolvedVariables>
</MonetizationLimitsCheck>

Contoh

Dalam contoh berikut, jika developer belum membeli langganan untuk produk API terkait, akses ke API yang dimonetisasi diblokir, dan Status 403 ditampilkan dengan pesan kustom.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <DisplayName>Monetization-Limits-Check-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:

Atribut	Default	Wajib?	Deskripsi
name	T/A	Wajib	Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter. Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
continueOnError	false	Opsional	Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani kesalahan dalam alur saat ini
enabled	true	Opsional	Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async	false	Tidak digunakan lagi	Atribut ini sudah tidak digunakan lagi.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan dari <MonetizationLimitsCheck>.

<DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih alami.

Elemen <DisplayName> bersifat umum untuk semua kebijakan.

Nilai Default	T/A
Wajib?	Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis	String
Elemen Induk	<PolicyElement>
Elemen Turunan	Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaksis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<FaultResponse>

Menentukan pesan respons yang ditampilkan ke klien yang meminta. FaultResponse menggunakan setelan yang sama dengan <FaultResponse> dalam kebijakan RaiseFault.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<MonetizationLimitsCheck>
Elemen Turunan	<AssignVariable> <Add> <Copy> <Remove> <Set>

<AssignVariable>

Menetapkan nilai ke variabel alur tujuan. Jika variabel flow tidak ada, AssignVariable akan membuatnya.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<FaultResponse>
Elemen Turunan	<Name> <Value>

Misalnya, gunakan kode berikut untuk menetapkan variabel bernama myFaultVar dalam kebijakan MonetizationLimitsCheck:

<FaultResponse>
<AssignVariable>
  <Name>myFaultVar</Name>
  <Value>42</Value>
</AssignVariable>
</FaultResponse>

Kemudian, kebijakan dalam aturan fault dapat mengakses variabel. Misalnya, kebijakan MenetapkanMessage berikut menggunakan variabel untuk menyetel Header dalam respons fault:

<AssignMessage enabled="true" name="Assign-Message-1">
<Add>
  <Headers>
    <Header name="newvar">{myFaultVar}</Header>
  </Headers>
</Add>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> dalam kebijakan MonetizationLimitsCheck menggunakan sintaksis yang sama dengan Elemen <AssignVariable> dalam kebijakan MenetapkanMessage.

<Name>

Nama variabel. Untuk informasi selengkapnya, lihat Nama dalam kebijakan MenetapkanMessage.

Nilai Default	T/A
Wajib?	Opsional
Jenis	String
Elemen Induk	<AssignVariable>
Elemen Turunan	Tidak ada

<Value>

Nilai variabel. Untuk informasi selengkapnya, lihat Nilai dalam kebijakan MenetapkanMessage.

Nilai Default	T/A
Wajib?	Opsional
Jenis	String
Elemen Induk	<AssignVariable>
Elemen Turunan	Tidak ada

<Add>

Menambahkan header HTTP ke pesan error.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<FaultResponse>
Elemen Turunan	<Headers>

<Headers>

Menentukan header HTTP yang akan ditambahkan, disetel, disalin, atau dihapus.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<Add> <Copy> <Remove> <Set>
Elemen Turunan	Tidak ada

• Header kosong (<Add><Headers/></Add>) tidak menambahkan header apa pun.
• Elemen <Header> mendukung fitur substitusi string dinamis yang disebut template pesan.

Contoh:

Tambahkan header

Contoh berikut menyalin nilai variabel alur request.user.agent ke dalam {i>header<i}:

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Tetapkan header

Contoh berikut menetapkan header user-agent ke variabel pesan yang ditentukan dengan elemen <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Salin header - 1

Contoh berikut menyalin headerA dari permintaan:

<Copy source='request'>
    <Headers>
        <Header name="headerA"/>
    </Headers>
</Copy>

Salin header - 2

Contoh berikut menyalin beberapa header:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

Contoh ini menyalin "h1", "h2", dan nilai kedua dari "h3". Jika "h3" hanya memiliki satu nilai, lalu "h3" tidak disalin.

Hapus header - 1

Contoh berikut menghapus header:

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Hapus header - 2

Contoh berikut menghapus beberapa header:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

Contoh ini menghapus "h1", "h2", dan nilai kedua dari "h3". Jika "h3" hanya memiliki satu nilai, lalu "h3" tidak dihapus.

<Copy>

Menyalin informasi dari pesan yang ditentukan oleh source ke pesan error.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<FaultResponse>
Elemen Turunan	<Headers> <StatusCode>

Tabel berikut menjelaskan atribut <Copy>:

Atribut	Wajib?	Jenis	Deskripsi
sumber	Opsional	String	Menentukan objek sumber salinan. Jika source tidak ditetapkan, maka diperlakukan sebagai pesan sederhana. Misalnya, jika kebijakan berada di alur permintaan, lalu sumber ditetapkan secara default ke objek request. Jika kebijakan dalam alur respons, secara default objek response. Jika Anda menghilangkan source, Anda dapat menggunakan referensi absolut ke variabel alur sebagai sumber salinan. Misalnya, sebutkan nilainya sebagai {request.header.user-agent}. Jika variabel sumber tidak dapat di-resolve, atau di-resolve menjadi jenis bukan pesan, <Copy> gagal merespons.

<StatusCode>

Menentukan kode status HTTP dalam pesan error. Anda dapat menyalin atau menetapkan nilai dari untuk objek yang ditentukan oleh atribut source.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<Copy> <Set>
Elemen Turunan	Tidak ada

Contoh:

Salin kode status

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Tetapkan kode status

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<Remove>

Menghapus header HTTP yang ditentukan dari pesan error. Untuk menghapus semua {i>header<i}, tentukan <Remove><Headers/></Remove>.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<FaultResponse>
Elemen Turunan	<Headers>

<Set>

Menetapkan informasi dalam pesan error.

Nilai Default	T/A
Wajib?	Opsional
Jenis	Jenis kompleks
Elemen Induk	<FaultResponse>
Elemen Turunan	<Headers> <Payload> <StatusCode>

<Payload>

Menetapkan payload pesan error.

Nilai Default	T/A
Wajib?	Opsional
Jenis	String
Elemen Induk	<Set>
Elemen Turunan	Tidak ada

Contoh:

Menyetel payload teks

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Menetapkan payload JSON - 1

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

Menetapkan payload JSON - 2

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

Contoh ini menyisipkan variabel menggunakan variablePrefix dan Atribut variableSuffix dengan karakter pembatas.

Menetapkan payload JSON - 3

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Contoh ini menyisipkan variabel menggunakan tanda kurung kurawal. Anda dapat menggunakan tanda kurung kurawal mulai dari dengan rilis 16.08.17.

Menetapkan payload XML

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Contoh ini menyisipkan variabel menggunakan tanda kurung kurawal. Anda dapat menggunakan tanda kurung kurawal mulai dari dengan rilis 16.08.17.

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum terselesaikan ditemukan.

Tetapkan ke true untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan; jika tidak, false. Tujuan nilai defaultnya adalah true.

Menyetel <IgnoreUnresolvedVariables> ke true berbeda dengan menyetel <MonetizationLimitsCheck> continueOnError hingga true. Jika Anda menetapkan continueOnError ke true, Apigee akan mengabaikan semua error, bukan hanya {i>error <i} dalam variabel.

Elemen <IgnoreUnresolvedVariables> menggunakan sintaksis berikut:

Sintaks

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

Contoh

Contoh berikut menetapkan <IgnoreUnresolvedVariables> ke false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Kode error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan	Status HTTP	Penyebab
mint.service.subscription_not_found_for_developer	500	Error ini terjadi ketika developer tidak memiliki langganan Produk API.
mint.service.wallet_not_found_for_developer	500	Error ini terjadi saat developer prabayar mencoba menggunakan API yang dimonetisasi tanpa memiliki dompet untuk mata uang yang ditentukan dalam paket tarif.
mint.service.developer_usage_exceeds_balance	500	Error ini terjadi saat penggunaan developer prabayar melebihi saldo dompet.
mint.service.wallet_blocked_due_to_inactivity	500	Error ini terjadi ketika dompet developer prabayar tidak diisi ulang selama lebih dari 1,5 tahun dan developer mencoba menggunakan API.

Variabel kesalahan

Setiap kali terjadi error eksekusi dalam kebijakan, Apigee akan menghasilkan pesan error. Anda dapat melihat pesan error ini dalam respons error. Sering kali, pesan error yang dihasilkan sistem mungkin tidak relevan dalam konteks produk Anda. Anda mungkin ingin menyesuaikan pesan error berdasarkan jenis error agar pesan menjadi lebih bermakna.

Untuk menyesuaikan pesan error, Anda dapat menggunakan aturan kesalahan atau kebijakan RaiseFault. Untuk mengetahui informasi tentang perbedaan antara aturan fault dan kebijakan RaiseFault, lihat kebijakan FaultRules vs. RaiseFault. Anda harus memeriksa kondisi menggunakan elemen Condition di aturan fault dan kebijakan RaiseFault. Apigee menyediakan variabel kesalahan yang unik untuk setiap kebijakan dan nilai variabel kesalahan ditetapkan saat kebijakan memicu error runtime. Dengan menggunakan variabel ini, Anda dapat memeriksa kondisi error tertentu dan mengambil tindakan yang sesuai. Untuk mengetahui informasi selengkapnya tentang cara memeriksa kondisi error, lihat Kondisi build.

Variabel	Dari mana	Contoh
fault.name	fault.name dapat cocok dengan kesalahan mana pun yang tercantum dalam tabel Error runtime. Nama kesalahan adalah bagian terakhir dari kode kesalahan.	fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed	POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan.	MonetizationLimitsCheck.monetization-limits-check-1.failed = true

Untuk mengetahui informasi selengkapnya tentang error kebijakan, lihat Yang perlu Anda ketahui tentang error kebijakan

Variabel flow

Variabel alur standar berikut akan otomatis diisi saat kebijakan MonetizationLimitsCheck akan dijalankan. Untuk informasi selengkapnya, lihat variabel alur mint.

Variabel aliran	Deskripsi
mint.limitscheck.is_request_blocked	true untuk permintaan yang diblokir.
mint.limitscheck.is_subscription_found	true jika langganan API ditemukan.
mint.limitscheck.purchased_product_name	Nama produk API yang dibeli. Misalnya: MyProduct.
mint.limitscheck.status_message	Pesan status. Misalnya: limits_check_success.
mint.subscription_end_time_ms	Waktu berakhir langganan produk API.
mint.subscription_start_time_ms	Waktu mulai langganan produk API. Misalnya: 1618433956209.