Chính sách JavaScript

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

Chính sách này cho phép bạn thêm mã JavaScript tuỳ chỉnh thực thi trong bối cảnh của một quy trình proxy API. Trong mã JavaScript tuỳ chỉnh, bạn có thể sử dụng các đối tượng, phương thức và thuộc tính của mô hình đối tượng JavaScript Apigee Edge. Mô hình đối tượng cho phép bạn nhận, đặt và xoá các biến trong ngữ cảnh luồng proxy. Bạn cũng có thể sử dụng các hàm mã hoá cơ bản được cung cấp cùng với mô hình đối tượng.

Giới thiệu

Có nhiều trường hợp sử dụng cho chính sách JavaScript. Ví dụ: bạn có thể 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, chỉnh sửa linh hoạt URL đích phụ trợ, 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. Trên thực tế, bạn có thể sử dụng chính sách JavaScript để đạt được nhiều hành vi tương tự như các chính sách khác đã triển khai, chẳng hạn như AssignMessage và ExtractVariable.

Một trường hợp sử dụng mà bạn không nên dùng cho chính sách JavaScript là ghi nhật ký. Chính sách Ghi nhật ký thông báo phù hợp hơn nhiều cho việc ghi nhật ký vào các nền tảng ghi nhật ký của bên thứ ba như Splunk, Sumo và Loggly, đồng thời bạn cải thiện hiệu suất của proxy API bằng cách thực thi chính sách Ghi nhật ký thông báo trong PostClientFlow, chính sách này sẽ thực thi sau khi phản hồi được gửi lại cho máy khách.

Chính sách JavaScript cho phép bạn chỉ định một tệp nguồn JavaScript để thực thi hoặc bạn có thể trực tiếp thêm mã JavaScript vào cấu hình của chính sách bằng phần tử <Source>. Dù bằng cách nào, mã JavaScript sẽ thực thi khi bước mà chính sách được đính kèm thực thi. Đối với lựa chọn tệp nguồn, mã nguồn luôn được lưu trữ ở một vị trí tiêu chuẩn trong gói proxy: apiproxy/resources/jsc. Hoặc bạn cũng có thể lưu trữ mã nguồn trong một tệp tài nguyên ở cấp môi trường hoặc tổ chức. Để biết hướng dẫn, hãy xem phần Tệp tài nguyên. Bạn cũng có thể tải JavaScript lên thông qua trình chỉnh sửa proxy giao diện người dùng Apigee.

Các tệp nguồn JavaScript phải luôn có đuôi .js.

Hãy xem phần Phần mềm và phiên bản được hỗ trợ để biết phiên bản JavaScript hiện được hỗ trợ.

Video

Xem một video ngắn để tìm hiểu cách tạo tiện ích chính sách tuỳ chỉnh bằng chính sách JavaScript.

Mẫu

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

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 JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

Thuộc tính <Javascript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Các thuộc tính sau đây dành riêng cho chính sách này.

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:

&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>

Phần tử <IncludeURL>

Chỉ định một tệp thư viện JavaScript sẽ được tải dưới dạng phần phụ thuộc vào tệp JavaScript chính được chỉ định bằng phần tử <ResourceURL> hoặc <Source>. Các tập lệnh sẽ được đánh giá theo thứ tự được liệt kê trong chính sách. Mã của bạn có thể sử dụng các đối tượng, phương thức và thuộc tính của mô hình đối tượng JavaScript.

Thêm nhiều tài nguyên phụ thuộc JavaScript bằng các phần tử <IncludeURL> bổ sung.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Ví dụ:

Hãy xem Ví dụ cơ bản trong phần Mẫu.

Phần tử <Property>

Chỉ định một thuộc tính mà bạn có thể truy cập từ mã JavaScript trong thời gian chạy.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Thuộc tính

Ví dụ:

Hãy xem ví dụ trong phần Mẫu.

Phần tử <ResourceURL>

Chỉ định tệp JavaScript chính sẽ thực thi trong luồng API. Bạn có thể lưu trữ tệp này ở phạm vi proxy API (trong /apiproxy/resources/jsc 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. Mã của bạn có thể sử dụng các đối tượng, phương thức và thuộc tính của mô hình đối tượng JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Ví dụ:

Hãy xem Ví dụ cơ bản trong phần Mẫu.

Phần tử <Source>

Cho phép bạn chèn JavaScript trực tiếp vào cấu hình XML của chính sách. Mã JavaScript được chèn sẽ thực thi khi chính sách thực thi trong luồng API.

Ví dụ:

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Phần tử <SSLInfo>

Chỉ định các thuộc tính dùng để định cấu hình TLS cho tất cả các phiên bản máy khách HTTP do chính sách JavaScript tạo.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Quy trình định cấu hình TLS cho một ứng dụng HTTP cũng giống như quy trình bạn dùng để định cấu hình TLS cho TargetEndpoint/TargetServer. Hãy xem phần Định cấu hình TLS từ Edge đến phần phụ trợ để biết thêm thông tin.

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

Một chính sách JavaScript không chứa mã thực tế. Thay vào đó, một chính sách JavaScript sẽ tham chiếu đến một "tài nguyên" JavaScript và xác định Bước trong quy trình API mà JavaScript thực thi. Bạn có thể tải tập lệnh lên thông qua trình chỉnh sửa proxy trên Giao diện người dùng quản lý hoặc bạn có thể đưa tập lệnh vào thư mục /resources/jsc trong các proxy API mà bạn phát triển cục bộ.

Gỡ lỗi mã chính sách JavaScript

Sử dụng hàm print() để xuất thông tin gỡ lỗi vào bảng đầu ra giao dịch trong Công cụ theo dõi. Để biết thông tin chi tiết và ví dụ, hãy xem phần Gỡ lỗi bằng câu lệnh print() trong JavaScript.

Cách xem câu lệnh in trong Trace:

1. Mở Công cụ theo dõi và bắt đầu một phiên theo dõi cho một proxy chứa chính sách JavaScript của bạn.
2. Gọi proxy.
3. Trong Công cụ theo dõi, hãy nhấp vào Đầu ra từ tất cả các giao dịch để mở bảng đầu ra.

   

4. Các câu lệnh in sẽ xuất hiện trong bảng điều khiển này.

Bạn có thể sử dụng hàm print() để xuất thông tin gỡ lỗi sang Công cụ theo dõi. Bạn có thể sử dụng trực tiếp hàm này thông qua mô hình đối tượng JavaScript. Để biết thông tin chi tiết, hãy xem phần "Gỡ lỗi JavaScript bằng câu lệnh print()".

Biến luồng

Theo mặc định, chính sách này không điền sẵn bất kỳ biến nào; tuy nhiên, bạn có thể đặt (và nhận) các biến luồng trong mã JavaScript bằng cách gọi các phương thức trên đối tượng ngữ cảnh. Một mẫu điển hình có dạng như sau:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

Đối tượng ngữ cảnh là một phần của mô hình đối tượng JavaScript của Apigee Edge.

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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

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

Example error response

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Lược đồ

Mỗi loại chính sách được xác định bằng một lược đồ XML (.xsd). Để tham khảo, bạn có thể xem lược đồ chính sách trên GitHub.

Chủ đề có liên quan

• Mô hình đối tượng JavaScript
• Để xem hướng dẫn, mẫu chính sách và mẫu JavaScript, hãy xem phần Lập trình các proxy API bằng JavaScript.

Bài viết trên Cộng đồng Apigee

Bạn có thể tìm thấy những bài viết liên quan này trên Cộng đồng Apigee:

• Làm cách nào để xử lý tiêu đề có nhiều giá trị trong JavaScript?