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 secara otomatis oleh kebijakan Apigee. Dalam kode Java, Anda dapat mengakses properti pesan (header, parameter kueri, konten) dan variabel alur dalam alur proxy. Jika Anda baru memulai kebijakan ini, lihat Cara membuat info Java.

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

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

Kapan

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

Tentang

Kebijakan Java Callout memungkinkan Anda mendapatkan dan menetapkan variabel alur, menjalankan logika kustom dan melakukan penanganan error, mengekstrak data dari permintaan atau respons, dan lainnya. Kebijakan ini memungkinkan Anda menerapkan perilaku kustom yang tidak tercakup dalam kebijakan Apigee standar lainnya.

Anda dapat memaketkan aplikasi Java dengan file JAR paket apa pun yang Anda perlukan. Perhatikan bahwa ada beberapa batasan terkait hal yang dapat Anda lakukan dengan Info Java. Hal ini tercantum di bawah di Pembatasan.

Sampel

Contoh sederhana

Cara membuat info Java

Mengambil properti dalam kode Java Anda

Elemen <Property> kebijakan memungkinkan Anda menentukan pasangan nama/nilai yang dapat diambil saat runtime dalam kode Java. Untuk contoh yang berfungsi dan menggunakan properti, lihat Cara menggunakan properti dalam info Java.

Gunakan atribut name elemen <Property> untuk menentukan nama yang akan digunakan untuk mengakses properti dari kode Java. Nilai 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 alur untuk mendapatkan 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 implementasi class Eksekusi sebagai berikut:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Menetapkan variabel alur dalam 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>

Atribut <JavaCallout>

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

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

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

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

Elemen <Properties>

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

Elemen <Property>

Menentukan properti yang dapat Anda akses dari kode Java saat runtime. Anda harus menentukan nilai string literal untuk setiap properti; Anda tidak dapat mereferensikan variabel alur dalam elemen ini. Untuk contoh kerja yang menggunakan properti, lihat Cara menggunakan properti dalam info 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.

Elemen <ResourceURL>

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

Anda dapat menyimpan file ini di cakupan proxy API (di bagian /apiproxy/resources/java dalam paket proxy API atau di bagian Skrip pada panel Navigator editor proxy API), atau di 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 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 dieksekusi.

Kode kerusakan Status HTTP Penyebab Perbaiki
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 error 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 error. 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 error.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] T/A Lihat string error.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] T/A Lihat string error.
NoResourceForURL Could not locate a resource with URL [string] T/A Lihat string error.

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 Matches "ExecutionError"
javacallout.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. javacallout.JC-GetUserData.failed = true

Contoh respons error

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

Contoh aturan error

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

Skema

Mengompilasi dan men-deploy

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

Pembatasan

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

  • Sebagian besar panggilan sistem tidak diizinkan. Misalnya, Anda tidak dapat membuat sistem file internal membaca atau menulis.
  • Akses ke jaringan melalui soket. Apigee membatasi akses ke alamat sitelocal, anylocal, loopback, dan linklocal.
  • Info tidak dapat mendapatkan informasi tentang proses saat ini, daftar proses, atau penggunaan CPU/memori di komputer. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas ke depan, Anda harus menghindari panggilan tersebut dalam kode Anda.
  • Ketergantungan pada library Java yang disertakan dengan Apigee tidak didukung. Library tersebut hanya untuk fungsi produk Apigee, dan tidak ada jaminan bahwa library akan tersedia dari rilis ke rilis.
  • Jangan gunakan io.apigee atau com.apigee sebagai nama paket di Info Java. Nama tersebut dicadangkan dan digunakan oleh modul Apigee lainnya.

Paket

Tempatkan JAR di proxy API pada /resources/java. Jika Java Callout Anda bergantung pada library pihak ketiga tambahan yang dikemas sebagai file JAR independen, tempatkan file JAR tersebut di direktori /resources/java juga untuk memastikan file tersebut dimuat dengan benar saat runtime.

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

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

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

Javadoc

Javadoc untuk menulis kode Java Callout disertakan di sini di GitHub. Anda harus meng-clone atau mendownload HTML ke sistem, lalu cukup buka file index.html di browser.

Catatan penggunaan dan praktik terbaik

  • Saat menggunakan beberapa info Java, pertimbangkan untuk mengupload JAR umum sebagai resource cakupan lingkungan. Praktik ini lebih efisien dibandingkan dengan mengemas JAR yang sama dengan beberapa paket proxy saat men-deploy ke lingkungan yang sama.
  • Hindari memaketkan dan men-deploy beberapa salinan atau versi file JAR yang sama ke lingkungan. 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.

    Men-deploy beberapa salinan JAR yang sama dapat menyebabkan perilaku non-deterministik saat runtime karena potensi konflik ClassLoader.

  • Kebijakan Java Callout tidak berisi kode aktual. Sebagai gantinya, kebijakan Java Callout mereferensikan 'resource' Java dan menentukan Langkah dalam alur API tempat kode Java dieksekusi. Anda dapat mengupload JAR Java melalui editor proxy UI Pengelolaan, atau 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 ServiceCallout. Lihat kebijakan Info Layanan.
  • Untuk interaksi yang relatif sederhana dengan konten pesan, seperti mengubah atau mengekstrak header, parameter, atau konten pesan HTTP, Apigee merekomendasikan penggunaan kebijakan JavaScript.