Cách tạo chú thích Java

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Chú thích Java là gì?

Apigee Edge cung cấp một loạt chính sách đáp ứng các yêu cầu phổ biến về quản lý API, chẳng hạn như bảo mật, chuyển đổi dữ liệu, quản lý lưu lượng truy cập và các yêu cầu khác.

Tuy nhiên, có một số trường hợp mà API của bạn yêu cầu hành vi tuỳ chỉnh chưa được triển khai trong một chính sách tiêu chuẩn. Trong những trường hợp này, Apigee cung cấp một số lựa chọn cho phép bạn viết kịch bản hoặc mã hoá hành vi API tuỳ chỉnh. Một cách tiếp cận là triển khai hành vi mong muốn trong Java.

Để biết các phiên bản Java được hỗ trợ, hãy xem phần Phần mềm được hỗ trợ và các phiên bản được hỗ trợ.

Làm cách nào để sử dụng mã Java trong một proxy?

Chính sách gọi Java cho phép bạn gọi mã Java từ bên trong một luồng proxy đang thực thi. Mã Java của bạn cần triển khai một số giao diện Java dành riêng cho Edge để cho phép mã tương tác với proxy đang thực thi. Ví dụ: các phương thức Java tồn tại để nhận và đặt tiêu đề, tham số truy vấn, biến luồng và các thực thể khác trong ngữ cảnh luồng hiện tại của proxy.

Khi nào tôi nên sử dụng lệnh gọi Java?

Hãy xem xét những trường hợp mà chú thích Java hữu ích và những trường hợp mà bạn nên cân nhắc các phương pháp khác.

Trước tiên, hãy cân nhắc các phương pháp thay thế

Trước khi sử dụng chú thích Java, hãy lưu ý rằng bạn có thể sử dụng các phương pháp thay thế khác. Ví dụ:

  • Đối với các thao tác đơn giản, chẳng hạn như lệnh gọi API HTTP đến các dịch vụ từ xa, hãy cân nhắc sử dụng chính sách ServiceCallout. Xem Chính sách về chú thích dịch vụ.
  • Đối với các hoạt động tương tác tương đối đơn giản với nội dung thông báo, chẳng hạn như sửa đổi hoặc trích xuất tiêu đề, tham số hoặc nội dung thông báo HTTP, bạn có thể sử dụng ngôn ngữ JavaScript hoặc Python.

Những việc bạn có thể làm trong mã Java

Lệnh gọi Java hỗ trợ các thao tác cơ bản sau:

  • Kiểm tra hoặc thao tác với thông báo yêu cầu hoặc phản hồi
  • Nhận và thiết lập các biến luồng. Bạn có thể dùng các phương thức Java để truy cập vào các biến luồng Edge. Nếu muốn truy cập vào thông tin Key Value Map (KVM), hãy sử dụng chính sách KVM, chỉ định các giá trị KVM cho các biến luồng, sau đó bạn có thể truy cập vào các biến luồng từ trong lệnh gọi Java.
  • Gọi dịch vụ bên ngoài
  • Báo cáo lỗi
  • Thao tác với thông báo lỗi và mã trạng thái

Những việc bạn không thể làm trong mã Java

Hầu hết các lệnh gọi hệ thống đều không được phép. Bạn không thể:

  • Thực hiện các thao tác đọc hoặc ghi hệ thống tệp nội bộ. Điều này có nghĩa là bạn không thể sử dụng bất kỳ gói Java nào để đọc/ghi vào hệ thống tệp nội bộ; tuy nhiên, bạn có thể thực hiện các lệnh gọi từ xa bên ngoài.
  • Nhận thông tin về quy trình hiện tại, danh sách quy trình hoặc mức sử dụng CPU/bộ nhớ trên máy.
  • Truy cập vào mã nguồn trong "expressions-1.0.0.jar" và "message-flow-1.0.0.jar".

Mặc dù một số cuộc gọi như vậy có thể hoạt động, nhưng chúng không được hỗ trợ và có thể bị vô hiệu hoá bất cứ lúc nào. Tránh thực hiện những lệnh gọi như vậy trong mã của bạn.

Không sử dụng hoặc dựa vào các thư viện Java có trong Apigee Edge. Những thư viện đó chỉ dành cho chức năng của sản phẩm Edge và không có gì đảm bảo rằng một thư viện sẽ có sẵn từ bản phát hành này sang bản phát hành khác. Nếu bạn sử dụng các thư viện như vậy, hãy chỉ sử dụng chúng trong các bản minh hoạ không phải bản phát hành công khai.

Chú thích Hello Java

Hãy xem qua một ví dụ cơ bản về chú thích Java "hello world". Trong ví dụ này, chúng ta tạo một proxy đơn giản có lệnh gọi Java trả về phản hồi "xin chào thế giới". Proxy có thể trả về một trong hai phản hồi có thể có:

  • Nếu bạn truyền một tiêu đề "username" có giá trị "name", thì proxy sẽ trả về:

    Hello, <name>!
  • Nếu bạn bỏ qua tiêu đề, proxy sẽ chỉ trả về:

    "Hello, Guest!"

Tải dự án khởi đầu xuống

Để đơn giản hoá, chúng tôi đã chuẩn bị một dự án cơ bản cho bạn trên GitHub trong kho lưu trữ api-platform-samples của Apigee.

  1. Tải xuống hoặc sao chép api-platform-samples vào hệ thống của bạn.
  2. Trong một cửa sổ dòng lệnh hoặc trình chỉnh sửa mã mà bạn chọn, hãy chuyển đến dự án api-platform-samples/doc-samples/java-hello.

Viết mã Java

  1. Mở tệp nguồn Java: java-hello/callout/src/main/java/HelloJava.java. Tệp này là phiên bản khung của lớp Java chính mà chúng ta sẽ triển khai. Các gói được nhập là bắt buộc đối với mã Lời gọi Java Edge. Các lớp này cung cấp những phương thức cho phép bạn truy cập vào ngữ cảnh thực thi của proxy. Chúng ta sẽ xem xét các bước để biên dịch và triển khai mã này trong thời gian ngắn.
    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. Thay thế dòng được nhận xét // Your code here bằng đoạn mã sau:

    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!");
}
  3. Lưu tệp.


Biên dịch mã bằng Maven

Dự án được thiết lập để bạn có thể biên dịch bằng Maven. Nếu bạn muốn sử dụng javac, chúng tôi sẽ đưa ra một ví dụ sau ví dụ về Maven.

  1. Đảm bảo bạn đã cài đặt Maven:

    mvn -version
  2. Thực thi tập lệnh java-hello/buildsetup.sh. Tập lệnh này sẽ cài đặt các phần phụ thuộc JAR bắt buộc trong kho lưu trữ Maven cục bộ.
  3. cd đến thư mục java-hello/callout.
  4. Thực thi Maven:

    mvn clean package
  5. Nếu muốn, hãy xác minh rằng tệp JAR edge-custom-policy-java-hello.jar đã được sao chép vào java-hello/apiproxy/resources/java. Đây là vị trí bắt buộc đối với các tệp JAR mà bạn muốn triển khai bằng một proxy.

Biên dịch bằng javac (không bắt buộc)

Trong phần trước, bạn tự động tạo tệp JAR Java cần thiết bằng một lệnh Maven. Ngoài ra, nếu muốn sử dụng javac để biên dịch mã, bạn có thể làm việc gì đó tương tự như sau (từ thư mục java-hello). Các tệp JAR bắt buộc được cung cấp cho bạn trong thư mục java-hello/lib.

  1. cd đến api-platform-samples/doc-samples/java-hello.
  2. Đảm bảo rằng bạn có javac trong đường dẫn của mình.

    javac -version
  3. Thực thi lệnh javac sau:

    javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java
     Thao tác này sẽ tạo ra com/apigeesample/HelloJava.class.
  4. Tạo một tệp JAR chứa lớp đã biên dịch trong thư mục apiproxy/resources/java. Đây là vị trí bắt buộc đối với các tệp JAR mà bạn muốn triển khai bằng một proxy. Bạn có thể thực hiện việc này bằng cách chạy lệnh sau trong thư mục java-hello (đừng quên dấu chấm ở cuối).

    jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .

Triển khai và gọi proxy

Một tập lệnh triển khai được cung cấp trong thư mục ./java-hello. Nhưng trước khi chạy, bạn cần thiết lập nhanh.

  1. cd đến api-platform-samples/doc-samples/java-hello
  2. Nếu bạn chưa làm việc này, hãy mở tệp ../../setup/setenv.sh và chỉnh sửa tệp đó như hướng dẫn bằng thông tin tài khoản Apigee của bạn: tên người dùng (địa chỉ email được liên kết với tài khoản của bạn), tên tổ chức và miền mà bạn dùng để thực hiện các lệnh gọi quản lý API. Ví dụ: đối với đám mây Edge, miền là https://api.enterprise.apigee.com; tuy nhiên, miền của bạn có thể khác nếu bạn đang sử dụng Đám mây riêng tư Edge.
  3. Lưu tệp setenv.sh.
  4. Thực thi tập lệnh triển khai:

    ./deploy.sh
  5. Nếu triển khai thành công, hãy thực thi tập lệnh gọi:

    ./invoke.sh

    Tập lệnh gọi sẽ gọi một lệnh cURL có dạng như sau:

    curl  http://$org-$env.$api_domain/java-hello -H "username:Will"

    Kết quả trả về là "Xin chào, Will!

    Bạn có thể chỉnh sửa tập lệnh invoke.sh để thay đổi tên, hoặc nếu bạn thay đổi lệnh gọi cURL để xoá tiêu đề, thì lệnh sẽ trả về "Xin chào, Khách!"

Giới thiệu về proxy

Hãy xem nhanh các chính sách được dùng trong proxy này. Chú ý đến vị trí của các chính sách trong quy trình proxy và lý do.

Chính sách Assign message (Chỉ định tin nhắn)

Một chính sách Assign message được đính kèm vào luồng yêu cầu ProxyEndpoint. Thao tác này sẽ sao chép tiêu đề tên người dùng từ yêu cầu và chỉ định tiêu đề đó cho phản hồi. Thao tác này cho phép chính sách Lệnh gọi Java (được đính kèm vào luồng phản hồi) truy cập vào tiêu đề tên người dùng và tạo nội dung phản hồi tuỳ chỉnh bằng giá trị của tiêu đề đó.

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

Chính sách chú thích Java

Chính sách chú thích Java được đính kèm vào luồng phản hồi. Điều này là do mã Java tuỳ chỉnh sẽ thay đổi tiêu đề và thông báo phản hồi. Phần tử ClassName của chính sách chỉ định lớp chính do chính sách thực thi. Phần tử ResourceURL là tên của tệp JAR mà bạn đã tạo và thêm vào thư mục resources/java của proxy.

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

Những điều bạn cần biết về chú thích Java

Những điều quan trọng cần lưu ý về việc triển khai một lệnh gọi Java là:

  • Nhập các lớp từ gói com.apigee.flow.execution và com.apigee.flow.message. Các gói này phải có trong tệp JAR được đóng gói và triển khai. Bạn có thể tải JAR Java lên thông qua trình chỉnh sửa proxy Giao diện người dùng quản lý hoặc bạn có thể đưa JAR Java vào thư mục /resources/java trong các proxy API mà bạn phát triển cục bộ.
  • Triển khai giao diện Thực thi. Mọi mã Java được thực thi trong một proxy API đều phải triển khai Execution.
  • Chính sách Lời gọi Java không chứa mã thực tế. Thay vào đó, chính sách Lệnh gọi Java sẽ tham chiếu đến một "tài nguyên" Java mà bạn phải đóng gói trong một JAR.
  • Tên gói cần tránh: Không dùng io.apigee hoặc com.apigee làm tên gói trong Java Callout. Những mô-đun này được các mô-đun Apigee khác dành riêng và sử dụng.
  • Nếu Java Callout của bạn dựa vào các thư viện bổ sung của bên thứ ba được đóng gói dưới dạng các tệp JAR độc lập, thì hãy đặt các tệp JAR đó vào thư mục /resources/java để đảm bảo rằng chúng được tải đúng cách trong thời gian chạy.
  • Nếu có nhiều tệp JAR, bạn chỉ cần thêm các tệp đó làm tài nguyên bổ sung. Bạn không cần sửa đổi cấu hình chính sách để tham chiếu đến các tệp JAR bổ sung. Bạn chỉ cần đặt chúng vào /resources/java.
  • Để biết thêm thông tin về cách tải JAR Java lên, hãy xem phần Tệp tài nguyên.