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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

<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