Cara membuat info Java

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Apa yang dimaksud dengan pemanggilan Java?

Apigee menyediakan berbagai kebijakan yang memenuhi persyaratan pengelolaan API umum seperti keamanan, transformasi data, pengelolaan traffic, dan lainnya.

Namun, ada beberapa kasus saat API Anda memerlukan perilaku kustom yang tidak diterapkan dalam kebijakan standar. Dalam kasus ini, Apigee menyediakan beberapa opsi yang memungkinkan Anda membuat skrip atau kode perilaku API yang disesuaikan. Salah satu pendekatannya adalah menerapkan perilaku yang diinginkan di Java.

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

Catatan: Penting: Jika Anda mengembangkan kebijakan Java Callout, Anda perlu mengetahui kebijakan izin mana yang berlaku di JVM Apigee dan pengaruhnya terhadap kode Anda. Lihat Referensi izin Java. .

Bagaimana cara menggunakan kode Java di proxy?

Kebijakan info Java memungkinkan Anda memanggil kode Java dari dalam alur proxy yang dieksekusi. Kode Java Anda harus mengimplementasikan antarmuka Java khusus Apigee tertentu yang memungkinkan kode berinteraksi dengan proxy yang dieksekusi. Misalnya, metode Java ada untuk mendapatkan dan menetapkan header, parameter kueri, variabel alur, dan entity lainnya dalam konteks alur proxy saat ini.

Kapan saya harus menggunakan info Java?

Mari kita lihat situasi saat info Java berguna, dan situasi saat Anda harus mempertimbangkan pendekatan lain.

Pertama, pertimbangkan pendekatan alternatif

Sebelum menggunakan info Java, perhatikan bahwa mungkin ada pendekatan alternatif yang dapat Anda gunakan sebagai gantinya. Contoh:

• Untuk operasi ringan, seperti panggilan HTTP API ke layanan jarak jauh, pertimbangkan untuk menggunakan kebijakan ServiceCallout. Lihat kebijakan Info Layanan.
• Untuk interaksi yang relatif sederhana dengan konten pesan, seperti mengubah atau mengekstrak header, parameter, atau konten pesan HTTP, Anda dapat menggunakan kebijakan JavaScript atau PythonScript.

Yang dapat Anda lakukan dalam kode Java

Info Java mendukung operasi dasar berikut:

• Memeriksa atau memanipulasi pesan permintaan atau respons
• Mendapatkan dan menetapkan variabel alur. Anda dapat menggunakan metode Java untuk mengakses variabel alur Apigee. Jika ingin mengakses informasi Peta Nilai Kunci (KVM), gunakan kebijakan KVM, tetapkan nilai KVM ke variabel alur, lalu Anda dapat mengakses variabel alur dari dalam info Java.
• Memanggil layanan eksternal
• Mengajukan kesalahan
• Melakukan manipulasi pada pesan error dan kode status

Hal yang tidak dapat Anda lakukan dalam kode Java

Sebagian besar panggilan sistem tidak diizinkan. Anda tidak dapat:

• Membuat sistem file internal membaca atau menulis. Artinya, Anda tidak dapat menggunakan paket Java apa pun untuk membaca/menulis ke sistem file internal; namun, Anda dapat melakukan panggilan jarak jauh eksternal.
• Dapatkan informasi tentang proses saat ini, daftar proses, atau penggunaan CPU/memori di mesin.
• Akses kode sumber di expressions-1.0.0.jar dan message-flow-1.0.0.jar.

Meskipun beberapa panggilan tersebut mungkin berfungsi, panggilan tersebut tidak didukung dan dapat dinonaktifkan secara aktif kapan saja. Hindari melakukan panggilan tersebut dalam kode Anda.

Jangan gunakan atau bergantung pada library Java yang disertakan dengan Apigee. Library tersebut hanya untuk fungsi produk Apigee, dan tidak ada jaminan bahwa library akan tersedia dari rilis ke rilis. Jika Anda menggunakan library tersebut, gunakan hanya dalam demonstrasi non-produksi.

Info Hello Java

Mari kita lihat contoh info Java hello world dasar. Dalam contoh ini, kita membuat proxy sederhana dengan info Java yang menampilkan respons "halo dunia". Proxy dapat menampilkan salah satu dari dua kemungkinan respons:

• Jika Anda meneruskan header "username" dengan nilai "name", proxy akan menampilkan:
  
  

  Hello, <name>!

• Jika Anda menghapus header, proxy hanya akan menampilkan:
  
  

  "Hello, Guest!"

Mendownload project awal

Untuk mempermudah, kami telah menyiapkan project dasar untuk Anda di GitHub di repositori api-platform-samples Apigee.

1. Download atau clone api-platform-samples ke sistem Anda. Jika Anda sudah memiliki api-platform-samples di sistem, lakukan pull untuk memastikan Anda memiliki versi terbaru.
2. Di terminal atau editor kode pilihan Anda, buka project api-platform-samples/doc-samples/java-hello.

Menulis kode Java

1. Buka file sumber Java: java-hello/callout/src/main/java/HelloJava.java. File ini adalah versi kerangka dari class Java utama yang akan kita terapkan. Paket yang diimpor diperlukan untuk kode Callout Java Apigee. Class ini menyediakan metode yang memungkinkan Anda mengakses konteks eksekusi proxy. Kami akan membahas langkah-langkah untuk mengompilasi dan men-deploy kode ini dalam waktu dekat.
   

   package com.apigeesample;
   
   import com.apigee.flow.execution.ExecutionContext;
   import com.apigee.flow.execution.ExecutionResult;
   import com.apigee.flow.execution.spi.Execution;
   import com.apigee.flow.message.MessageContext;
   
   
   public class HelloJava implements Execution {
   
           public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {
   
                   try {
   
                           // Your code here.
   
               return ExecutionResult.SUCCESS;
   
                   } catch (Exception e) {
                           return ExecutionResult.ABORT;
                   }
           }
   
   }

2. Ganti baris yang dikomentari // Your code here dengan kode berikut:
   
   

   String name = messageContext.getMessage().getHeader("username");
   
   if (name != null && name.length()>0) {
           messageContext.getMessage().setContent("Hello, " + name + "!");
           messageContext.getMessage().removeHeader("username");
   } else {
           messageContext.getMessage().setContent("Hello, Guest!");
   }

   Catatan: Catatan: Objek MessageContext memungkinkan Anda mengakses entity di dalam alur tempat kebijakan Java Callout dijalankan. Misalnya, kebijakan Java Callout dilampirkan ke alur Respons Endpoint Proxy. Kode yang tercantum di atas mendapatkan objek Pesan HTTP untuk konteks alur tersebut. Objek Message, pada gilirannya, memberi Anda akses ke header, parameter kueri, konten isi, dan variabel alur.
3. Simpan file.

Mengompilasi kode dengan Maven

Catatan: File POM dan konfigurasi untuk kompilasi Maven seharusnya berfungsi, tetapi ditawarkan di repositori Git hanya sebagai contoh. Anda mungkin perlu melakukan penyesuaian untuk lingkungan Anda. Jika membuat perubahan pada kode contoh, Anda mungkin juga perlu menyesuaikan konfigurasi Maven.

1. Pastikan Anda telah menginstal Maven:
   
   

   mvn -version

2. Instal dependensi JAR yang diperlukan di repo Maven lokal Anda menggunakan salah satu metode berikut:
   • Tambahkan cuplikan berikut ke file pom.xml untuk mendownload dependensi JAR yang diperlukan dari Artifact Registry:

     <repositories>
       <repository>
         <id>artifact-registry</id>
         <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
       </repository>
     </repositories>
     
     <dependencies>
       <dependency>
         <groupId>com.apigee.gateway.libraries</groupId>
         <artifactId>message-flow</artifactId>
         <version>1.0.0</version>
         <scope>compile</scope>
         <type>jar</type>
       </dependency>
       <dependency>
         <groupId>com.apigee.infra.libraries</groupId>
         <artifactId>expressions</artifactId>
         <version>1.0.0</version>
         <scope>compile</scope>
         <type>jar</type>
       </dependency>
     </dependencies>

   • Gunakan panggilan curl berikut untuk mendownload dependensi JAR yang diperlukan dari Artifact Registry:

     curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
             

     curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
             

   • Jalankan skrip java-hello/buildsetup.sh. Skrip ini mendownload dependensi JAR yang diperlukan dari repositori GitHub Apigee.
3. cd ke direktori java-hello/callout.
4. Jalankan Maven:
   
   

   mvn clean package

   Catatan: Jika Anda mendapatkan error Maven, pastikan Anda berada di direktori java-hello/callout.
5. Jika mau, verifikasi bahwa file JAR edge-custom-policy-java-hello.jar telah disalin ke java-hello/apiproxy/resources/java. Ini adalah lokasi yang diperlukan untuk file JAR yang ingin Anda deploy dengan proxy.

Men-deploy dan memanggil proxy

Ikuti langkah-langkah berikut untuk men-deploy dan menguji proxy API:

1. Ubah ke direktori java-hello.
2. Zip paket proxy API:

   zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

3. Cara termudah untuk men-deploy proxy adalah dengan memaketkannya dalam file zip dan mengupload paket proxy ke lingkungan di organisasi Apigee Anda. Lihat Membuat proxy API. Pastikan untuk menggunakan opsi Upload Proxy Bundle. Lihat juga Tips dan trik untuk mengupload proxy API dalam paket proxy di komunitas Apigee.
4. Saat proxy di-deploy, coba panggil:
   

   curl  https://$HOSTNAME/java-hello -H "username:Will"

   Yang akan menampilkan "Halo, Will!

Tentang proxy

Mari kita pelajari kebijakan yang digunakan di proxy ini dengan cepat. Perhatikan posisi kebijakan dalam alur proxy dan alasannya.

Kebijakan Tetapkan pesan

Kebijakan pesan Tetapkan dilampirkan ke alur permintaan ProxyEndpoint. Fungsi ini menyalin header nama pengguna dari permintaan dan menetapkannya ke respons. Operasi ini memungkinkan kebijakan Java Callout, yang dilampirkan ke alur respons, untuk mengakses header nama pengguna dan membuat isi respons kustom menggunakan nilai header tersebut.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Kebijakan info Java

Kebijakan callout Java dilampirkan ke alur respons. Hal ini karena kode Java kustom membuat perubahan pada header dan pesan respons. Elemen ClassName kebijakan menentukan class utama yang dijalankan oleh kebijakan. Elemen ResourceURL adalah nama file JAR yang Anda build dan tambahkan ke direktori resources/java proxy.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

Yang perlu Anda ketahui tentang pemanggilan Java

Hal-hal penting yang perlu diperhatikan tentang penerapan info Java adalah:

• Mengimpor class dari paket com.apigee.flow.execution dan com.apigee.flow.message. Paket ini harus disertakan dalam file JAR yang dipaketkan dan di-deploy. Anda dapat mengupload JAR Java melalui editor proxy UI Pengelolaan, atau Anda dapat menyertakannya dalam direktori /resources/java di proxy API yang Anda kembangkan secara lokal.
• Mengimplementasikan antarmuka Eksekusi. Setiap kode Java yang dieksekusi dalam proxy API harus menerapkan Eksekusi.
• Kebijakan Java Callout tidak berisi kode aktual. Sebagai gantinya, kebijakan Java Callout mereferensikan 'resource' Java, yang harus Anda paketkan dalam JAR.
• Nama paket yang harus dihindari: Jangan gunakan io.apigee atau com.apigee sebagai nama paket di Java Callouts. Modul tersebut dicadangkan dan digunakan oleh modul Apigee lainnya.
• Jika Info Java Anda mengandalkan 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 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 tambahan tentang cara mengupload JAR Java, lihat File resource.