Kiểm soát cách một proxy thực thi với các 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

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

Flow 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ự do luồng chỉ định. Khi xác định một điều kiện để chỉ định liệu có thực thi logic hay không 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 luồng sau đây xác định một luồng trong đó chính sách VerifyAPIKey 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 flow đóng vai trò 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 flow

Bạn định cấu trúc luồng để 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 sẽ chọn thêm logic đó vào điểm cuối proxy hay điểm cuối mục tiêu. Proxy API phân chia mã của proxy đó giữa mã tương tác với máy khách của 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 đích).

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

Loại thiết bị đầu cuối Mô tả Các luồng được hỗ trợ
ProxyEndpoint Chứa các luồng proxy API gần nhất với ứng dụng. Cung cấp các vị trí để logic hành động trước tiên theo yêu cầu từ ứng dụng, sau đó cuối cùng trên phản hồi gửi đến ứng dụng. PreFlow, luồng có điều kiện, PostFlow, PostClientFlow
TargetEndpoint Chứa các luồng proxy API 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ừ tài nguyên phụ trợ. PreFlow, quy trình có điều kiện, PostFlow

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

Yêu cầu từ máy khách HTTP truyền Điểm cuối proxy đến Điểm cuối mục tiêu trên phần phụ trợ để truy cập vào dịch vụ HTTP. Mỗi bảng điều khiển yêu cầu và phản hồi cho thấy luồng trước, luồng có điều kiện và luồng sau. Ngoài ra, chúng tôi cũng cung cấp ví dụ về điểm cuối proxy và điểm cuối mục tiêu.

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

Vị trí Loại quy trình Mô tả
1 PreFlow

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

Nếu PreFlow nằm trong một điểm cuối mục tiêu, thì quy trình này sẽ thực thi sau PostFlow của điểm cuối proxy.
2 Luồng có điều kiện

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

Chỉ 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 flow có điều kiện trong mỗi:
  • 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à một nơi phù hợp để ghi lại dữ liệu, gửi thông báo về việc đã xảy ra sự cố trong khi xử lý yêu cầu, v.v. Thực thi sau các 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ì PostFlow của điểm cuối proxy sẽ thực thi trước PreFlow của điểm cuối mục tiêu.
4 PostClientFlow (chỉ luồng proxy) Một quy trình để ghi nhật ký thông điệp sau khi phản hồi được trả về máy khách.

Chạy mã trước bằng PreFlow

PreFlow rất hữu ích khi bạn cần đảm bảo rằng một số mã nhất định được thực thi trước khi đ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 khách và hạn chế lưu lượng truy cập từ ứng dụng khách. Trong một điểm cuối mục tiêu khi bắt đầu chuẩn bị gửi yêu cầu đến một mục tiêu phụ trợ, PreFlow là lựa chọn phù hợp cho các bước đầu tiên khi chuẩn bị gửi yêu cầu.

Ví dụ: bạn thường không muốn phục vụ một ứng dụng đã vượt quá hạn mức. Để hỗ trợ các yêu cầu này, bạn sẽ đặt các chính sách bảo mật và hạn mức vào phân đoạn PreFlow. Nhờ đó, bạn không cần lo lắng về việc một điều kiện không đánh giá được 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 thực thi trước khi diễn ra bất kỳ quá trình xử lý nào khác.

Trong ví dụ sau, các chính sách SpikeArrest và Hạn mức sẽ thực thi trước khi xử lý các lượt chuyển sang các 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>

Yêu cầu thực thi mã có điều kiện bằng 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. Cách này giúp bạn có cơ hội đị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 của proxy. Bạn không bắt buộc phải sử dụng luồng có điều kiện nếu có thể thực thi tất cả logic trong PreFlow hoặc PostFlow mà 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 flow chỉ định một điều kiện kiểm tra các giá trị trạng thái khác nhau. Thao tác này phân nhánh thực thi hiệu quả dựa trên các điều kiện. Ví dụ: có thể bạn 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.

Tại đây, các quy tắc hạn mức chỉ được thực thi nếu yêu cầu là yêu cầu GET có mẫu URI là /issue/** (/issue/ với bất kỳ nội dung 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 biến flow để chỉ định điều kiện. Để biết thêm thông tin về cách sử dụng biến trong điều kiện, hãy xem bài viết Điều kiện có biến luồng.

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

Yêu cầu thực thi mã sau logic cốt lõi bằng PostFlow

PostFlow là một nơi tuyệt vời để 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 phù hợp để ghi nhật ký một số dữ liệu, gửi thông báo về một sự kiện nào đó, chuyển đổi định dạng thông báo phản hồi, v.v.

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

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

Yêu cầu thực thi mã sau khi máy khách nhận được phản hồi của proxy bằng PostClientFlow

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

* Chính sách FlowAnnotation chỉ có thể gọi các luồng chia sẻ mà bản thân các luồng đó đáp ứng các tiêu chí để được đưa vào PostClientFlow (tức là chỉ chứa các chính sách tương thích).

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

PostClientFlow phù hợp để 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.

Dưới đây là 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 hướng dẫn bạn 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 flow

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. Giống như các flow thực thi theo một trình tự (PreFlow rồi đến Flow rồi đến PostFlow, như mô tả trong chủ đề này), nội dung của một flow sẽ thực thi theo trình tự.

Cấu hình luồng ví dụ sau đây tham chiếu đến 3 chính sách (được định cấu hình ở nơi khác trong các tệp XML riêng). Chính sách mà Verify-API-Key tham chiếu sẽ thực thi trước chính sách được Remove-API-Key tham chiếu; cả hai đều theo sau là 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 trình tự chính sách này dưới dạng một hàng biểu tượng, trong đó mỗi biểu tượng đại diện cho một chính sách.

Bảng điều khiển Apigee Edge trình bày trình tự các chính sách này dưới dạng một hàng biểu tượng, trong đó 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ụ Apigee Edge Trace cung cấp một phương thức đồ hoạ để xem cách logic trong proxy API của bạn thực thi theo một yêu cầu. Công cụ này minh hoạ quá trình xử lý giữa yêu cầu và phản hồi. Ví dụ này không minh hoạ cụ thể sự khác biệt giữa PreFlow, flow có điều kiện và PostFlow.

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

Xử lý lỗi trong flow

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

Ví dụ sau đây là đoạn mã phản hồi từ mộ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ụ này, lỗi sẽ xuất hiện 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 về cách xử lý lỗi, hãy xem phần Xử lý lỗi.