Kebijakan JavaCallout

Kebijakan yang dapat diperluas

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan JavaCallout memungkinkan Anda menggunakan Java untuk menerapkan perilaku kustom yang tidak disertakan secara langsung oleh kebijakan Apigee. Dalam kode Java, Anda dapat mengakses properti pesan (header, parameter kueri, konten), mendapatkan dan menyetel variabel alur, menjalankan logika kustom, dan melakukan penanganan error, mengekstrak data dari permintaan atau respons, dan lainnya. Jika Anda baru memulai kebijakan ini, lihat Cara membuat panggilan Java.

Anda dapat mengemas aplikasi Java dengan file JAR paket apa pun yang Anda butuhkan. Perhatikan bahwa ada beberapa batasan terkait hal yang dapat Anda lakukan dengan JavaCallout. Pembatasan ini tercantum dalam Pembatasan.

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 mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Sampel

Contoh umum

Untuk contoh sederhana menggunakan callout Java, lihat Cara membuat callout Java.

Untuk mempelajari cara menyetel variabel alur dalam kode Java, lihat postingan Komunitas Apigee tentang men-debug panggilan Java.

Mengambil properti dalam kode Java Anda

Contoh ini menunjukkan cara menggunakan 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.

Konfigurasi memerlukan dua bagian:

  • Konfigurasi 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>
</JavaCallout>
  • Dalam kode Java Anda, terapkan konstruktor berikut pada class Execution:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

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

 T/A Wajib
continueOnError

Disetel ke false untuk menampilkan error saat kebijakan gagal. Hal ini adalah perilaku yang diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur berlanjut meskipun kebijakan gagal. Lihat juga:

 false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir pada alur.

 true 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 JavaCallout berjalan. class harus disertakan dalam file JAR yang ditentukan oleh <ResourceURL>. Lihat juga Cara membuat panggilan 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 kebijakan JavaCallout.

<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 JavaCallout dijalankan.

Anda dapat menyimpan file ini di cakupan proxy API (di bagian /apiproxy/resources/java dalam paket proxy API atau di bagian Skrip di 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

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
steps.javacallout.ExecutionError 500 当 Java 代码执行 JavaCallout policy 时抛出异常或返回 null 时发生。

部署错误

部署包含政策的代理时，可能会出现此类错误。

错误名称 故障字符串 HTTP 状态 发生的条件
ResourceDoesNotExist Resource with name [name] and type [type] does not exist 不适用 <ResourceURL> 元素中指定的文件不存在。
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] 不适用 在 <ClassName> 元素中指定的类文件不在 jar 中。
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] 不适用 请参阅故障字符串。支持的 Java 版本包括：Oracle JDK 7/8 和 OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] 不适用 请参阅故障字符串。
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] 不适用 请参阅故障字符串。
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] 不适用 请参阅故障字符串。
NoResourceForURL Could not locate a resource with URL [string] 不适用 请参阅故障字符串。

故障变量

此政策触发错误时设置这些变量。如需了解详情，请参阅您需要了解的有关政策错误的信息。

变量 位置 示例
fault.name="fault_name" fault_name 是故障名称，如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name 是抛出故障的政策的用户指定名称。 javacallout.JC-GetUserData.failed = true

错误响应示例

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

故障规则示例

<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 panggilan Java.

Pembatasan

Berikut adalah batasan yang perlu Anda pertimbangkan saat menulis kode panggilan Java:

  • Sebagian besar panggilan sistem tidak diizinkan. Misalnya, Anda tidak dapat melakukan operasi baca atau tulis sistem file internal.
  • Akses ke jaringan melalui soket. Apigee membatasi akses ke alamat sitelocal, anylocal, loopback, dan linklocal.
  • Callout tidak dapat memperoleh informasi tentang proses saat ini, daftar proses, atau penggunaan CPU/memori di mesin. Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Untuk kompatibilitas ke depan, Anda sebaiknya menghindari melakukan panggilan tersebut dalam kode Anda.
  • Penggunaan 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 dalam Java Callout. Nama tersebut dicadangkan dan digunakan oleh modul Apigee lainnya.

Paket

Tempatkan JAR di proxy API dalam /resources/java. Jika kode JavaCallout 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 mengetahui informasi tentang cara mengupload JAR Java, lihat File resource.

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

Javadoc

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

Catatan penggunaan dan praktik terbaik

  • Saat bekerja dengan beberapa kebijakan JavaCallout, pertimbangkan untuk mengupload JAR umum sebagai resource cakupan lingkungan. Praktik ini lebih efisien dibandingkan mengemas JAR yang sama dengan beberapa paket proxy saat men-deploy ke lingkungan yang sama.
  • Hindari mengemas 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.

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

  • Kebijakan JavaCallout tidak berisi kode sebenarnya. Sebagai gantinya, kebijakan mereferensikan 'resource' Java dan menentukan Langkah dalam alur API tempat kode Java dijalankan. Anda dapat mengupload JAR Java melalui editor proxy UI Pengelolaan, atau menyertakannya di direktori /resources/java dalam proxy API yang Anda kembangkan secara lokal.
  • Untuk operasi ringan, seperti panggilan API ke layanan jarak jauh, sebaiknya gunakan kebijakan ServiceCallout. Lihat kebijakan Service Callout.
  • Untuk interaksi yang relatif sederhana dengan konten pesan, seperti mengubah atau mengekstrak header HTTP, parameter, atau konten pesan, Apigee merekomendasikan penggunaan kebijakan JavaScript.