Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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 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 các chính sách hoặc tiện ích của mình (chẳng hạn như công cụ Trace tool). Các chính sách 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 trong luồng là gì?

Các biến luồng tồn tại trong ngữ cảnh của một luồng proxy API và chúng theo dõi trạng thái trong một giao dịch API theo cách mà 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. Các biến luồng lưu trữ 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 một yêu cầu
Dữ liệu được lấy khi một chính sách thực thi. Ví dụ: sau khi thực thi một chính sách xác thực mã thông báo OAuth, Edge sẽ tạo các biến luồng giữ thông tin như tên của ứng dụng yêu cầu.
Thông tin về phản hồi của hệ thống đích

Một số biến được "tích hợp" vào Edge và được tự động điền bất cứ khi nào nhận được một yêu cầu API. Các thông tin này có sẵn trong suốt giao dịch API. Bạn cũng có thể tạo các 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ư chính sách AssignMessage hoặc trong mã JavaScript, Node.js và Java.

Như bạn sẽ thấy, các biến có phạm vi và nơi có thể truy cập vào các biến này phụ thuộc một phần vào thời điểm chúng được tạo trong quy trình 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 quy trình giao dịch API.

Các biến trong 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:

Các chính sách có thể truy xuất trạng thái từ các biến luồng và sử dụng chúng để thực hiện công việc.
Ví dụ: chính sách VerifyJWT có thể truy xuất mã thông báo cần xác minh từ một biến luồng, sau đó thực hiện quy trình xác minh trên mã thông báo đó. 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 để điều hướng luồng của một API thông qua Edge, tương tự 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 có thể chỉ thực thi khi một biến luồng cụ thể được đặt. Cuối cùng, bạn có thể nhận và đặt các biến luồng trong một ứng dụng đích Node.js.

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

Các biến luồng 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 luồng client.ip và đặt giá trị đó vào một tiêu đề của yêu cầu có tên là My-Client-IP. Nếu được thêm vào quy trình request, chính sách này sẽ đặt một tiêu đề được truyền đến đích đến phụ trợ. Nếu được đặt trên luồng phản hồi, tiêu đề sẽ được gửi lại cho ứ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 sẽ được điền sẵn 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 luồng có điều kiện cho biết "nếu số lượng hạn mức hiện tại dưới 50% 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à vào 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.

Biến quy trình trong quy trình 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 luồng, bước và quy tắc định 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 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ì chính sách VerifyAPIKey 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>

Có thể bạn đang thắc mắc các biến như request.verb, client.ip và system.time đến từ đâu? Khi nào chúng được khởi tạo và điền sẵn một giá trị? Để giúp bạn hiểu rõ thời điểm biến được tạo và thời điểm biến có sẵn cho bạn, hãy xem phần 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 trong ngữ cảnh của một 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 của bạn vào các đối tượng yêu cầu, phản hồi và ngữ cảnh được liên kết với quy trình 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 với 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 các biến này tương tự như nhữ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ùng một loại việc 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ả các biến luồng hiện có và nằm trong phạm vi trong luồng proxy API.

Các biến luồng 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 luồng từ trong mã Node.js được triển khai đến Edge.

Dưới đây là một ví dụ đơn giản trong đó một biến có tên là custom.foo được đặt thành giá trị Bar. Sau khi được thiết lập, biến mới này sẽ có sẵn cho mọi chính sách hoặc mã khác xuất hiện trong quy trình 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 Truy cập vào các biến luồng trong Node.js.

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

Phạm vi biến có liên quan đến quy trình 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 một proxy API

Để hiểu phạm vi của biến luồng, bạn cần hiểu hoặc hình dung cách các thông báo truyền qua một proxy API. Một 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 quy trình uỷ quyền, 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ạ chuỗi các luồng này. Lưu ý cách các 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 ý 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 quan hệ giữa phạm vi biến và luồng proxy

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

Ví dụ: nếu bạn có một chính sách được đí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 được giới hạn trong phân đoạn yêu cầu TargetEndpoint. Lý do là vì phân đoạn yêu cầu TargetEndpoint của quy trình chưa được thực thi, nên API proxy 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ộ các phạm vi biến và cho biết thời điểm chúng có sẵn trong quy trình proxy.

Phạm vi biến	Nơi các biến này được điền sẵn
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 của proxy	Phân đoạn phản hồi ProxyEndpoint
luôn có sẵn	Ngay khi 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". Tham số này sẽ tự động được điền sẵn địa chỉ IP của ứng dụng khách đã gọi proxy. Tham số này được điền sẵn khi một yêu cầu lần đầu tiên truy cập vào ProxyEndpoint và vẫn có sẵn trong toàn bộ vòng đời của luồng proxy.

Có một biến được tạo sẵn 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". Tham số này được điền sẵn trong phân đoạn yêu cầu TargetEndpoint bằng URL yêu cầu được gửi đến mục tiêu phụ trợ. Nếu cố gắng truy cập 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 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à chỉ định nội dung đó cho tải trọng phản hồi sẽ được gửi lại cho ứng dụng gọi. Bạn có thể sử dụng chính sách AssignMessage cho tác vụ này. Mã chính sách sẽ 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à chỉ định đối tượng đó cho đối tượng response. Nhưng chính sách này nên được đặt ở đâu trong quy trình 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 các biến trong quy trình

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 dành riêng nhiều tiền tố để sắp xếp các biến 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 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 một tiêu đề của 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 các luồng có điều kiện, bạn không cần 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 luồng 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 các biến trong quy trình

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

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

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

Nhiều chính sách tạo ra các biến luồng trong quá trình thực thi bình thường. Tài liệu Thông tin tham khảo về chính sách liệt kê tất cả các biến cụ thể theo 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 những biến số nào được tạo và mục đích sử dụng của chúng. Ví dụ: Chính sách về hạn mức tạo ra một tập hợp các biến chứa thông tin về số lượng và 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 để xem những biến nào được đặt tại một phiên bản cụ thể trong một luồng proxy.

Chính sách ExtractVariables cho phép bạn điền các biến tuỳ chỉnh bằng dữ liệu được trích xuất từ các thông báo. Bạn có thể trích xuất 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 các thông báo yêu cầu và 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 thông báo.

Trong ví dụ sau, thao tác Trích xuất biến sẽ phân tích 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 ra 2 biến tuỳ chỉnh, geocoderesponse.latitude và geocoderesponse.longitude, rồ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, hãy lưu ý rằng nhiều chính sách tự động tạo các biến. Bạn có thể truy cập vào các biến đó trong ngữ cảnh luồng proxy và chúng được ghi lại trong Tài liệu tham khảo về 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 bối cảnh của một proxy API. Thông qua mô hình đối tượng JavaScript của Apigee, JavaScript thực thi trên Edge có quyền truy cập trực tiếp vào các biến luồng của proxy.

Để truy cập vào các biến trong mã JavaScript, hãy gọi các 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 liên kết đế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 phần Hình dung luồng của một proxy API.

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

Bạn cũng có thể nhận/đặt các biến luồng proxy trong mã Java mà bạn thực thi bằng chính sách JavaCallout.

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 khỏi mã Node.js được triển khai đến Edge. Bạn chỉ cần "require" mô-đun apigee-access trong mã của mình. Để biết thông tin chi tiết, hãy xem bài viết Truy cập vào các biến luồng trong Node.js.

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

Sau đâ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" được thực hiện và điền sẵn tự động bởi chính proxy. Những biến 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 để sử dụng trong quy trình 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ư chính sách AssignMessage và chính sách JavaScript, cũng như trong mã Node.js.
Các 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, các chính sách có thể tạo và điền các biến cụ thể theo chính sách. Tài liệu cho mỗi chính sách liệt kê tất cả các biến cụ thể theo chính sách có liên quan này.
Các 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 các biến làm đầu vào hoặc đầu ra. Có thể một biến do một chính sách tạo ra sau này sẽ được một chính sách khác sử dụng.
Bạn có thể nhận và đặt nhiều biến luồng trong Node.js bằng cách sử dụng JavaScript thuần tuý (và mô hình đối tượng JavaScript của chúng tôi) hoặc chính sách JavaCallout. Chính sách này 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 các 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 chúng.

Sau đây là các proxy mẫu có tính năng sử dụng biến và xử lý biến:

variables – Minh hoạ cách trích xuất và đặt các biến dựa trên nội dung thông báo truyền tải, JSON và XML.
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 ra một 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 một 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 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ể nào sẽ điền những biến số nào, hãy tham khảo chủ đề tham chiếu cho chính sách đó. Ví dụ: hãy xem Biến luồng trong tài liệu tham khảo Chính sách về hạn mức.