Lập trình proxy API với 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

Trong chủ đề này, bạn sẽ tìm hiểu cách dùng JavaScript để thêm tiêu đề HTTP vào thông báo phản hồi một cách linh động, cũng như cách phân tích cú pháp phản hồi JSON và trả về một số thuộc tính của phản hồi đó cho ứng dụng yêu cầu.

Tải xuống và dùng thử mã mẫu

Giới thiệu về ví dụ sổ tay nấu ăn này

Ví dụ về sổ tay này minh hoạ một mẫu proxy API, trong đó bạn triển khai hành vi API bằng JavaScript. Các ví dụ về JavaScript được thiết kế để cho bạn thấy cách làm việc với các biến đơn giản và nội dung thông báo. Một mẫu cho bạn thấy cách lấy và đặt các biến. Ví dụ thứ hai cho thấy cách phân tích cú pháp JSON và tạo một thông báo từ kết quả.

Có 2 mẫu JavaScript trong proxy API:

  • setHeaders.js: JavaScript này nhận các giá trị của một số biến được đặt khi một proxy API được gọi. JavaScript sẽ thêm các biến đó vào thông báo phản hồi để bạn có thể thấy giá trị của các biến cho từng yêu cầu mà bạn thực hiện.
  • minimize.js: JavaScript này cho bạn biết cách xử lý nội dung thông báo. Ý tưởng đằng sau mẫu này là một dịch vụ thường trả về nhiều dữ liệu hơn mức cần thiết. Vì vậy, JavaScript sẽ phân tích thông báo phản hồi, trích xuất một số thuộc tính thú vị, sau đó sử dụng các thuộc tính đó để tạo nội dung của thông báo phản hồi.

Mã cho setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Mã cho minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Bạn có thể truy cập vào các biến luồng trong JavaScript thông qua đối tượng ngữ cảnh. Đối tượng này thuộc mô hình đối tượng JavaScript của Edge. Để biết thông tin chi tiết về mô hình đối tượng, hãy xem Mô hình đối tượng JavaScript.

Trước khi bắt đầu

Trước khi khám phá ví dụ về sổ tay này, bạn cũng nên làm quen với những khái niệm cơ bản sau:

  • Chính sách là gì và cách đính kèm chính sách vào các proxy. Để biết thông tin tổng quan về chính sách, hãy xem phần Chính sách là gì?.
  • Cấu trúc của một quy trình proxy, như được giải thích trong phần Định cấu hình quy trình. Luồng cho phép bạn chỉ định trình tự mà các chính sách được thực thi bởi một proxy API. Trong ví dụ này, một số chính sách được tạo và thêm vào một quy trình proxy API.
  • Cách tổ chức dự án proxy API trên hệ thống tệp của bạn, như được giải thích trong Tài liệu tham khảo về cấu hình proxy API.
  • Có kiến thức về XML, JSON và JavaScript. Trong ví dụ này, bạn sẽ tạo proxy API và các chính sách của proxy đó bằng các tệp XML nằm trên hệ thống tệp.

Nếu đã tải mã mẫu xuống, bạn có thể tìm thấy tất cả các tệp được đề cập trong chủ đề này trong thư mục mẫu javascript-cookbook. Các phần sau đây sẽ thảo luận chi tiết về mã mẫu.

Tìm hiểu về quy trình uỷ quyền

Để JavaScript thực thi trong một proxy API, bạn phải đính kèm JavaScript đó vào một luồng bằng cách sử dụng một tệp đính kèm chính sách có tên là "Bước". Một chính sách thuộc loại Javascript (lưu ý chữ viết hoa) chỉ chứa một tham chiếu đến tên của một tệp JavaScript. Bạn trỏ chính sách đến một tệp JavaScript bằng cách sử dụng phần tử ResourceURL.

Ví dụ: chính sách sau đây tham chiếu đến tệp JavaScript có tên là setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Bạn có thể đính kèm chính sách này vào một luồng proxy API như mọi loại chính sách khác. Bằng cách đính kèm chính sách vào quy trình proxy API, bạn cho biết vị trí cần thực thi JavaScript. Điều này cho phép bạn thực thi JavaScript tương tác với thông báo yêu cầu hoặc thông báo phản hồi khi các thông báo đó "chảy" qua proxy API. Trong ví dụ này, cả hai JavaScript đều thực thi trong luồng phản hồi, vì các chính sách này thực hiện 2 việc: đặt tiêu đề HTTP trên thông báo phản hồi và "giảm thiểu" thông báo phản hồi mà Apigee Edge trả về cho ứng dụng yêu cầu.

Nếu mở cấu hình luồng này trong giao diện người dùng quản lý, bạn sẽ thấy cấu hình luồng bên dưới.

Chọn Proxy Endpoints > default > PostFlow (Điểm cuối của proxy > mặc định > PostFlow) trong ngăn Navigator (Trình điều hướng).

Cấu hình XML tương ứng cho ProxyEndpoint có tên "default" xuất hiện bên dưới. 

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Sau đây là nội dung tóm tắt về các phần tử của quy trình.

  • <Request> – Phần tử <Request> bao gồm một số phần tử <Step>. Mỗi bước gọi một trong các chính sách mà bạn tạo thông qua phần còn lại của chủ đề này. Các chính sách này đính kèm một JavaScript vào quy trình proxy API và vị trí của tệp đính kèm chính sách sẽ xác định thời điểm JavaScript thực thi.
  • <Response> – Phần tử <Response> cũng bao gồm <Steps>. Các bước này cũng gọi các chính sách chịu trách nhiệm xử lý phản hồi cuối cùng từ đích đến (trong ví dụ này là đích đến dịch vụ mô phỏng của Apigee – lưu ý chế độ cài đặt HTTPTargetConnection trong /apiproxy/targets/default.xml.)
  • <HTTPProxyConnection> – Chỉ định máy chủ lưu trữ và đường dẫn URI xác định địa chỉ mạng mà các ứng dụng gọi để sử dụng API này.
  • <RouteRule> – Phần tử này chỉ định cấu hình TargetEndpoint nào được ProxyEndpoint gọi.

Thêm mã JavaScript vào một proxy

JavaScript (chẳng hạn như tập lệnh Python, tệp JAR Java, tệp XSLT, v.v.) được lưu trữ dưới dạng tài nguyên. Khi mới bắt đầu làm việc với JavaScript, bạn nên lưu trữ các tệp JavaScript trong proxy API. Khi bạn tiến hành, JavaScript nên được tạo càng chung chung và có thể sử dụng lại càng tốt, sau đó được lưu trữ ở cấp môi trường hoặc tổ chức. Điều này giúp bạn không phải lưu trữ cùng một tệp JavaScript trong nhiều proxy API, điều này có thể nhanh chóng trở nên khó quản lý.

Để tìm hiểu về cách lưu trữ tài nguyên ở cấp tổ chức và môi trường, hãy xem Tệp tài nguyên.

Dùng thử

Để biết hướng dẫn về cách triển khai và gọi proxy, hãy xem README của sổ tay JavaScript.

Nhập và triển khai proxy API

Sau khi thực hiện các thay đổi, bạn có thể Lưu proxy API trong công cụ trình tạo proxy API trong giao diện người dùng quản lý.

Hoặc bạn có thể chạy lệnh sau trong thư mục /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Kiểm thử JavaScript

Chạy lệnh sau trong thư mục /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

Cờ curl -v được dùng trong tập lệnh shell để xem tiêu đề HTTP trên thông báo phản hồi do JavaScript sửa đổi.

Bạn có thể gửi trực tiếp yêu cầu theo cách sau:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Nếu JavaScript thực thi đúng cách, bạn sẽ thấy một phản hồi như sau:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Giờ đây, bạn có thể sửa đổi JavaScript để thử những điều mới, triển khai lại proxy API và xác minh kết quả bằng cách gửi cùng một yêu cầu. Luôn đảm bảo rằng bạn triển khai proxy API có chứa JavaScript để các thay đổi có hiệu lực.

Lỗi tập lệnh

Chắc chắn bạn sẽ gặp lỗi khi viết JavaScript. Định dạng của các lỗi JavaScript mà bạn sẽ thấy do một proxy API phát hành được trình bày bên dưới.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Trường hợp sử dụng JavaScript

Trên Apigee Edge, thường có nhiều cách để triển khai chức năng cụ thể. Sử dụng các chính sách có sẵn nếu có thể và tránh việc mã hoá tất cả logic của proxy API trong JavaScript. Mặc dù Apigee Edge tận dụng JavaScript đã biên dịch để cải thiện hiệu suất, nhưng JavaScript khó có thể hoạt động hiệu quả như Chính sách. JavaScript có thể khó duy trì và gỡ lỗi hơn. Dành riêng JavaScript cho những chức năng chỉ có trong các yêu cầu của bạn.

Nếu hiệu suất là vấn đề đáng lo ngại đối với chức năng tuỳ chỉnh, hãy sử dụng Java nếu có thể.

Tóm tắt

Trong chủ đề về sổ tay này, bạn đã tìm hiểu cách đưa JavaScript vào cấu hình của một proxy API để triển khai hành vi tuỳ chỉnh. Hành vi tuỳ chỉnh do các mẫu triển khai minh hoạ cách lấy và biến, cũng như cách phân tích cú pháp JSON và tạo thông báo phản hồi tuỳ chỉnh.