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.
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 của mình hoặc phần mềm tiện ích (chẳng hạn như Công cụ theo dõi). Chúng cho phép bạn duy trì trạng thái được 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 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à theo dõi trạng thái trong một API giao dịch 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. Kho lưu trữ biến luồng 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 như ngày và giờ khi Edge nhận được yêu cầu
Dữ liệu được thu thập khi một chính sách thực thi. Ví dụ: sau khi một chính sách thực thi mà xác thực một Mã thông báo OAuth, Edge tạo các biến luồng chứa thông tin như tên của yêu cầu .
Thông tin về phản hồi của hệ thống mục tiêu

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

Như bạn sẽ thấy, phạm vi của các biến phụ thuộc một phần vào thời điểm truy cập vào biến đều được tạo trong luồng proxy API. Nói 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ơ quan.
Ví dụ: chính sáchVerifyJWT có thể truy xuất mã thông báo được xác minh từ một biến luồng rồi thực hiện xác minh trên biến đó. Một 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 để điều hướng luồng của một API qua Edge, đại loại như cách câu lệnh chuyển đổi hoạt động 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 thiết lập. Cuối cùng, bạn có thể nhận và đặt các biến luồng trong ứng dụng đích Node.js.

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

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

Một số chính sách được áp dụng làm dữ liệu đầu vào.

Ví dụ: Chính sách chỉ định sau đây sẽ lấy giá trị của biến luồng client.ip rồi đặt biến đó vào tiêu đề yêu cầu có tên là 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 trong quy trình phản hồi, thì tiêu đề sẽ được gửi quay 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 thực thi một Chính sách về hạn mức, một số biến luồng sẽ được điền sẵn có các giá trị liên quan đến chính sách. Một trong những biến số này là có tên 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 này, bạn có thể thực thi luồng có điều kiện có nội dung là "nếu số lượng hạn mức hiện tại dưới 50% mức tối đa và nằm trong khoảng từ 9 giờ sáng đến 5 giờ chiều, thì sẽ có 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à trên biến luồng có tên system.time, một trong các Edge được tích hợp sẵn biến.

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

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. Các điều kiện thường được sử dụng để thay đổi hành vi của các luồng, bước và quy tắc định tuyến.

Sau đây là một quy trình 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 sử 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 rằng các biến như request.verb nằm ở đâu, client.ip và system.time đến từ đâu? Thời điểm tạo thực thể và có điền giá trị không? Để giúp bạn biết khi nào biến được tạo và khi nào biến đó được tạo có sẵn cho bạn, hãy xem phần Tìm hiểu về biến luồng phạm vi.

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

Với chính sách JavaScript, bạn có thể thực thi mã JavaScript từ bên trong ngữ cảnh của một Luồng proxy API. JavaScript (được thực thi theo chính sách này) có sử dụng Apigee Mô hình đối tượng JavaScript 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 được liên kết với Luồng proxy API nơi 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"));

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 bằng chính sáchassignMessage (hiển thị trước đó). Chỉ là một cách khác để hoàn thành nhiệm vụ mọi thứ trên Edge. Điều cần nhớ là JavaScript được thực thi theo chính sách JavaScript 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ể thiết lập 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 đặt, biến mới này sẽ được cung cấp 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 quy trình hoặc "vòng đời" tổng thể của proxy API .

Trực quan hoá luồng proxy API

Để hiểu phạm vi của biến luồng, bạn cần phải hiểu hoặc trình bày trực quan cách thông điệp thông qua 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 luồng. Tại mỗi bước trong luồng proxy, proxy sẽ đánh giá thông tin có sẵn cho và quyết định các bước cần làm 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ự luồng này. Lưu ý đến cách các flow bao gồm 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 ý 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 bạn có thể hình dung cách thông điệp di chuyển qua proxy, như đã mô tả ở trên, 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 điểm trong vòng đời luồng proxy khi một biến được tạo thực thể lần đầu tiên.

Ví dụ: nếu bạn có chính sách đính kèm với Phân đoạn yêu cầu ProxyEndpoint, chính sách đó sẽ không thể truy cập vào bất kỳ biến nào phạm vi phân đoạn yêu cầu TargetEndpoint. Nguyên nhân là do TargetEndpoint phân đoạn yêu cầu 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 ở trong proxy mà chúng trở nên khả dụng.

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 thông qua toàn bộ vòng đời luồng proxy.

Ví dụ: có một biến Edge được tích hợp sẵn tên là client.ip. Biến này có "yêu cầu proxy" phạm vi. URL này được tự động điền bằng địa chỉ IP của ứng dụng khách có tên là 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 tiên và sau đó giữ nguyên sẵn có trong toàn bộ vòng đời luồng proxy.

Có một biến tích hợp 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 đã gửi cho mục tiêu phụ trợ. Nếu bạn cố truy cập vào target.url trong yêu cầu ProxyEndpoint bạn sẽ nhận được giá trị NULL. Nếu bạn cố đặt biến này trước khi thuộc phạm vi áp dụng, proxy không làm gì được—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 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 đối tượng đó cho tải trọng phản hồi này để gửi lại cho ứng dụng gọi. Bạn có thể dùng chính sách AssignmentsMessage (Chỉ định) cho nhiệm 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? Chiến lược phát hành đĩa đơn câu trả lời là nó phải được đặt trên phản hồi TargetEndpoint, vì phạm vi của biến phản hồi là "mục tiêu phản hồi".

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

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

Apigee đặt trước 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 chính sách, hãy đặt biến đó trong dấu ngoặc nhọn. Ví dụ: chính sáchChỉ định sau đây nhận giá trị của biến client.ip và đặt mã đó 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 các luồng có điều kiện, không cần dấu ngoặc nhọn. Điều kiện ví dụ sau đây ước tính 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 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 Bộ sưu tậ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 flow. Đối với biến do chính sách tạo ra, 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 được cung cấp khi chúng được tạo và phụ thuộc vào dựa trên các loại giá trị được cho phép. Ví dụ: các biến được tạo trong mã Node.js là bị hạn chế ở 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 các biến luồng trong quá trình thực thi thông thường. Tài liệu Tài liệu tham khảo về chính sách tất cả các biến theo chính sách cụ thể 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 chính sách để tìm hiểu các biến được tạo và mục đích sử dụng các biến đó. Cho 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 hạn mức 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ể sử dụng công cụ Theo dõi để xem biến nào được đặt tại phiên bản cụ thể trong luồng proxy.

Chính sách ExtractVariables cho phép bạn điền sẵn dữ liệu trích xuất từ các tin nhắn vào các biến tuỳ chỉnh. Bạn có thể trích xuất truy vấn tham số, 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à thông báo phản hồi bằng cách dùng các mẫu để trích xuất dữ liệu cụ thể từ tin nhắn.

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

<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 trong ngữ cảnh luồng proxy và các 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 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à thiết lập các biến ngay trong mã JavaScript đang thực thi theo ngữ cảnh của proxy API. Thông qua mô hình đối tượng JavaScript của Apigee, việc thực thi JavaScript trên Edge đã 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 tham chiếu đối tượng này ánh xạ tớ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 đây trong Hình ảnh luồng của proxy API.

Đối tượng context tương ứng với "trên toàn cầu" các biến có sẵn, chẳng hạn như hệ thống biến. Ví dụ: bạn có thể gọi getVariable() trên đối tượng context để xem 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 sẵn dùng có thể ghi. Ở đây, chúng ta tạo một biến tuỳ chỉnh được gọi là organization.name.myorg rồi gán giá trị cho thuộc tính đó.

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 để 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 Java Chú thích.

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. Tất cả những gì bạn cần cần làm là "yêu cầu" mô-đun truy cập apigee trong mã của bạn. Để 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ớ

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

Một số sản phẩm "dùng ngay" các biến được proxy tạo thực thể và điền tự động . Các vấn đề này được nêu 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 có sẵn để sử dụng trong luồng proxy. Có khả năng để tạo biến bằng cách sử dụng các chính sách như chính sách GánTin 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 tự động điền khi proxy đầu tiên sẽ nhận yêu cầu từ ứng dụng. Các biến khác được điền sẵn vào quy trình phản hồi phân đoạn 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 sẵn các biến theo chính sách. Chiến lược phát hành đĩa đơn 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.
Luồng có điều kiện thường đánh giá một hoặc nhiều biến. Bạn cần phải hiểu nếu bạn 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 được tạo bởi sau đó chính sách được sử dụng bởi một người dùng khác.
Bạn có thể nhận và đặt nhiều biến luồng từ bên trong Node.js bằng cách sử dụng JavaScript thẳng (và mô hình đối tượng JavaScript của chúng tôi) hoặc chính sách JavaAnnotation (chính sách này 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ề việc tải xuống và sử dụng mẫu. Hãy xem Danh sách mẫu để biết nội dung mô tả về API mẫu proxy và những gì chúng làm.

Những proxy mẫu 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 phương thức truyền tải cũng như thông báo JSON và XML nội dung.
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 các kết quả và tạo ra phản hồi chi tiết hơn cho ứng dụng . Để biết thêm thông tin về mẫu này, hãy xem Chính sách sử dụng cấu trúc.
conditional-policy – chính sách có điều kiện Triển khai biện pháp 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 trong proxy API đượ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 một chính sách cụ thể điền những biến nào, hãy tham khảo tài liệu về 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 về hạn mức.