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 nhiều chính sách để giải quyết các yêu cầu chung để quản lý API như như bảo mật, chuyển đổi dữ liệu, quản lý lưu lượng truy cập, v.v.

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 theo 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 để bạn có thể viết tập lệnh hoặc mã tuỳ chỉnh hành vi API. Một phương pháp 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 Được hỗ trợ và các phiên bản phần mềm đượ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ừ bên trong luồng proxy thực thi. 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ác phương thức Java để lấy và đặt tiêu đề, truy vấn tham số, 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 chú thích Java?

Hãy xem xét các tình huống mà chú thích Java hữu ích và các tình huống 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 phương pháp thay thế

Trước khi sử dụng chú thích Java, xin lưu ý rằng có thể có nhiều phương pháp thay thế mà bạn có thể dùng thay thế. 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 về chú thích dịch vụ. Xem Chính sách về chú thích dịch vụ.
  • Đối với các tương tác tương đối đơn giản với nội dung thư, chẳng hạn như sửa đổi hoặc trích xuất Tiêu đề HTTP, tham số hoặc nội dung thông báo, 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 kiểm soát yêu cầu hoặc thông báo phản hồi
  • Lấy và thiết lập biến luồng. Bạn có thể sử dụng các phương thức Java để truy cập vào các biến luồng của Edge. Nếu bạn muốn truy cập vào thông tin Bản đồ 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 các biến luồng từ trong chú thích Java.
  • Gọi dịch vụ bên ngoài
  • Lỗi cách nâng cao
  • Thao túng thông báo lỗi và mã trạng thái

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

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

  • Giúp 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 để đọc/ghi vào hệ thống tệp nội bộ; Tuy nhiên, bạn có thể thực hiện cuộc gọi từ xa.
  • 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ớ 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ị tắt chủ động tại bất cứ lúc nào. Hãy tránh thực hiện những lệnh gọi như vậy trong mã nguồn của bạn.

Đừ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 sản phẩm Edge và không thể đảm bảo rằng sẽ có thư viện từ bản phát hành này sang bản phát hành khác. Nếu bạn dùng các thư viện như vậy, hãy dùng chúng trong các bản minh hoạ không sản xuất .

Chú thích Java xin chào

Hãy cùng xem một ví dụ cơ bản về chú thích Java Hello world (Xin chào thế giới). Trong ví dụ này, chúng tôi tạo một proxy đơn giản với chú thích Java trả về lời chào "hello world" của bạn. Proxy có thể trả về một kết quả có thể có 2 đáp án:

  • Nếu bạn nhập "tên người dùng" tiêu đề có "tên" thì proxy sẽ trả về:

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

    "Hello, Guest!"

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

Nói một cách đơn giản, chúng tôi có một dự án cơ bản được chuẩn bị cho bạn trên GitHub trong chương trình Apigee Kho lưu trữ api-platform-samples.

  1. Tải xuống hoặc sao chép api-platform-samples vào hệ thống của bạn.
  2. Trong cửa sổ dòng lệnh 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 cơ bản của lớp Java chính mà chúng ta sẽ triển khai. Tham số đã nhập Cần có gói để sử dụng mã Chú thích Java của Edge. Các lớp này cung cấp phương thức cho phép bạn để truy cập ngữ cảnh thực thi proxy. Chúng tôi sẽ hướng dẫn từng 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 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 ta sẽ đưa vào một ví dụ sau ví dụ 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 cài đặt đoạn mã bắt buộc Các phần phụ thuộc JAR trong kho lưu trữ Maven cục bộ của bạn.
  3. cd vào thư mục java-hello/callout.
  4. Thực thi Maven:

    mvn clean package
  5. Nếu bạn muốn, hãy xác minh rằng tệp JAR edge-custom-policy-java-hello.jar là đã sao chép vào java-hello/apiproxy/resources/java. Đây là vị trí bắt buộc cho 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 đã tự động tạo tệp Java JAR 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 nội dung nào đó tương tự như mã sau (từ thư mục java-hello). Bắt buộc Các tệp JAR được cung cấp cho bạn trong thư mục java-hello/lib.

  1. đĩa 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:

    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 được biên dịch trong Thư mục apiproxy/resources/java. Đây là vị trí bắt buộc cho 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. Nhưng trước khi chạy quảng cáo, 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 thực hiện, hãy mở tệp ../../setup/setenv.sh rồi chỉnh sửa mã này được thể hiệ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 sử dụng để tạo API các cuộc gọi quản lý. Ví dụ: đối với Cloud Cloud, 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 bằ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 một lệnh cURL có dạng như sau:

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

    Nút này 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 để xóa tiêu đề, sau đó lệnh trả về "Xin chào, khách!"

Giới thiệu về proxy

Hãy cùng kiểm tra nhanh các chính sách được sử dụng trong proxy này. Chú ý đến vị trí của các chính sách được đặt trong luồng proxy và tại sao.

Chính sách Chỉ định tin nhắn

Chính sách Chỉ định tin nhắn được đính kèm với quy trình yêu cầu ProxyEndpoint. Nó sao chép tiêu đề tên người dùng trong 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ào quy trình 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 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 thông báo và tiêu đề phản hồi. ClassName của chính sách phần tử chỉ định lớp chính được thực thi theo chính sách. Phần tử ResourceURL là phần tử 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

Sau đây là những điều quan trọng cần lưu ý về việc triển khai chú thích Java:

  • Nhập các lớp từ com.apigee.flow.execution và com.apigee.flow.message gói. 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 tệp JAR Java lên thông qua proxy Management UI trình chỉnh sửa hoặc bạn có thể đưa tệp này vào thư mục /resources/java trong proxy API mà bạn phát triển ở địa phương.
  • Triển khai giao diện Thực thi. Mọi mã Java được thực thi trong proxy API đều phải thực thi.
  • Chính sách 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 "resource" Java mà bạn phải đóng gói trong tệp JAR.
  • Tên gói cần tránh: Không sử dụng io.apigee hoặc com.apigee làm tên gói trong Chú thích Java. Những cookie này dành riêng và được sử dụng bởi các mô-đun Apigee khác.
  • Nếu Chú thích Java phụ thuộc vào thư viện bổ sung của bên thứ ba được đóng gói dưới dạng JAR độc lập rồi đặt các tệp JAR đó trong thư mục /resources/java để đảm bảo các tệp được tải chính xác 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. Đưa 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.