Sử dụng các biến luồng

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Về mặt lý thuyết, biến luồng là các đối tượng mà bạn có thể truy cập trong các chính sách hoặc tiện ích (chẳng hạn như công cụ Công cụ theo dõi). Các API này cho phép bạn duy trì trạng thái liên kết với một giao dịch API do Apigee Edge xử lý.

Video

Video sau đây giới thiệu về các biến luồng:

Biến luồng là gì?

Biến luồng tồn tại trong ngữ cảnh của luồng proxy API và các biến này theo dõi trạng thái trong giao dịch API theo cách biến được đặt tên theo dõi trạng thái trong chương trình phần mềm. Biến luồng lưu trữ các thông tin như:

• Địa chỉ IP, tiêu đề, đường dẫn URL và tải trọng được gửi từ ứng dụng yêu cầu
• Thông tin hệ thống, chẳng hạn như ngày và giờ mà Edge nhận được yêu cầu
• Dữ liệu thu được khi một chính sách thực thi. Ví dụ: Sau khi một chính sách thực thi việc xác thực mã thông báo OAuth, Edge sẽ tạo các biến luồng lưu giữ thông tin như tên của ứng dụng yêu cầu.
• Thông tin về phản hồi từ hệ thống mục tiêu

Một số biến được "tích hợp" trong Edge và được tự động điền bất cứ khi nào nhận được yêu cầu API. Chúng có sẵn trong suốt giao dịch API. Bạn cũng có thể tạo biến tuỳ chỉnh của riêng mình bằng cách sử dụng các chính sách như AssignMessage policy hoặc trong JavaScript, Node.js và mã Java.

Như bạn sẽ thấy, biến có phạm vi và vị trí truy cập biến phụ thuộc một phần vào thời điểm biến được tạo trong luồng proxy API. Nhìn chung, khi một biến được tạo, biến đó sẽ có sẵn cho tất cả các chính sách và mã sẽ thực thi sau đó trong luồng giao dịch API.

Biến luồng được sử dụng như thế nào?

Biến luồng được dùng trong chính sách và luồng có điều kiện:

• Chính sách có thể truy xuất trạng thái từ các biến luồng và sử dụng các biến đó để thực hiện công việc.

  Ví dụ: một chính sáchVerifyJWT có thể truy xuất mã thông báo cần được xác minh từ một biến luồng rồi thực hiện xác minh trên mã đó. Một ví dụ khác là chính sách JavaScript có thể truy xuất các biến luồng và mã hoá dữ liệu có trong các biến đó.

• Luồng có điều kiện có thể tham chiếu các biến luồng để hướng luồng API thông qua Edge, giống như cách hoạt động của câu lệnh chuyển đổi trong lập trình.

  Ví dụ: một chính sách trả về lỗi chỉ có thể thực thi khi bạn thiết lập một biến luồng cụ thể. Cuối cùng, bạn có thể nhận và đặt các biến luồng trong ứng dụng mục tiêu Node.js.

Hãy xem các ví dụ về cách sử dụng biến trong từng ngữ cảnh này.

Biến luồng trong chính sách

Một số chính sách lấy biến flow làm dữ liệu đầu vào.

Ví dụ: assignMessage policy sau đây sẽ lấy giá trị của biến luồng client.ip và đặt giá trị đó vào tiêu đề yêu cầu có tên My-Client-IP. Nếu được thêm vào quy trình yêu cầu, chính sách này sẽ đặt một tiêu đề được truyền đến mục tiêu phụ trợ. Nếu bạn đặt chính sách này trên quy trình phản hồi, thì tiêu đề sẽ được gửi lại ứng dụng khách.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Một ví dụ khác là khi Chính sách hạn mức thực thi, một số biến luồng được điền sẵn bằng các giá trị liên quan đến chính sách. Một trong những biến này được gọi là ratelimit.my-quota-policy.used.count (trong đó my-quota-policy là tên của chính sách hạn mức mà bạn quan tâm).

Sau đó, bạn có thể thực thi một quy trình có điều kiện cho biết "nếu hạn mức hiện tại thấp hơn 50% mức tối đa và nằm trong khoảng thời gian từ 9 giờ sáng đến 5 giờ chiều, hãy áp dụng một hạn mức khác". Điều kiện này có thể phụ thuộc vào giá trị của hạn mức hiện tại và vào biến luồng có tên system.time (một trong các biến Edge tích hợp).

Biến luồng trong luồng có điều kiện

Luồng có điều kiện đánh giá các biến luồng và cho phép các proxy hoạt động linh hoạt. Các điều kiện thường được dùng để thay đổi hành vi của các luồng, các bước và quy tắc định tuyến.

Dưới đây là một luồng có điều kiện giúp đánh giá giá trị của biến request.verb trong một bước luồng proxy. Trong trường hợp này, nếu động từ yêu cầu là POST, thì VerifyAPIKey policy (chính sách Xác minh API) sẽ được thực thi. Đây là một mẫu phổ biến được dùng trong các cấu hình proxy API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Bây giờ, bạn có thể thắc mắc các biến như request.verb, client.ip và system.time đến từ đâu? Khi nào các hệ thống này được tạo thực thể và điền sẵn một giá trị? Để giúp bạn nắm được thời điểm tạo biến và thời điểm bạn có thể sử dụng các biến này, hãy xem bài viết Tìm hiểu phạm vi biến luồng.

Các biến luồng trong mã JavaScript được gọi bằng chính sách JavaScript

Với chính sách JavaScript, bạn có thể thực thi mã JavaScript từ trong ngữ cảnh của luồng proxy API. JavaScript mà chính sách này thực thi sẽ sử dụng mô hình đối tượng JavaScript của Apigee. Mô hình này cung cấp quyền truy cập mã tuỳ chỉnh vào các đối tượng yêu cầu, phản hồi và ngữ cảnh liên kết với luồng proxy API mà mã của bạn đang thực thi. Ví dụ: Mã này đặt một tiêu đề phản hồi bằng giá trị thu được từ biến luồng target.name.

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

Công nghệ sử dụng JavaScript để đọc và đặt các biến này tương tự như công việc bạn có thể thực hiện với chính sáchAssignMessage (hiển thị trước đó). Đó chỉ là một cách khác để thực hiện những việc tương tự trên Edge. Điều cần nhớ là JavaScript do chính sách JavaScript thực thi có quyền truy cập vào tất cả biến luồng hiện có và nằm trong phạm vi của luồng proxy API.

Biến luồng trong mã Node.js

Bằng cách yêu cầu mô-đun apigee-access, bạn có thể đặt và truy cập các biến luồng từ trong mã Node.js được triển khai cho Edge.

Dưới đây là một ví dụ đơn giản, trong đó biến có tên là custom.foo được đặt thành giá trị Bar. Sau khi được đặt, biến mới này có thể sử dụng được cho bất kỳ chính sách hoặc mã nào khác xuất hiện trong luồng proxy sau khi mã Node.js thực thi.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Bạn có thể đọc thêm về cách sử dụng apigee-access để làm việc với các biến trong phần Truy cập vào các biến luồng trong Node.js.

Tìm hiểu phạm vi biến của luồng

Phạm vi biến liên quan đến luồng hoặc "vòng đời" tổng thể của một lệnh gọi proxy API.

Trực quan hoá luồng của proxy API

Để hiểu phạm vi biến của luồng, bạn cần phải hiểu hoặc trực quan hoá được cách thông báo truyền qua một proxy API. Proxy API bao gồm một loạt các bước xử lý thông báo được sắp xếp theo luồng. Ở mỗi bước trong luồng proxy, proxy sẽ đánh giá thông tin có sẵn cho proxy và quyết định bước tiếp theo. Đồng thời, proxy có thể thực thi mã chính sách hoặc thực hiện phân nhánh có điều kiện.

Hình dưới đây minh hoạ trình tự các quy trình này. Hãy lưu ý rằng luồng bao gồm 4 phân đoạn chính: yêu cầu ProxyEndpoint, yêu cầu TargetEndpoint, phản hồi TargetEndpoint và phản hồi ProxyEndpoint.

Hãy lưu ý đến cấu trúc luồng này khi chúng ta bắt đầu tìm hiểu các biến luồng thông qua phần còn lại của chủ đề này.

Mối liên hệ giữa phạm vi biến và luồng proxy

Ngay khi có thể hình ảnh hoá cách thông báo truyền qua một proxy, như đã mô tả ở trên, bạn có thể bắt đầu hiểu phạm vi của biến. Theo phạm vi, chúng tôi muốn nói đến điểm trong vòng đời của luồng proxy khi biến được tạo thực thể lần đầu tiên.

Ví dụ: nếu bạn đính kèm một chính sách vào phân đoạn yêu cầu ProxyEndpoint, thì chính sách đó sẽ không thể truy cập vào bất kỳ biến nào thuộc phạm vi của phân đoạn yêu cầu TargetEndpoint. Lý do là vì phân đoạn yêu cầu TargetEndpoint của luồng chưa được thực thi, vì vậy, proxy API chưa có cơ hội để điền các biến trong phạm vi đó.

Bảng sau đây liệt kê toàn bộ phạm vi biến và cho biết thời điểm có thể sử dụng các phạm vi này trong luồng proxy.

Phạm vi biến	Vị trí điền sẵn các biến này
yêu cầu proxy	Phân đoạn yêu cầu ProxyEndpoint
yêu cầu mục tiêu	Phân đoạn yêu cầu TargetEndpoint
câu trả lời mục tiêu	Phân đoạn phản hồi TargetEndpoint
phản hồi proxy	Phân đoạn phản hồi ProxyEndpoint
luôn có sẵn	Ngay khi proxy nhận được yêu cầu. Các biến này có sẵn trong toàn bộ vòng đời luồng proxy.

Ví dụ: có một biến Edge tích hợp sẵn tên là client.ip. Biến này có phạm vi "yêu cầu proxy". Chuỗi này được tự động điền bằng địa chỉ IP của ứng dụng đã gọi proxy. Yêu cầu này được điền khi yêu cầu lần đầu đến ProxyEndpoint và vẫn có sẵn trong toàn bộ vòng đời luồng proxy.

Có một biến được tích hợp khác tên là target.url. Phạm vi của biến này là "yêu cầu mục tiêu". URL này được điền sẵn trong phân đoạn yêu cầu TargetEndpoint với URL yêu cầu được gửi đến mục tiêu phụ trợ. Nếu cố truy cập vào target.url trong phân đoạn yêu cầu ProxyEndpoint, bạn sẽ nhận được giá trị NULL. Nếu bạn cố gắng đặt biến này trước khi thuộc phạm vi áp dụng của biến, thì proxy sẽ không làm gì cả, tức là sẽ không tạo ra lỗi và không đặt biến đó.

Sau đây là một ví dụ đơn giản minh hoạ cách xem xét phạm vi biến. Giả sử bạn muốn sao chép toàn bộ nội dung của đối tượng yêu cầu (tiêu đề, tham số, nội dung) và chỉ định đối tượng đó cho tải trọng phản hồi sẽ được gửi trở lại ứng dụng gọi. Bạn có thể sử dụng chính sáchAssignMessage cho tác vụ này. Mã chính sách có dạng như sau:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Chính sách này chỉ sao chép đối tượng request và gán đối tượng đó cho đối tượng response. Nhưng bạn nên đặt chính sách này ở đâu trong luồng proxy? Câu trả lời là phản hồi đó phải được đặt trên phản hồi TargetEndpoint, vì phạm vi của biến phản hồi là "phản hồi mục tiêu".

Tham chiếu các biến luồng

Tất cả các biến tích hợp trong Apigee Edge đều tuân theo quy ước đặt tên bằng ký hiệu dấu chấm. Quy ước này giúp bạn dễ dàng xác định mục đích của biến. Ví dụ: system.time.hour và request.content.

Apigee sử dụng nhiều tiền tố để sắp xếp các biến liên quan một cách phù hợp. Các tiền tố này bao gồm:

• request
• response
• system
• target

Để tham chiếu một biến trong một chính sách, hãy đặt biến đó trong dấu ngoặc nhọn. Ví dụ: Chính sách assignMessage sau đây sẽ lấy giá trị của biến client.ip và đặt giá trị đó vào tiêu đề yêu cầu có tên Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Trong luồng có điều kiện, bạn không cần đặt dấu ngoặc nhọn. Điều kiện ví dụ sau đây đánh giá biến request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Bạn cũng có thể tham chiếu các biến luồng trong mã JavaScript và Java. Để biết thêm thông tin, hãy xem các bài viết sau:

• Xử lý các biến trong JavaScript
• Truy cập vào các biến luồng trong Node.js
• Chính sách về JavaScript

Kiểu dữ liệu của biến luồng

Mỗi thuộc tính của biến luồng có một loại dữ liệu được xác định rõ ràng, chẳng hạn như Chuỗi, Dài, Số nguyên, Boolean hoặc Tập hợp. Bạn có thể tìm thấy các loại dữ liệu được liệt kê trong Tài liệu tham khảo về biến luồng. Đối với các biến do một chính sách tạo, hãy tham khảo chủ đề tham khảo chính sách cụ thể để biết thông tin về loại dữ liệu.

Các biến bạn tạo theo cách thủ công giả định loại đã cho khi chúng được tạo và phụ thuộc vào loại giá trị được cho phép. Ví dụ: các biến được tạo trong mã Node.js sẽ bị hạn chế ở mục Number, String, Boolean, rỗng hoặc không xác định.

Sử dụng các biến luồng trong chính sách

Nhiều chính sách tạo các biến luồng như một phần trong quá trình thực thi thông thường. Tài liệu tham khảo chính sách ghi lại tất cả các biến dành riêng cho chính sách này.

Khi bạn làm việc với các proxy và chính sách, hãy nhớ tham khảo tài liệu tham khảo về chính sách để tìm hiểu xem biến nào được tạo và dùng cho mục đích gì. Ví dụ: Chính sách về hạn mức tạo một tập hợp các biến chứa thông tin về số lượng và giới hạn, thời gian hết hạn, v.v.

Một số biến chính sách rất hữu ích khi gỡ lỗi. Ví dụ: bạn có thể dùng công cụ Theo dõi để xem những biến nào được đặt tại một thực thể cụ thể trong luồng proxy.

Chính sách ExtractVariables cho phép bạn điền dữ liệu được trích xuất từ các thông báo cho các biến tuỳ chỉnh. Bạn có thể trích xuất các tham số truy vấn, tiêu đề và các dữ liệu khác. Ví dụ: bạn có thể phân tích cú pháp thông báo yêu cầu và phản hồi bằng các mẫu để trích xuất dữ liệu cụ thể từ thông báo.

Trong ví dụ sau, tính năng Extract Variables (Trích xuất các biến) sẽ phân tích cú pháp thông báo phản hồi và lưu trữ dữ liệu cụ thể lấy từ phản hồi. Chính sách này tạo 2 biến tuỳ chỉnh là geocoderesponse.latitude và geocoderesponse.longitude, đồng thời chỉ định giá trị cho các biến đó.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Xin nhắc lại rằng có nhiều chính sách tự động tạo các biến. Bạn có thể truy cập những biến đó trong ngữ cảnh luồng proxy. Những biến này sẽ được đề cập trong Tài liệu tham khảo chính sách trong từng chủ đề chính sách riêng lẻ.

Làm việc với các biến luồng trong mã JavaScript

Bạn có thể truy cập và đặt các biến trực tiếp trong mã JavaScript đang thực thi trong ngữ cảnh proxy API. Thông qua mô hình đối tượng JavaScript của Apigee, việc thực thi JavaScript trên Edge có quyền truy cập trực tiếp vào các biến luồng proxy.

Để truy cập các biến trong mã JavaScript, hãy gọi phương thức getter/setter trên bất kỳ đối tượng nào trong số này:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Như bạn có thể thấy, các tham chiếu đối tượng này ánh xạ đến các phân đoạn quen thuộc của mô hình luồng proxy như đã giải thích trước đó trong bài viết Hình ảnh hoá luồng của một proxy API.

Đối tượng context tương ứng với các biến "toàn cục" có sẵn, chẳng hạn như các biến hệ thống. Ví dụ: bạn có thể gọi getVariable() trên đối tượng context để nhận năm hiện tại:

var year = context.getVariable('system.time.year');

Tương tự, bạn có thể gọi setVariable() để đặt giá trị của biến tuỳ chỉnh hoặc cho mọi biến có thể ghi ngoài hộp. Ở đây, chúng ta tạo một biến tuỳ chỉnh có tên là organization.name.myorg và gán giá trị cho biến đó.

var org = context.setVariable('organization.name.myorg', value);

Vì biến này được tạo bằng đối tượng context, nên bạn có thể sử dụng biến này cho mọi phân đoạn luồng (về cơ bản, việc này giống như việc tạo một biến toàn cục).

Bạn cũng có thể lấy/thiết lập các biến luồng proxy trong mã Java mà bạn thực thi bằng chính sách Chú thích Java.

Truy cập các biến luồng trong ứng dụng Node.js

Bạn có thể nhận, đặt và xoá các biến luồng từ mã Node.js đã triển khai cho Edge. Tất cả những gì bạn cần làm là "require" mô-đun truy cập apigee trong mã của mình. Để biết thông tin chi tiết, hãy xem phần Truy cập vào các biến luồng trong Node.js.

Những điều bạn cần nhớ

Dưới đây là một số điều quan trọng cần nhớ về biến luồng:

• Một số biến "có sẵn" do chính proxy tạo bản sao và điền tự động. Những thay đổi này được ghi lại trong Tài liệu tham khảo về biến luồng.
• Bạn có thể tạo các biến tuỳ chỉnh để dùng trong luồng proxy. Bạn có thể tạo các biến bằng cách sử dụng các chính sách như AssignMessage và chính sách JavaScript và trong mã Node.js.
• Biến có phạm vi. Ví dụ: một số biến được điền tự động khi proxy đầu tiên nhận được yêu cầu từ một ứng dụng. Các biến khác được điền sẵn trong phân đoạn luồng phản hồi của proxy. Các biến phản hồi này vẫn là không xác định cho đến khi phân đoạn phản hồi được thực thi.
• Khi chính sách thực thi, chúng có thể tạo và điền các biến dành riêng cho chính sách. Tài liệu của mỗi chính sách liệt kê tất cả các biến dành riêng cho chính sách có liên quan này.
• Luồng có điều kiện thường đánh giá một hoặc nhiều biến. Bạn cần hiểu rõ các biến nếu muốn tạo luồng có điều kiện.
• Nhiều chính sách sử dụng biến làm dữ liệu đầu vào hoặc đầu ra. Có thể biến do một chính sách tạo ra sau đó lại được sử dụng lại.
• Bạn có thể lấy và đặt nhiều biến luồng từ trong Node.js bằng cách sử dụng JavaScript trực tiếp (và mô hình đối tượng JavaScript của chúng tôi) hoặc chính sách JavaChú thích, vốn sẽ thực thi mã trên Edge.

Mã mẫu có liên quan

Các mẫu proxy API có trên GitHub và dễ tải xuống cũng như sử dụng. Hãy xem phần Sử dụng proxy API mẫu để biết thông tin về cách tải xuống và sử dụng mẫu. Hãy xem phần Danh sách mẫu để biết nội dung mô tả về các mẫu proxy API và chức năng tương ứng.

Các proxy mẫu có tính năng sử dụng các biến và xử lý biến bao gồm:

• biến – Hướng dẫn cách trích xuất và đặt các biến dựa trên dữ liệu truyền tải cũng như nội dung thông báo JSON và XML.
• policy-mashup-cookbook – Một ứng dụng hoàn chỉnh dùng cấu trúc chính sách để gọi 2 API công khai, kết hợp kết quả và tạo phản hồi chi tiết cho ứng dụng khách. Để biết thêm thông tin về mẫu này, hãy xem Sử dụng cấu trúc chính sách.
• conditional-policy – Triển khai quá trình thực thi chính sách có điều kiện đơn giản dựa trên các giá trị biến.

Chủ đề có liên quan

• Tất cả biến được tự động điền sẵn trong proxy API đều được liệt kê trong Tài liệu tham khảo về biến luồng. Tài liệu tham khảo cũng liệt kê loại và phạm vi của mỗi biến.
• Nếu bạn muốn biết những biến mà một chính sách cụ thể được điền, hãy tham khảo chủ đề tham khảo cho chính sách đó. Ví dụ: hãy xem phần Biến luồng trong tài liệu tham khảo về Chính sách về hạn mức.