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

Nội dung

Cho phép bạn sử dụng Java để triển khai hành vi tuỳ chỉnh không có sẵn bằng cách 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à biến luồng trong luồng proxy. Nếu bạn chỉ mới bắt đầu sử dụng chính sách này, hãy xem Cách tạo Java chú thích.

Đố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ợ.

Thời gian

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

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 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 điều chỉnh 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 bằng bất kỳ tệp JAR nào mà bạn cần trong gói. Ghi chú có một số hạn chế về những gì bạn có thể làm với Chú thích Java. Các địa điểm đó được liệt kê bên dưới trong phần Hạn chế.

Mẫu

Ví dụ đơn giản

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

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

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

Sử dụng <Property> thuộc tính name của phần tử để chỉ định tên bằng để truy cập vào thuộc tính qua mã Java. của phần tử <Property> giá trị (giá trị giữa các thẻ mở và đóng) là giá trị mà sẽ nhận được mã Java. 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ị.

  • Định cấu hình thuộc tính. Ở đâ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 lớp Thực thi cách triển khai như sau:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Thiết lập các biến luồng trong mã Java

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

Tham chiếu phần tử

Phần tham chiếu phần tử mô tả các phần tử và thuộc tính của chính sách JavaAnnotation.

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

&lt;JavaCallout&gt; thuộc tính

<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

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

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

<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

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

Chỉ định một thuộc tính mà bạn có thể truy cập qua mã Java trong thời gian chạy. Bạn phải chỉ định một giá trị cố định giá trị chuỗi cho mỗi thuộc tính; bạn không thể tham chiếu các biến luồng trong phần tử này. Đối với ví dụ về cách hoạt động khi sử dụng thuộc tính, hãy xem Cách sử dụng 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.

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

Phần tử này chỉ định tệp JAR Java sẽ thực thi khi chính sách chú thích 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 mục 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 tại 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 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 chi tiết về cách biên dịch mã Java tuỳ chỉnh và triển khai mã đó bằng proxy, hãy xem Cách tạo Java chú thích.

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 hệ thống tệp nội bộ hoặc viết.
  • Truy cập vào mạng qua ổ cắm. Apigee hạn chế quyền truy cập vào các trang web, địa chỉ loopback và địa chỉ linklocal.
  • Chú thích không thể nhận thông tin về quy trình hiện tại, danh sách quy trình hoặ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ể thực hiện được, nhưng không được hỗ trợ và có thể bị vô hiệu hoá bất cứ lúc nào. Để tương thích chuyển tiếp, bạn nên tránh thực hiện các lệnh gọi như vậy trong mã.
  • Không hỗ trợ những 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 có gì đảm bảo rằng thư viện sẽ có sẵn từ bản phát hành này đến bản phát hành khác.
  • Đừng dùng io.apigee hoặc com.apigee làm tên gói trong Java Chú thích. Những tên này đã được đặt trước và được các mô-đun Apigee khác sử dụng.

Nội dung ngữ cảnh

Đặt tệp JAR vào proxy API trong /resources/java. Nếu Chú thích Java sử dụng trên 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 đó trong thư mục /resources/java để đảm bảo rằng chúng được tải chính xác tại 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 tài nguyên mới và chỉ định tệp JAR phụ thuộc bổ sung. Nếu có nhiều tệp JAR, bạn chỉ cần thêm các tệp đó dưới dạng các tài nguyên khác. Bạn không cần sửa đổi cấu hình chính sách để tham khảo các Tệp JAR. Chỉ cần đặt các tham số này vào /resources/java là đủ.

Để biết 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.

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

Javadoc

Javadoc để viết mã Chú thích Java được đưa vào tại đây 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ở index.html trong trình duyệt.

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

  • 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 "Tài nguyên" Java và xác định Bước trong luồng API nơi mã Java thực thi. Bạn có thể tải tệp JAR Java của bạn lên 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ộ.
  • Đối với các thao tác đơn giản, 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 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, thông số hoặc nội dung thông báo, Apigee khuyên bạn nên sử dụng chính sách JavaScript.

Chủ đề có liên quan