Trang này được dịch bởi Cloud Translation API.

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

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu về Apigee X. thông tin

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

Video

Video sau đây giới thiệu về biến flow:

Biến flow là gì?

Các biến flow tồn tại trong ngữ cảnh của flow proxy API và theo dõi trạng thái trong giao dịch API theo cách các biến được đặt tên theo dõi trạng thái trong một chương trình phần mềm. Biến flow 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ờ Edge nhận được yêu cầu
Dữ liệu bắt nguồn khi một chính sách thực thi. Ví dụ: sau khi một chính sách thực thi để xác thực một mã thông báo OAuth, Edge sẽ tạo các biến luồng chứa 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" vào Edge và tự động được điền bất cứ khi nào nhận được yêu cầu API. Các giá trị này có sẵn trong suốt mộ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ác chính sách như AssignmentMessage (chính sách gán) hoặc trong JavaScript, Node.js và mã Java.

Như bạn sẽ thấy, các biến đều có phạm vi và nơi có thể truy cập được tuỳ thuộc một phần vào thời điểm tạo biến 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ã thực thi sau này trong luồng giao dịch API.

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

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

Chính sách có thể truy xuất trạng thái từ các biến flow và sử dụng các biến đó để thực hiện công việc.
Ví dụ: Chính sách VerifyJWT có thể truy xuất mã xác minh cần xác minh từ một biến flow, sau đó thực hiện xác minh trên mã đó. Ví dụ khác: 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 để định hướng luồng của một 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ụ: chính sách trả về lỗi chỉ có thể thực thi khi một biến luồng cụ thể được đặt. Cuối cùng, bạn có thể lấy và đặt các biến flow trong ứng dụng mục tiêu Node.js.

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

Biến flow trong chính sách

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

Ví dụ: Chính sách AssignMessage sau đây lấy giá trị của biến flow client.ip và đặt giá trị đó vào tiêu đề yêu cầu có tên là My-Client-IP. Nếu được thêm vào luồng 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 được đặt trên luồng phản hồi, 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>

Ví dụ khác: khi một Chính sách hạn mức thực thi, một số biến luồng sẽ được điền sẵn bằng các giá trị liên quan đến chính sách. Một trong các 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 luồng có điều kiện với nội dung "nếu số lượng hạn mức hiện tại thấp hơn 50% số lượng hạn mức tối đa và nằm trong khoảng từ 9 giờ sáng đến 5 giờ chiều, hãy thực thi 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 số lượng hạn mức hiện tại và trên một biến luồng có tên là system.time. Đây là một trong các biến Edge tích hợp sẵn.

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 proxy hoạt động linh hoạt. Điều kiện thường được dùng để thay đổi hành vi của luồng, bước và quy tắc tuyến.

Dưới đây là một luồng có điều kiện đánh giá giá trị của biến request.verb trong bước luồng proxy. Trong trường hợp này, nếu động từ yêu cầu là POST, thì chính sáchVerifyAPIKey sẽ được thực thi. Đây là một mẫu phổ biến được dùng trong 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 thuộc tính này được tạo bản sao và được điền giá trị? Để giúp bạn hiểu thời điểm tạo biến và thời điểm bạn có thể sử dụng biến, hãy xem phần Tìm hiểu phạm vi biến luồng.

Biến flow 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 trong bối cảnh của luồng proxy API. JavaScript do 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 tiêu đề phản hồi bằng giá trị thu được từ biến flow target.name.

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

Kỹ thuật sử dụng JavaScript để đọc và đặt biến này tương tự như công việc bạn có thể làm với chính sách AssignMessage (đã trình bày trước đó). Đây chỉ là một cách khác để thực hiện các thao tác tương tự trên Edge. Điều quan trọng 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 trong luồng proxy API.

Biến flow trong mã Node.js

Bằng cách yêu cầu mô-đun apigee-access, bạn có thể thiết lập và truy cập các biến flow 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 sẽ có sẵn cho mọi chính sách hoặc mã khác xảy ra 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 bài viết Truy cập vào các biến luồng trong Node.js.

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

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

Trực quan hoá luồng proxy API

Để hiểu phạm vi biến flow, điều quan trọng là bạn phải hiểu hoặc hình dung cách thông báo chảy 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 dưới dạng một luồng. Ở mỗi bước trong luồng proxy, proxy sẽ đánh giá thông tin có sẵn và quyết định việc cần làm tiếp theo. Trong quá trình này, 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 sau đây minh hoạ trình tự các luồng này. Hãy lưu ý cách các luồng được tạo thành từ bốn 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 khám phá các biến luồng trong phần còn lại của chủ đề này.

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

Ngay khi có thể hình dung cách thư chuyển qua proxy, như mô tả trước đó, bạn có thể bắt đầu hiểu được phạm vi biến. Phạm vi ở đây có nghĩa là điểm trong vòng đời của luồng proxy khi một biến được tạo bản sao lần đầu tiên.

Ví dụ: nếu bạn có một chính sách đính kèm 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 phân đoạn yêu cầu TargetEndpoint. Lý do là 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ê tập hợp đầy đủ các phạm vi biến và cho biết thời điểm các phạm vi này có sẵn trong luồng proxy.

Phạm vi biến	Vị trí điề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
phản hồ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 của luồng proxy.

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

Có một biến tích hợp sẵn khác có tên là target.url. Phạm vi của biến này là "yêu cầu mục tiêu". Phương thức này được điền sẵn trong phân đoạn yêu cầu TargetEndpoint kèm theo URL yêu cầu được gửi đến mục tiêu phụ trợ. Nếu cố gắng 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 biến đó nằm trong phạm vi, thì proxy sẽ không làm gì cả – không tạo lỗi và không đặt biến.

Sau đây là một ví dụ đơn giản minh hoạ cách suy nghĩ về phạm vi của biến. Giả sử bạn muốn sao chép toàn bộ nội dung của một đối tượng yêu cầu (tiêu đề, tham số, nội dung) và gán nội dung đó cho tải trọng phản hồi để gửi lại ứng dụng gọi. Bạn có thể sử dụng SpecifyMessage policy (chính sách gán 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à bạn phải đặt biến này 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 biến flow

Tất cả biến tích hợp sẵn 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 dành riêng nhiều tiền tố để sắp xếp các biến có liên quan một cách thích hợp. Các tiền tố này bao gồm:

request
response
system
target

Để tham chiếu đến một biến trong 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 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 là 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 phải sử dụng 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 flow trong mã JavaScript và Java. Để biết thêm thông tin, hãy xem các bài viết sau:

Loại dữ liệu của biến flow

Mỗi thuộc tính của biến flow có một loại dữ liệu được xác định rõ ràng, chẳng hạn như String, Long, Integer, Boolean hoặc Collection. 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 flow. Đối với các biến do 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 sẽ giả định kiểu dữ liệu đã cung cấp 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 bị giới hạn ở các biến Số, Chuỗi, Boolean, rỗng hoặc không xác định.

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

Nhiều chính sách tạo biến flow trong quá trình thực thi thông thường. Tài liệu tham khảo về 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 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 để làm gì. Ví dụ: Chính sách 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 hạn mức, thời gian hết hạn, v.v.

Một số biến chính sách hữu ích cho việc gỡ lỗi. Ví dụ: bạn có thể sử dụng công cụ Trace tool (Công cụ theo dõi) để xem 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ừ tin nhắn vào 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à dữ liệu khác. Ví dụ: bạn có thể phân tích cú pháp yêu cầu và tin nhắn phản hồi bằng cách sử dụng các mẫu để trích xuất dữ liệu cụ thể từ các tin nhắn đó.

Trong ví dụ sau, hàm Trích xuất biến phân tích cú pháp một 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 hai biến tuỳ chỉnh là geocoderesponse.latitude và geocoderesponse.longitude, đồng thời gán 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 lưu ý rằng nhiều chính sách tự động tạo ra các biến. Bạn có thể truy cập vào các biến đó trong ngữ cảnh luồng proxy. Những biến đó được nêu trong Tài liệu tham khảo về chính sách trong từng chủ đề chính sách.

Làm việc với biến flow trong mã JavaScript

Bạn có thể truy cập và thiết lập các biến trực tiếp trong mã JavaScript đang thực thi trong bối cảnh một proxy API. Thông qua mô hình đối tượng JavaScript của Apigee, 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 vào 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 sau đây:

context
proxyRequest
proxyResponse
targetRequest
targetResponse

Như bạn có thể thấy, các tệp tham chiếu đối tượng này liên kết với 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 phần Hình dung luồng của proxy API.

Đối tượng context tương ứng với các biến có sẵn "toàn cục", 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 để lấy 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 một biến tuỳ chỉnh hoặc cho mọi biến có thể ghi ngay từ đầu. Ở đây, chúng ta sẽ 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 đối tượng này sẽ có sẵn cho tất cả các phân đoạn luồng (về cơ bản, việc này giống như việc tạo biến toàn cục).

Bạn cũng có thể nhận/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 vào 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. Bạn chỉ cần "yêu cầu" 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 biến flow trong Node.js.

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

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

Một số biến "có sẵn" được tạo thực thể và điền tự động bởi chính proxy. Các biến này được ghi lại trong Tài liệu tham khảo về biến Flow.
Bạn có thể tạo các biến tuỳ chỉnh để sử dụng trong luồng proxy. Bạn có thể tạo biến bằng các chính sách như chính sách AssignMessage và chính sách JavaScript, cũng như trong mã Node.js.
Biến có phạm vi. Ví dụ: một số biến được tự động điền 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 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 chưa được xác định cho đến khi phân đoạn phản hồi thực thi.
Khi thực thi, chính sách có thể tạo và điền các biến dành riêng cho chính sách. Tài liệu cho từng chính sách liệt kê tất cả các biến liên quan theo chính sách.
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õ về 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ể một biến do một chính sách này tạo ra sau đó lại được một chính sách khác sử dụng.
Bạn có thể lấy và đặt nhiều biến luồng từ bên trong Node.js bằng cách sử dụng JavaScript trực tiếp (và mô hình đối tượng JavaScript) hoặc chính sách JavaCallout. Chính sách này sẽ thực thi mã trên Edge.

Mã mẫu liên quan

Các mẫu proxy API có trên GitHub và rất 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 các mẫu. Hãy xem Danh sách mẫu để biết nội dung mô tả về các mẫu proxy API và chức năng của các mẫu đó.

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

biến – Minh hoạ cách trích xuất và đặt biến dựa trên nội dung thông điệp JSON, XML và nội dung truyền tải.
policy-mashup-cookbook – Một ứng dụng hoàn chỉnh sử dụng thành phần chính sách để gọi hai API công khai, kết hợp kết quả và tạo phản hồi phong phú cho ứng dụng khách. Để biết thêm thông tin về mẫu này, hãy xem phần Sử dụng thành phần chính sách.
conditional-policy – Triển khai việc 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ả các biến được tự động điền trong proxy API đều được liệt kê trong Tài liệu tham khảo về biến Flow. Tài liệu tham khảo này cũng liệt kê loại và phạm vi của từng biến.
Nếu bạn muốn biết chính sách cụ thể sẽ điền biến nào, hãy tham khảo chủ đề tham khảo cho chính sách đó. Ví dụ: hãy xem Biến luồng trong tài liệu tham khảo về Chính sách hạn mức.