Kebijakan JavaCallout

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

ikon kebijakan

Apa

Memungkinkan Anda menggunakan Java untuk menerapkan perilaku kustom yang tidak disertakan sejak awal Kebijakan Apigee. Dalam kode Java Anda, Anda dapat mengakses properti pesan ({i>header<i}, parameter kueri, ) dan variabel alur dalam alur proxy. Jika Anda baru memulai dengan kebijakan ini, lihat Cara membuat Java info.

Versi Java yang didukung meliputi: Oracle JDK 11 dan OpenJDK 11

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.

Kapan

Untuk panduan, lihat "Kapan saya harus menggunakan info Java?" di Cara membuat paket Java info.

Tentang

Kebijakan Pemanggilan Java memungkinkan Anda mendapatkan dan menyetel variabel alur, menjalankan logika kustom, dan melakukan penanganan {i>error<i}, mengekstrak data dari permintaan atau respons, dan banyak lagi. Kebijakan ini memungkinkan Anda menerapkan perilaku kustom yang tidak tercakup dalam kebijakan Apigee standar lainnya.

Anda dapat mengemas aplikasi Java dengan file JAR paket apa pun yang dibutuhkan. Catatan ada beberapa batasan pada hal-hal yang dapat Anda lakukan dengan Java callout. Hal tersebut tercantum di bawah di Pembatasan.

Sampel

Contoh sederhana

Cara membuat Java info

Mengambil properti dalam kode Java

Elemen <Property> kebijakan memungkinkan Anda menentukan nama/nilai yang bisa Anda ambil saat runtime dalam kode Java. Sebagai contoh nyata yang menggunakan properti, lihat Cara menggunakan properti dalam info Java.

Gunakan <Property> ke atribut name elemen untuk menentukan nama dengan untuk mengakses properti dari kode Java. Elemen <Property> (nilai antara tag pembuka dan penutup) adalah nilai yang akan diterima oleh kode Java. Nilai harus berupa string; Anda tidak dapat mereferensikan variabel flow untuk mendapatkan dengan sejumlah nilai.

  • Konfigurasikan properti. Di sini, nilai properti adalah nama variabel response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • Dalam kode Java Anda, implementasikan konstruktor berikut pada kelas Execution penerapan sebagai berikut:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Menetapkan variabel flow di kode Java

Untuk deskripsi yang jelas tentang cara menetapkan variabel dalam konteks pesan (variabel alur) dalam kode Java Anda, lihat postingan Komunitas Apigee ini.

Referensi elemen

Referensi elemen menjelaskan elemen dan atribut kebijakan Javacallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

&lt;JavaCallout&gt; atribut

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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 kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

 T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal. Lihat juga:

 salah Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan ini tidak akan ditegakkan meskipun tetap terikat pada alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 salah Tidak digunakan lagi

&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>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan menjadi data
Kehadiran Opsional
Jenis String

&lt;ClassName&gt; elemen

Menentukan nama class Java yang dijalankan saat kebijakan Panggilan Java berjalan. Tujuan harus disertakan dalam file JAR yang ditentukan oleh <ResourceURL>. Lihat juga Cara membuat info.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Default: T/A
Kehadiran: Wajib
Jenis: String

&lt;Properties&gt; elemen

Menambahkan properti baru yang dapat Anda akses dari kode Java saat runtime.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Default: Tidak ada
Kehadiran: Opsional
Jenis: String

&lt;Property&gt; elemen

Menentukan properti yang dapat Anda akses dari kode Java saat runtime. Anda harus menentukan literal nilai string untuk setiap properti; Anda tidak dapat mereferensikan variabel alur dalam elemen ini. Untuk contoh kerja yang menggunakan properti, lihat Cara menggunakan properti Keterangan Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Default: Tidak ada
Kehadiran: Opsional
Jenis: String

Atribut

Atribut Deskripsi Default Kehadiran
nama

Menentukan nama properti.

 T/A Wajib.

&lt;ResourceURL&gt; elemen

Elemen ini menentukan file JAR Java yang akan dieksekusi saat kebijakan pemanggilan Java yang dijalankan.

Anda bisa menyimpan file ini di cakupan proxy API (di bagian /apiproxy/resources/java di paket proxy API atau di bagian Skrip panel Navigator editor proxy API), atau pada cakupan organisasi atau lingkungan untuk digunakan kembali di beberapa proxy API, seperti yang dijelaskan dalam File resource.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Default: Tidak ada
Kehadiran: Wajib
Jenis: String

Referensi 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 Perbaikan
steps.javacallout.ExecutionError 500 Terjadi saat kode Java menampilkan pengecualian atau menampilkan null selama eksekusi JavaCallout policy.

Error saat deployment

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

Nama error String kesalahan Status HTTP Terjadi saat
ResourceDoesNotExist Resource with name [name] and type [type] does not exist T/A File yang ditentukan dalam elemen <ResourceURL> tidak ada.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] T/A File class yang ditentukan dalam elemen <ClassName> tidak ada dalam jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] T/A Lihat string kesalahan. Versi Java yang didukung meliputi: Oracle JDK 7/8 dan OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] T/A Lihat string kesalahan.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] T/A Lihat string kesalahan.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] T/A Lihat string kesalahan.
NoResourceForURL Could not locate a resource with URL [string] T/A Lihat string kesalahan.

Variabel kesalahan

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

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. javacallout.JC-GetUserData.failed = true

Contoh respons error

{
   "fault":{
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Contoh aturan kesalahan

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Skema

Mengompilasi dan men-deploy

Untuk detail tentang cara mengompilasi kode Java kustom Anda dan men-deploy-nya dengan proxy, lihat Cara membuat Java info.

Pembatasan

Berikut adalah batasan yang perlu Anda pertimbangkan saat menulis Info Java:

  • Sebagian besar panggilan sistem tidak diizinkan. Misalnya, Anda tidak dapat membuat pembacaan sistem file internal atau tulis.
  • Akses ke jaringan melalui soket. Apigee membatasi akses ke sitelocal, anylocal, loopback, dan linklocal addresses.
  • Info tidak dapat memperoleh informasi tentang proses saat ini, daftar proses, atau Pemakaian CPU/memori pada mesin. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas dengan versi baru, Anda dapat sebaiknya hindari melakukan panggilan seperti itu di kode Anda.
  • Mengandalkan library Java yang disertakan dengan Apigee tidak didukung. Mereka library hanya untuk fungsi produk Apigee, dan tidak ada jaminan bahwa library tersedia mulai dari rilis hingga rilis.
  • Jangan gunakan io.apigee atau com.apigee sebagai nama paket di Java Info. Nama-nama tersebut dicadangkan dan digunakan oleh modul Apigee lainnya.

Paket

Tempatkan JAR di proxy API di bagian /resources/java. Jika pemanggilan Java bergantung pada library pihak ketiga tambahan yang dikemas sebagai file JAR independen, lalu menempatkan file JAR tersebut di direktori /resources/java juga untuk memastikannya dimuat dengan benar di waktu beroperasi.

Jika Anda menggunakan UI pengelolaan untuk membuat atau memodifikasi proxy, tambahkan resource baru dan menentukan file JAR dependen tambahan. Jika ada beberapa JAR, cukup tambahkan sebagai resource tambahan. Anda tidak perlu mengubah konfigurasi kebijakan untuk merujuk ke File JAR. Memasukkannya di /resources/java saja sudah cukup.

Untuk mengetahui informasi tentang cara mengupload JAR Java, lihat File resource.

Untuk contoh mendetail yang menunjukkan cara mengemas dan men-deploy Java callout menggunakan Maven atau javac, lihat Cara membuat paket info.

Javadoc

Javadoc untuk menulis kode Info Java disertakan di sini di GitHub. Anda harus menggandakan atau mengunduh HTML ke sistem, dan kemudian cukup buka index.html di browser.

Catatan penggunaan dan praktik terbaik

  • Saat menangani beberapa info Java, pertimbangkan untuk mengupload JAR umum sebagai resource cakupan lingkungan. Praktik ini lebih efisien dibandingkan dengan memaketkan JAR yang sama dengan beberapa proxy paket saat men-deploy ke lingkungan yang sama.
  • Hindari mengemas dan men-deploy beberapa salinan atau versi file JAR yang sama ke lingkungan fleksibel App Engine. Misalnya, Apigee merekomendasikan agar Anda menghindari:
    • Men-deploy JAR yang sama sebagai bagian dari paket proxy dan sebagai resource lingkungan.
    • Men-deploy satu versi file JAR sebagai resource lingkungan dan versi lainnya sebagai bagian dari paket proxy.

    Memiliki beberapa salinan dari JAR yang sama yang di-deploy dapat menyebabkan perilaku non-deterministik runtime karena potensi konflik ClassLoader.

  • Kebijakan Pemanggilan Java tidak berisi kode sebenarnya. Sebagai gantinya, kebijakan Java Keterangan merujuk 'Resource' Java dan menentukan Langkah dalam alur API tempat kode Java dieksekusi. Anda dapat upload Java JAR Anda melalui editor proxy UI Pengelolaan, atau Anda dapat menyertakannya dalam Direktori /resources/java di proxy API yang Anda kembangkan secara lokal.
  • Untuk operasi ringan, seperti panggilan API ke layanan jarak jauh, sebaiknya gunakan Kebijakan ServiceInfo. Lihat kebijakan Pemanggilan Layanan.
  • Untuk interaksi yang relatif sederhana dengan konten pesan, seperti memodifikasi atau mengekstrak Header HTTP, parameter, atau konten pesan, Apigee merekomendasikan penggunaan kebijakan JavaScript.