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

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Chú thích Java là gì?

Apigee Edge cung cấp một loạt chính sách giúp giải quyết các yêu cầu phổ biến về việc 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 API yêu cầu hành vi tuỳ chỉnh không được triển khai trong một chính sách chuẩn. Trong những trường hợp như vậy, Apigee cung cấp một số lựa chọn cho phép bạn viết tập lệnh hoặc viết mã cho hành vi API tuỳ chỉnh. Một phương pháp tiếp cận là triển khai hành vi mong muốn trong Java.

Đối với 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 proxy?

Chính sách chú thích Java cho phép bạn gọi mã Java từ trong 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 thực thi. Ví dụ: có các phương thức Java để lấy và đặt tiêu đề, tham số truy vấn, biến luồng cũng như 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 chú thích Java?

Hãy xem những tình huống mà chú thích Java hữu ích và những tình huống mà bạn nên xem xét 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 có thể có một số phương pháp thay thế mà bạn có thể sử dụng. 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 Chú thích dịch vụ. 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

Chú thích Java hỗ trợ các thao tác cơ bản sau:

  • Kiểm tra hoặc thao túng thông báo yêu cầu hoặc phản hồi
  • Lấy và đặt 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 thông tin về Sơ đồ giá trị khoá (KVM), hãy sử dụng chính sách KVM, chỉ định 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 chú thích Java.
  • Đang gọi cho các dịch vụ bên ngoài
  • Gửi lỗi
  • Sửa đổ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ể:

  • Yêu cầu hệ thống tệp nội bộ đọc hoặc ghi. Đ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.
  • Lấy 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 các cuộc gọi này không được hỗ trợ và có thể bị tắt bất cứ lúc nào. Hãy tránh thực hiện các lệnh gọi như vậy trong mã.

Đừng sử dụng hoặc dựa vào thư viện Java đi kèm với 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 đảm bảo rằng thư viện sẽ được cung cấp cho mọi bản phát hành. Nếu bạn dùng các thư viện như vậy, chỉ sử dụng chúng trong các bản minh hoạ không phải để phát hành chính thức.

Chú thích Hello Java (Xin chào Java)

Hãy cùng xem ví dụ về chú thích Java cơ bản. Trong ví dụ này, chúng ta tạo một proxy đơn giản với chú thích 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ể xảy ra:

  • Nếu bạn truyền tiêu đề "username" (tên người dùng) 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 ban đầu xuống

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

  1. Tải hoặc sao chép api-platform-samples vào hệ thống của bạn.
  2. Trong một thiết bị đầu cuối hoặc trình soạn thảo 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 sườn của lớp Java chính mà chúng ta sẽ triển khai. Bạn phải có các gói đã nhập đối với mã Chú thích Java của Edge. Các lớp này cung cấp các phương thức cho phép bạn truy cập vào ngữ cảnh thực thi proxy. Chúng tôi sẽ sớm hướng dẫn các bước biên dịch và triển khai mã này.
    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 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 vào một ví dụ theo ví dụ về Maven.

  1. Hãy đảm bảo rằng 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 vào 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 cho các tệp JAR mà bạn muốn triển khai bằng proxy.

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

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

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

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

    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 com/apigeesample/HelloJava.class.
  4. Tạo 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 cho các tệp JAR mà bạn muốn triển khai bằng 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

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

  1. cd sang 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ư được nêu trong thông tin tài khoản Apigee của bạn: tên người dùng (địa chỉ email 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 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 sử dụng Edge Private Cloud.
  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"

    Trả về "Hello, Will!

    Bạn có thể chỉnh sửa tập lệnh invoke.sh để đổ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ề "Hello, Customer!"

Giới thiệu về proxy

Hãy xem xét nhanh các chính sách được sử dụng trong proxy này. Hãy chú ý đến vị trí của chính sách trong luồng proxy và lý do tại sao.

Chính sách Chỉ định thông báo

Chính sách Chỉ định thông báo được đính kèm vào quy trình yêu cầu ProxyEndpoint. Phương thức này sao chép tiêu đề tên người dùng từ yêu cầu và gán tiêu đề đó cho phản hồi. Thao tác này cho phép chính sách Chú thích Java (được đính kèm với quy trình phản hồi) truy cập vào tiêu đề tên người dùng và tạo một nội dung phản hồi tuỳ chỉnh bằng cách sử dụ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 quy trình phản hồi. Điều này là do mã Java tuỳ chỉnh thực hiện các thay đổi đối vớ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 mà 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 chú thích 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 đưa vào tệp JAR được đóng gói và triển khai. Bạn có thể tải tệp 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 tệp này 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 proxy API đều phải triển khai Thực thi.
  • Chính sách về Chú thích Java không chứa mã thực. Thay vào đó, chính sách Chú thích Java sẽ tham chiếu đến một "tài nguyên" Java. Bạn phải đóng gói tài nguyên này trong tệp 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 Chú thích Java. Những mô-đun Apigee khác đã đặt trước và sử dụng.
  • Nếu Chú thích Java 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 tệp JAR độc lập, hãy đặt các tệp JAR đó vào thư mục /resources/java để đảm bảo rằng những tệp đó đượ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. Chỉ cần đặt chúng vào /resources/java là đủ.
  • Để biết thêm thông tin về cách tải các tệp JAR Java lên, hãy xem phần Tệp tài nguyên.