Kiểm soát cách proxy thực thi với các luồng

Bạn đang xem tài liệu về Apigee Edge.
Hãy xem tài liệu về Apigee X.

Mọi mô hình lập trình ứng dụng đều có cách kiểm soát luồng xử lý. Trong một proxy API, quy trình đó được thực hiện thông qua flow. Đối với flow, bạn sẽ thêm logic, câu lệnh điều kiện, xử lý lỗi, v.v. Bạn sử dụng luồng để kiểm soát những gì xảy ra và thời điểm.

Luồng là các giai đoạn tuần tự dọc theo đường dẫn xử lý yêu cầu API. Khi thêm logic proxy, chẳng hạn như xác minh khoá API, bạn sẽ thêm logic đó làm một bước trong trình tự được chỉ định bởi một flow. Khi xác định một điều kiện để chỉ định xem liệu và khi nào logic thực thi, bạn sẽ thêm điều kiện đó vào một luồng.

Ví dụ về cấu hình flow sau đây xác định một luồng trong đó chính sách VerificationAPIKey thực thi nếu đường dẫn yêu cầu đến kết thúc bằng / và động từ HTTP của yêu cầu là GET.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Giá trị Verify-API-Key trong phần tử <Name> của luồng sẽ bao gồm một chính sách được định cấu hình ở nơi khác trong proxy bằng XML, chẳng hạn như sau:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Thiết kế trình tự thực thi luồng

Bạn sắp xếp cấu trúc của các luồng này để có thể thực thi logic theo đúng trình tự dọc theo đường dẫn xử lý.

Khi quyết định vị trí thêm logic, trước tiên, bạn cần chọn thêm điểm cuối đó vào điểm cuối proxy hay điểm cuối mục tiêu. Proxy API chia mã tương tác giữa mã tương tác với ứng dụng proxy (điểm cuối proxy) và mã không bắt buộc tương tác với mục tiêu phụ trợ của proxy, nếu có (điểm cuối mục tiêu).

Cả hai điểm cuối đều chứa flow, như được mô tả ở đây:

Loại điểm cuối Mô tả Luồng được hỗ trợ
ProxyEndpoint Chứa các luồng proxy API gần ứng dụng nhất. Cung cấp các vị trí để logic thực hiện hành động đầu tiên theo yêu cầu của ứng dụng, sau đó là phản hồi cuối cùng từ ứng dụng. PreFlow, luồng có điều kiện, PostFlow, PostClientFlow
Điểm cuối Mục tiêu Chứa các luồng API proxy gần nhất với tài nguyên phụ trợ. Cung cấp các vị trí để logic chuẩn bị yêu cầu, sau đó xử lý phản hồi từ một tài nguyên phụ trợ. PreFlow, luồng có điều kiện, PostFlow

Bạn định cấu hình luồng với XML chỉ định điều gì sẽ xảy ra và theo thứ tự nào. Hình minh hoạ sau đây cho thấy cách sắp xếp các luồng theo tuần tự trong điểm cuối proxy và điểm cuối mục tiêu:

Yêu cầu từ ứng dụng HTTP truyền qua Điểm cuối Proxy tới Điểm cuối Mục tiêu trên phần phụ trợ để truy cập dịch vụ HTTP. Mỗi yêu cầu và bảng điều khiển phản hồi hiển thị luồng trước, luồng có điều kiện và luồng bài đăng. Ngoài ra, bạn cũng có thể xem ví dụ về điểm cuối proxy và điểm cuối mục tiêu.

Mỗi điểm cuối proxy và điểm cuối mục tiêu đều chứa các luồng mà bạn có thể sắp xếp theo trình tự sau:

Vị trí Loại luồng Mô tả
1 PreFlow

Hữu ích khi bạn cần đảm bảo rằng một số mã thực thi trước khi bất kỳ thao tác nào khác xảy ra.

Nếu nằm trong một điểm cuối mục tiêu, PreFlow sẽ thực thi sau PostFlow của điểm cuối proxy.

2 Luồng có điều kiện

Vị trí dành cho logic có điều kiện. Thực thi sau PreFlow và trước PostFlow.

Chỉ có một luồng có điều kiện được thực thi cho mỗi phân đoạn – luồng đầu tiên có điều kiện được đánh giá là true. Điều đó có nghĩa là bạn có thể thực thi một luồng có điều kiện như một phần của:
  • Quy trình yêu cầu của ProxyEndpoint
  • Quy trình yêu cầu của TargetEndpoint
  • Quy trình phản hồi của ProxyEndpoint
  • Quy trình phản hồi của TargetEndpoint
3 PostFlow

Đây là nơi phù hợp để ghi nhật ký dữ liệu, gửi thông báo cho biết đã xảy ra sự cố khi xử lý yêu cầu, v.v. Thực thi sau luồng có điều kiện và PreFlow.

Nếu PostFlow nằm trong một điểm cuối proxy và có một điểm cuối mục tiêu, thì điểm cuối proxy PostFlow sẽ thực thi trước điểm cuối PreFlow của mục tiêu.

4 PostClientFlow (chỉ dành cho luồng proxy) Quy trình ghi nhật ký thư sau khi phản hồi được trả về máy khách.

Để thực thi mã trước tiên bằng PreFlow

PreFlow rất hữu ích khi bạn cần đảm bảo rằng một số mã thực thi trước khi bất kỳ điều gì khác xảy ra.

Trong điểm cuối proxy, PreFlow là một nơi tuyệt vời để mã xác thực ứng dụng và hạn chế lưu lượng truy cập từ ứng dụng. Trong điểm cuối mục tiêu, khi nó bắt đầu chuẩn bị gửi yêu cầu đến một mục tiêu phụ trợ, PreFlow sẽ rất hữu ích cho các bước đầu tiên để chuẩn bị gửi yêu cầu.

Ví dụ: bạn thường không muốn phục vụ khách hàng đã vượt quá hạn ngạch của dịch vụ đó. Để hỗ trợ các yêu cầu này, bạn cần đưa các chính sách bảo mật và hạn mức vào phân khúc PreFlow. Bằng cách đó, bạn không cần phải lo lắng về việc một điều kiện không thể đánh giá trong một luồng có điều kiện sau này. Các chính sách trong quy trình này sẽ luôn được thực thi trước khi các quy trình xử lý khác diễn ra.

Trong ví dụ sau, các chính sách SpikeArrest và Quota được thực thi trước khi xử lý các luồng đến luồng có điều kiện.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Có mã thực thi có điều kiện với luồng có điều kiện

Giữa PreFlow và PostFlow, bạn có thể có các flow thực thi có điều kiện. Điều này cho phép bạn định cấu hình nhiều chuỗi logic, nhưng chỉ có một chuỗi được thực thi dựa trên trạng thái proxy của bạn. Không bắt buộc phải có flow có điều kiện nếu bạn có thể thực thi tất cả logic trong PreFlow hoặc PostFlow và không cần có điều kiện nào (nói cách khác, chỉ hỗ trợ một đường dẫn qua điểm cuối).

Mỗi luồng chỉ định một điều kiện kiểm thử các giá trị trạng thái khác nhau. Việc này giúp thực thi nhánh một cách hiệu quả dựa trên các điều kiện. Ví dụ: bạn có thể chỉ muốn chuyển đổi XML sang JSON khi ứng dụng yêu cầu đang chạy trên thiết bị di động.

Ở đây, các hạn chế đối với hạn mức chỉ được thực thi nếu yêu cầu là một yêu cầu GET có mẫu URI là /issue/** (/issue/ với bất kỳ giá trị nào trong URI sau dấu gạch chéo lên cuối cùng).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Bạn sử dụng các biến luồng để chỉ định điều kiện. Để biết thêm về cách sử dụng biến trong điều kiện, hãy xem phần Điều kiện có biến luồng.

Để biết ví dụ về cách sử dụng phương thức khớp mẫu trong các điều kiện, hãy xem phần So khớp mẫu.

Việc thực thi mã sau logic cốt lõi với PostFlow

PostFlow là một nơi rất phù hợp để thực hiện các hành động sau logic cốt lõi của điểm cuối và trước khi quá trình xử lý điểm cuối kết thúc. PostFlow thực thi sau các luồng có điều kiện và PreFlow.

PostFlow là một nơi lý tưởng để ghi nhật ký một số dữ liệu, gửi thông báo về sự kiện đã xảy ra, chuyển đổi định dạng thông báo phản hồi, v.v.

Trong ví dụ sau, một chính sáchassignMessage có tên SetResponseHeaders đặt các tiêu đề của thông báo phản hồi trước khi Apigee Edge gửi thông tin phản hồi về ứng dụng.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Việc thực thi mã sau khi ứng dụng nhận được phản hồi của proxy của bạn với PostClientFlow

PostClientFlow có thể bao gồm những chính sách sau:

* Chính sách FlowChú thích chỉ có thể gọi các luồng chia sẻ mà chính nó đáp ứng các tiêu chí để nằm trong PostClientFlow (tức là chỉ chứa các chính sách tương thích).

Nếu bạn đưa vào một phản hồi, thì PostClientFlow sẽ là luồng cuối cùng cần thực thi, thực thi sau khi một phản hồi được gửi đến ứng dụng.

PostClientFlow rất phù hợp cho việc ghi nhật ký cuối cùng. Ngoài ra, bạn có thể ghi lại dấu thời gian bắt đầu và kết thúc cho tin nhắn phản hồi.

Đây là một ví dụ về PostClientFlow có chính sách MessageLogging được đính kèm.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

Video: Xem video ngắn này để biết cách tạo PostClientFlow bằng chính sách MessageLogging trong loạt video Four Minute Video For Developers (4MV4D).

Để biết thêm thông tin, hãy xem các bài viết sau:

Thêm logic vào luồng

Khi thêm logic vào proxy, bạn thực hiện việc này bằng cách thêm chính sách vào luồng của proxy. Cũng giống như các flow thực thi theo trình tự (PreFlow rồi Flow rồi PostFlow, như mô tả trong chủ đề này), nội dung của một flow thực thi theo một trình tự.

Ví dụ sau đây định cấu hình luồng tham chiếu ba chính sách (được định cấu hình ở nơi khác trong tệp XML của chính sách). Chính sách được Verify-API-Key tham chiếu sẽ thực thi trước chính sách mà Remove-API-Key tham chiếu; cả hai đều tuân theo chính sách do Quota biểu thị.

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Bảng điều khiển Apigee Edge trình bày chuỗi chính sách này dưới dạng một hàng biểu tượng mà mỗi biểu tượng đại diện cho chính sách.

Bảng điều khiển Apigee Edge trình bày chuỗi chính sách này dưới dạng một hàng biểu tượng mà mỗi biểu tượng đại diện cho chính sách. Các biểu tượng xuất hiện trên đường dẫn yêu cầu bao gồm: Xác minh khoá API, Xoá khoá API và Hạn mức

Gỡ lỗi luồng

Công cụ Theo dõi cạnh Apigee cung cấp một cách đồ hoạ để xem cách logic trong proxy API thực thi theo yêu cầu. Công cụ này minh họa quá trình xử lý giữa yêu cầu và phản hồi. Tài liệu này không minh hoạ cụ thể sự phân tách giữa PreFlow, flow có điều kiện và PostFlow.

Để biết thêm về proxy theo dõi, hãy xem Sử dụng công cụ Theo dõi.

Xử lý lỗi trong luồng

Bạn có thể gặp lỗi từ nhiều vị trí trong proxy API, kể cả từ luồng.

Ví dụ sau đây là khổ thơ phản hồi từ PreFlow trong một điểm cuối mục tiêu – nói cách khác là mã sẽ thực thi ngay khi nhận được phản hồi từ một mục tiêu phụ trợ. Trong ví dụ, một lỗi được nêu ra nếu phản hồi từ mục tiêu không phải là 200 (thành công).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Để biết thêm thông tin về cách xử lý lỗi, hãy xem phần Xử lý lỗi.