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 các chính sách Apigee đưa vào từ đầu. Trong mã Java, bạn có thể truy cập vào các thuộc tính 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 chỉ mới làm quen với chính sách này, hãy xem phần Cách tạo chú thích 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ợ.

Trường hợp nên sử dụng

Để 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 phần Cách tạo chú thích Java.

Giới thiệu

Chính sách về chú thích Java cho phép bạn lấy và đặt các biến luồng, thực thi logic tuỳ chỉnh và 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 theo bất kỳ gói JAR nào mà bạn cần. Lưu ý rằng có một số hạn chế về những việc bạn có thể làm với Chú thích 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 bằng mã Java. Để biết ví dụ về cách sử dụng các thuộc tính, hãy xem phần Cách sử dụng 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 cần truy cập vào thuộc tính qua mã Java. Giá trị của phần tử <Property> (giá trị nằm giữa các thẻ mở và đó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 biến luồng để nhận giá trị.

  • Định cấu hình 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 khi 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

Để xem nội dung mô tả rõ ràng về cách đặt 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 API.

Tham chiếu phần tử

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

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

Thuộc tính <Javachú thích>

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

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

Thuộc tính Nội dung 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ự.

Nếu muốn, bạn có thể sử dụng phần tử <DisplayName> để gắn nhãn cho chính sách này 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 một chính sách không hoạt động. Đây là hành vi dự kiến đối với hầu hết các chính sách.

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

 false Không bắt buộc
enabled

Đặt thành true để thực thi chính sách.

Đặ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 chính sách vẫn được đính kèm vào một quy trình.

 đú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

Phần tử <DisplayName>

Sử dụng cùng với thuộc tính name để gắn nhãn cho 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 khác theo ngôn ngữ tự nhiên.

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

Không áp dụng

Nếu bạn bỏ qua phần tử này, thì giá trị thuộc tính name của chính sách sẽ được 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 Chú thích Java chạy. Lớp này phải có trong tệp JAR do <ResourceURL> chỉ định. Hãy xem thêm bài viết 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 cố định 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. Để biết ví dụ về cách sử dụng các thuộc tính, hãy xem phần 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 Nội dung 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 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 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 đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem 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 thực thi chính sách.

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 trả về một ngoại lệ hoặc trả về giá trị rỗng trong quá trình thực thi chính sách JavaAnnotate.

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 này.

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 tệp jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Không áp dụng Xem chuỗi lỗi. Ngoài ra, hãy xem thêm phần Phần mềm và phiên bản đượ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 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ư 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 của chính sách báo lỗi do người dùng chỉ định. javacallout.JC-GetUserData.failed = true

Ví dụ về phản hồi 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 proxy, hãy xem phần Cách tạo chú thích Java.

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

Dưới đây là các hạn chế mà bạn cần xem xét 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ể yêu cầu hệ thống tệp nội bộ đọc hoặc ghi.
  • Quyền truy cập vào mạng qua ổ 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 được 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ố 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. Để có khả năng tương thích chuyển tiếp, bạn nên tránh thực hiện những lệnh gọi như vậy trong mã.
  • Chúng tôi không hỗ trợ việc sử dụng các 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 có gì đảm bảo rằng thư viện sẽ được cung cấp cho mọi bản phát hành.
  • Đừng dùng io.apigee hoặc com.apigee làm tên gói trong Chú thích Java. Những tên đó được các mô-đun Apigee khác đặt trước và sử dụng.

Nội dung ngữ cảnh

Đặt tệp JAR vào một proxy API trong /resources/java. 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 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 tài nguyên mới và chỉ định thêm một tệp JAR phụ thuộc. 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ô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.

Để biết 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 bài viết Cách tạo chú thích Java.

Javadoc

Chúng tôi cung cấp Javadoc để viết mã Chú thích Java tại đây trên GitHub. Bạn 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 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 và xác định Bước trong quy trình API nơi mã Java thực thi. 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ộ.
  • Đối với các thao tác nhẹ, 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 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ư, chẳng hạn như sửa đổi hoặc trích xuất các tiêu đề, tham số hoặc nội dung thư HTTP, Apigee nên sử dụng chính sách JavaScript.

Chủ đề có liên quan