Chính sách về 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

Nội dung

Cho phép bạn sử dụng Java để triển khai hành vi tuỳ chỉnh không được đưa vào sẵn trong các chính sách của Apigee. Trong mã Java, bạn có thể truy cập vào các thuộc tính của thông báo (tiêu đề, tham số truy vấn, nội dung) và các biến luồng trong luồng proxy. Nếu bạn mới bắt đầu tìm hiểu chính sách này, hãy xem bài viết Cách tạo chú thích 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ợ.

Thời gian

Để biết các nguyên tắc, hãy xem phần "Khi nào tôi nên sử dụng chú thích Java?" trong bài viết Cách tạo chú thích Java.

Giới thiệu

Chính sách Chú thích Java cho phép bạn nhận và đặt các biến luồng, thực thi logic tuỳ chỉnh và thực hiện việc xử lý lỗi, trích xuất dữ liệu từ các yêu cầu hoặc phản hồi, v.v. Chính sách này cho phép bạn triển khai hành vi tuỳ chỉnh không thuộc phạm vi của bất kỳ chính sách tiêu chuẩn nào khác của Edge.

Bạn có thể đóng gói ứng dụng Java của mình bằng bất kỳ tệp JAR gói nào bạn cần. Xin lưu ý rằng có một số hạn chế đối với những việc bạn có thể làm với Lệnh gọi Java. Những hạn chế này được liệt kê dưới đây trong phần Hạn chế.

Mẫu

Ví dụ đơn giản

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

Truy xuất các thuộc tính trong mã Java

Phần tử <Property> của chính sách cho phép bạn chỉ định một cặp tên/giá trị mà bạn có thể truy xuất trong thời gian chạy trong mã Java. Để xem ví dụ minh hoạ cách sử dụng các thuộc tính, hãy xem bài viết Cách sử dụng các thuộc tính trong chú thích Java.

Sử dụng thuộc tính name của phần tử <Property> để chỉ định tên dùng để truy cập vào thuộc tính từ mã Java. Giá trị của phần tử <Property> (giá trị giữa thẻ mở và thẻ đóng) là giá trị mà mã Java sẽ nhận được. Giá trị phải là một chuỗi; bạn không thể tham chiếu đến một biến luồng để lấy giá trị.

  • Thiết lập tài sản. Ở đây, giá trị thuộc tính là tên biến 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>
</Javascript>
  • Trong mã Java, hãy triển khai hàm khởi tạo sau đây trên quá trình triển khai lớp Thực thi như sau:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

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

Đặt các biến luồng trong mã Java

Để biết nội dung mô tả rõ ràng về cách thiết lập các biến trong ngữ cảnh thông báo (biến luồng) trong mã Java, hãy xem bài đăng này trên Cộng đồng Apigee.

Tham chiếu phần tử

Tài liệu tham khảo về phần tử mô tả các phần tử và thuộc tính của chính sách JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Thuộc tính <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Thuộc tính Mô tả Mặc định Sự hiện diện
name

Tên nội bộ của chính sách. Giá trị của thuộc tính name có thể chứa chữ cái, số, dấu cách, dấu gạch nối, dấu gạch dưới và dấu chấm. Giá trị này không được vượt quá 255 ký tự.

(Không bắt buộc) Bạn có thể dùng phần tử <DisplayName> để gắn nhãn chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên ngôn ngữ tự nhiên khác.

 Không áp dụng Bắt buộc
continueOnError

Đặt thành false để trả về lỗi khi chính sách không thành công. Điều này là dự kiến đối với hầu hết các chính sách.

Đặt thành true để tiếp tục thực thi luồng ngay cả sau khi có chính sách không thành công.

 false Không bắt buộc
enabled

Hãy đặt thành true để thực thi chính sách này.

Đặt thành false để tắt chính sách này. Chính sách này sẽ không được thực thi ngay cả khi luồng đó vẫn được liên kết với một luồng.

 đúng Không bắt buộc
async

Thuộc tính này không được dùng nữa.

 false Không được dùng nữa

&lt;DisplayName&gt; phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>
Mặc định

Không áp dụng

Nếu bạn bỏ qua phần tử này, giá trị của thuộc tính name của chính sách sẽ là đã sử dụng.
Sự hiện diện Không bắt buộc
Loại Chuỗi

Phần tử <ClassName>

Chỉ định tên của lớp Java sẽ thực thi khi chính sách Lệnh gọi Java chạy. Lớp này phải có trong tệp JAR do <ResourceURL> chỉ định. Xem thêm Cách tạo chú thích Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Mặc định: Không áp dụng
Sự hiện diện: Bắt buộc
Loại: Chuỗi

Phần tử <Property>

Chỉ định một thuộc tính mà bạn có thể truy cập từ mã Java trong thời gian chạy. Bạn phải chỉ định một giá trị chuỗi theo nghĩa đen cho từng thuộc tính; bạn không thể tham chiếu các biến luồng trong phần tử này. Để xem ví dụ hoạt động sử dụng các thuộc tính, hãy xem bài viết Cách sử dụng các thuộc tính trong chú thích Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Mặc định: Không có
Sự hiện diện: Không bắt buộc
Loại: Chuỗi

Thuộc tính

Thuộc tính Mô tả Mặc định Sự hiện diện
tên

Chỉ định tên của thuộc tính.

 Không áp dụng Bắt buộc.

Phần tử<ResourceURL>

Phần tử này chỉ định tệp JAR Java sẽ thực thi khi chính sách lệnh gọi Java chạy.

Bạn có thể lưu trữ tệp này ở phạm vi proxy API (trong /apiproxy/resources/java trong gói proxy API hoặc trong phần Tập lệnh của ngăn Trình điều hướng của trình chỉnh sửa proxy API), hoặc ở phạm vi tổ chức hoặc môi trường để sử dụng lại trên nhiều proxy API, như mô tả trong phần Tệp tài nguyên.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Mặc định: Không có
Sự hiện diện: Bắt buộc
Loại: Chuỗi

Tham chiếu lỗi

Phần này mô tả các mã lỗi và thông báo lỗi được trả về cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi chính sách này thực thi.

Mã lỗi Trạng thái HTTP Nguyên nhân Khắc phục
steps.javacallout.ExecutionError 500 Xảy ra khi mã Java gửi ra một ngoại lệ hoặc trả về giá trị rỗng trong quá trình thực thi chính sách JavaAnnotation.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách.

Tên lỗi Chuỗi lỗi Trạng thái HTTP Xảy ra khi
ResourceDoesNotExist Resource with name [name] and type [type] does not exist Không áp dụng Tệp được chỉ định trong phần tử <ResourceURL> không tồn tại.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] Không áp dụng Tệp lớp được chỉ định trong phần tử <ClassName> không nằm trong jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Không áp dụng Xem chuỗi lỗi. Xem thêm mục Được hỗ trợ và các phiên bản phần mềm được hỗ trợ.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] Không áp dụng Xem chuỗi lỗi.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] Không áp dụng Xem chuỗi lỗi.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] Không áp dụng Xem chuỗi lỗi.
NoResourceForURL Could not locate a resource with URL [string] Không áp dụng Xem chuỗi lỗi.

Biến lỗi

Các biến này được đặt khi chính sách này kích hoạt lỗi. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.

Biến Trong đó Ví dụ:
fault.name="fault_name" fault_name là tên của lỗi, như được liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name là tên do người dùng chỉ định của chính sách gây ra lỗi. javacallout.JC-GetUserData.failed = true

Ví dụ về phản hồi khi gặp lỗi

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

Ví dụ về quy tắc lỗi

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Giản đồ

Biên dịch và triển khai

Để biết thông tin chi tiết về cách biên dịch mã Java tuỳ chỉnh và triển khai mã đó bằng một proxy, hãy xem bài viết Cách tạo một lệnh gọi Java.

Các quy định hạn chế

Dưới đây là những hạn chế mà bạn cần cân nhắc khi viết chú thích Java:

  • Hầu hết các lệnh gọi hệ thống đều không được phép. Ví dụ: bạn không thể đọc hoặc ghi hệ thống tệp nội bộ.
  • Truy cập vào mạng thông qua các ổ cắm. Apigee hạn chế quyền truy cập vào các địa chỉ sitelocal, anylocal, loopback và linklocal.
  • Chú thích không thể 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. Mặc dù một số lệnh 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. Để đảm bảo khả năng tương thích trong tương lai, bạn nên tránh thực hiện các lệnh gọi như vậy trong mã của mình.
  • Không hỗ trợ việ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 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.
  • Đừng sử dụng io.apigee hoặc com.apigee làm tên gói trong chú thích Java. Những tên này được các mô-đun Apigee khác đặt trước và sử dụng.

Nội dung ngữ cảnh

Đặt JAR trong một proxy API trong /resources/java. 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 các tệp này được tải đúng cách trong thời gian chạy.

Nếu bạn đang sử dụng giao diện người dùng quản lý để tạo hoặc sửa đổi proxy, hãy thêm một tài nguyên mới và chỉ định một tệp JAR phụ thuộc bổ sung. Nếu có nhiều JAR, bạn chỉ cần thêm chúng 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ông tin về cách tải JAR Java lên, hãy xem phần Tệp tài nguyên.

Để xem ví dụ chi tiết minh hoạ cách đóng gói và triển khai một Lời gọi Java bằng Maven hoặc javac, hãy xem bài viết Cách tạo một lời gọi Java.

Javadoc

Javadoc để viết mã Lời gọi Java có tại đây trên GitHub. Bạn sẽ cần sao chép hoặc tải HTML xuống hệ thống của mình, sau đó chỉ cần mở tệp index.html trong trình duyệt.

Lưu ý về cách sử dụng

  • 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ời gọi Java tham chiếu đến một "tài nguyên" Java và xác định Bước trong luồng API mà mã Java thực thi. Bạn có thể tải JAR Java lên thông qua trình chỉnh sửa proxy của 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ộ.
  • Đối với các thao tác có mức sử dụng tài nguyên thấp, chẳng hạn như lệnh gọi API đến các dịch vụ từ xa, bạn nên 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 đề HTTP, tham số hoặc nội dung thông báo, Apigee đề xuất sử dụng chính sách JavaScript.

Chủ đề có liên quan