Chính sách JavaScript

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

Chính sách này cho phép bạn thêm mã JavaScript tuỳ chỉnh thực thi trong ngữ cảnh của luồng 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 của Apigee Edge. Mô hình đối tượng cho phép bạn lấy, đặ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 kèm theo mô hình đối tượng.

Giới thiệu

Có nhiều trường hợp sử dụng chính sách JavaScript. Ví dụ: bạn có thể 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, chỉnh sửa linh động URL đích phụ trợ và làm nhiều việc khác. 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. Trên thực tế, bạn có thể sử dụng chính sách JavaScript để đạt được nhiều hành vi giống như được triển khai bởi các chính sách khác, như AttributionMessage và ExtractVariable.

Một trường hợp sử dụng mà bạn không nên áp 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 để 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 giúp 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 thực thi sau khi phản hồi được gửi lại cho ứng dụng 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 đưa mã JavaScript vào cấu hình của chính sách bằng phần tử <Source>. Dù theo cách nào thì mã JavaScript cũng sẽ thực thi khi bước đính kèm chính sách được thực thi. Đối với tuỳ 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 tệp tài nguyên ở cấp môi trường hoặc tổ chức. Để được 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ó phần mở rộng .js.

Xem phần Phần mềm và phiên bản được hỗ trợ cho phiên bản JavaScript hiện được hỗ trợ.

Video

Hãy xem video ngắn để tìm hiểu cách tạo phần mở rộng về 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ử

Tham chiếu 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">

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

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:

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>

Phần tử <IncludeURL>

Chỉ định một tệp thư viện JavaScript cần được tải dưới dạng phần phụ thuộc cho 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 nêu 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.

Cung cấp nhiều tài nguyên phần phụ thuộc JavaScript với các phần tử <IncludeURL> bổ sung.

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

Ví dụ:

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ụ:

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 mục Tập lệnh của ngăn Trình điều hướng của trình điều hướng 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. 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ụ:

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 này 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 ứng dụng HTTP được tạo theo chính sách JavaScript.

    <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 ứng dụng HTTP cũng giống như quy trình bạn sử dụng để định cấu hình TLS cho một TargetEndpoint/TargetServer. Hãy xem bài viết Đị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

Chính sách JavaScript không chứa mã thực. Thay vào đó, chính sách JavaScript sẽ tham chiếu đến một "tài nguyên" JavaScript và xác định Bước trong luồng API nơi 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 giao diện người dùng quản lý hoặc đưa tập lệnh này 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 sang bảng điều khiển đầu ra của 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() JavaScript.

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

1. Mở Công cụ theo dõi và bắt đầu 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 Output from all Transaction (Kết quả từ tất cả giao dịch) để mở bảng điều khiển đầu ra.

   

4. Báo cáo in của bạn 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. Hàm này có sẵn trực tiếp 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 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ẫu thông thường sẽ có dạng như sau:

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

Đối tượng ngữ cảnh thuộc mô hình đối tượng JavaScript của Apigee Edge.

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. Bạn cần nắm được thông tin này nếu đ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 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.

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.

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 trong thời gian chạy. Để 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.

Ví dụ về phản hồi lỗi

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

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

<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 giản đồ XML (.xsd). Giản đồ chính sách có sẵn trên GitHub để bạn tham khảo.

Chủ đề có liên quan

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

Các bài viết trong Cộng đồng Apigee

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

• Cách xử lý các tiêu đề có nhiều giá trị trong JavaScript?