Chính sách Bộ nhớ đệm phản hồi

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

Lưu dữ liệu vào bộ nhớ đệm từ một tài nguyên phụ trợ, giảm số lượng yêu cầu đối với tài nguyên đó. Khi các ứng dụng đưa ra yêu cầu đến cùng một URI, bạn có thể sử dụng chính sách này để trả về các phản hồi được lưu vào bộ nhớ đệm thay vì chuyển tiếp các yêu cầu đó đến máy chủ phụ trợ. Chính sách ResponseCache có thể cải thiện hiệu suất API của bạn thông qua việc giảm độ trễ và lưu lượng truy cập mạng.

Bạn có thể thấy ResponseCache hữu ích nhất khi dữ liệu phụ trợ mà API của bạn sử dụng chỉ được cập nhật định kỳ. Ví dụ: giả sử bạn có một API chỉ cập nhật dữ liệu báo cáo thời tiết sau mỗi 10 phút. Bằng cách sử dụng ResponseCache để trả về các phản hồi được lưu vào bộ nhớ đệm giữa các lần làm mới, bạn có thể giảm số lượng yêu cầu đến phần phụ trợ. Điều này cũng làm giảm số lượng bước nhảy mạng.

Đối với hoạt động lưu vào bộ nhớ đệm ngắn hạn cho mục đích chung, hãy cân nhắc sử dụng chính sách Điền vào bộ nhớ đệm. Chính sách đó được dùng cùng với chính sách Tra cứu bộ nhớ đệm (để đọc các mục trong bộ nhớ đệm) và chính sách Vô hiệu hoá bộ nhớ đệm (để vô hiệu hoá các mục).

Mẫu

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778

'http://{org_name}-test.apigee.net/weather/forecastrss?w=23424778' -H "bypass-cache:true"

<ResponseCache name="ResponseCache">
    <CacheKey>
        <KeyFragment ref="request.queryparam.w" />
    </CacheKey>
    <!-- Explicitly refresh the cached response -->
    <SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>
    <ExpirySettings>
        <TimeoutInSeconds>600</TimeoutInSeconds>
    </ExpirySettings>
</ResponseCache>

Tài liệu tham khảo về phần tử

Tài liệu tham khảo về phần tử mô tả các phần tử và thuộc tính của chính sách.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">
    <DisplayName>Response Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref="request.uri" />
    </CacheKey>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <ExpiryDate/>
        <TimeOfDay/>
        <TimeoutInSeconds ref="flow.variable.here">300</TimeoutInSeconds>
    </ExpirySettings>
    <CacheResource>cache_to_use</CacheResource>
    <CacheLookupTimeoutInSeconds/>
    <ExcludeErrorResponse/>
    <SkipCacheLookup/>
    <SkipCachePopulation/>
    <UseAcceptHeader/>
    <UseResponseCacheHeaders/>
</ResponseCache>

Thuộc tính <ResponseCache>

<ResponseCache async="false" continueOnError="false" enabled="true" name="Response-Cache-1">

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

&lt;DisplayName&gt; phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>

Phần tử <CacheKey>

Định cấu hình một con trỏ duy nhất cho một phần dữ liệu được lưu trữ trong bộ nhớ đệm.

Khoá bộ nhớ đệm có kích thước tối đa là 2 KB.

<CacheKey>
    <Prefix>string</Prefix>
    <KeyFragment ref="variable_name" />
    <KeyFragment>literal_string</KeyFragment>
</CacheKey>

<CacheKey> tạo tên cho từng phần dữ liệu được lưu trữ trong bộ nhớ đệm. Khoá thường được đặt bằng cách sử dụng một giá trị từ tiêu đề thực thể hoặc tham số truy vấn. Trong những trường hợp đó, bạn sẽ có thuộc tính ref của phần tử chỉ định một biến chứa giá trị khoá.

Trong thời gian chạy, các giá trị <KeyFragment> được thêm vào trước bằng giá trị phần tử <Scope> hoặc giá trị <Prefix>. Ví dụ: kết quả sau đây sẽ tạo ra một khoá lưu vào bộ nhớ đệm là UserToken__apiAccessToken__<value_of_client_id>:

<CacheKey>
    <Prefix>UserToken</Prefix>
    <KeyFragment>apiAccessToken</KeyFragment>
    <KeyFragment ref="request.queryparam.client_id" />
</CacheKey>

Bạn sử dụng phần tử <CacheKey> cùng với <Prefix> và <Scope>. Để biết thêm thông tin, hãy xem phần Xử lý khoá bộ nhớ đệm.

Phần tử <CacheLookupTimeoutInSeconds>

Chỉ định số giây sau đó một lần tra cứu bộ nhớ đệm không thành công sẽ được coi là một lần thiếu bộ nhớ đệm. Nếu điều này xảy ra, luồng sẽ tiếp tục dọc theo đường dẫn thiếu bộ nhớ đệm.

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

Phần tử <CacheResource>

Chỉ định bộ nhớ đệm nơi lưu trữ thư. Bỏ qua phần tử này để dùng bộ nhớ đệm dùng chung đi kèm. Bạn nên chỉ định một CacheResource theo tên nếu muốn có thể xoá các mục có trong bộ nhớ đệm theo cách quản trị. Để biết thêm thông tin về vấn đề này, hãy xem phần Bộ nhớ đệm.

<CacheResource>cache_to_use</CacheResource>

Để biết thêm thông tin về cách định cấu hình bộ nhớ đệm, hãy xem phần Tạo và chỉnh sửa bộ nhớ đệm môi trường.

Phần tử <CacheKey>/<KeyFragment>

Chỉ định một giá trị cần được đưa vào khoá bộ nhớ đệm, tạo một không gian tên để so khớp các yêu cầu với các phản hồi được lưu vào bộ nhớ đệm.

<KeyFragment ref="variable_name"/>
<KeyFragment>literal_string</KeyFragment>

Đây có thể là một khoá (tên tĩnh mà bạn cung cấp) hoặc một giá trị (một mục nhập động do bạn đặt bằng cách tham chiếu đến một biến). Tất cả các đoạn được chỉ định kết hợp (cộng với tiền tố) được nối để tạo khoá bộ nhớ đệm.

<KeyFragment>apiAccessToken</KeyFragment>
<KeyFragment ref="request.queryparam.client_id" />

Bạn sử dụng phần tử <KeyFragment> cùng với <Prefix> và <Scope>. Để biết thêm thông tin, hãy xem phần Xử lý khoá bộ nhớ đệm.

Thuộc tính

Phần tử <CacheKey>/<Prefix>

Chỉ định một giá trị để dùng làm tiền tố khoá bộ nhớ đệm.

<Prefix>prefix_string</Prefix>

Hãy sử dụng giá trị này thay vì <Scope> khi bạn muốn chỉ định giá trị của riêng mình thay vì giá trị được liệt kê <Scope>. Nếu được xác định, <Prefix> sẽ thêm giá trị khoá của bộ nhớ đệm vào các mục được ghi vào bộ nhớ đệm. Giá trị phần tử <Prefix> sẽ thay thế giá trị phần tử <Scope>.

Bạn sử dụng phần tử <Prefix> cùng với <CacheKey> và <Scope>. Để biết thêm thông tin, hãy xem phần Xử lý khoá bộ nhớ đệm.

Phần tử <ExcludeErrorResponse>

Hiện tại, theo mặc định, chính sách này lưu phản hồi HTTP vào bộ nhớ đệm với bất kỳ mã trạng thái nào có thể. Điều đó có nghĩa là cả phản hồi thành công và phản hồi lỗi đều được lưu vào bộ nhớ đệm. Ví dụ: theo mặc định, các phản hồi có cả mã trạng thái 2xx và 3xx đều được lưu vào bộ nhớ đệm.

Đặt phần tử này thành true nếu bạn không muốn lưu vào bộ nhớ đệm các phản hồi mục tiêu có mã trạng thái lỗi HTTP; chỉ những phản hồi có mã trạng thái từ 200 đến 205 mới được lưu vào bộ nhớ đệm nếu phần tử này là true. Đây là những mã trạng thái HTTP duy nhất mà Edge tính là mã "thành công" và bạn không thể thay đổi mối liên kết này.

Để xem nội dung thảo luận về các mẫu Bộ nhớ đệm phản hồi mà phần tử này hữu ích, hãy xem bài đăng này trên cộng đồng.

Lưu ý: Trong một bản phát hành sắp tới (sẽ được xác định), chế độ cài đặt mặc định của phần tử này sẽ thay đổi thành true. Hãy xem Ghi chú phát hành của Apigee để biết thông tin chi tiết.

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Phần tử <ExpirySettings>

Chỉ định thời điểm một mục trong bộ nhớ đệm sẽ hết hạn. Khi có mặt, <TimeoutInSeconds> sẽ ghi đè cả <TimeOfDay> và <ExpiryDate>.

<ExpirySettings>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
</ExpirySettings>

Phần tử <ExpirySettings>/<ExpiryDate>

Chỉ định ngày mà một mục trong bộ nhớ đệm sẽ hết hạn. Sử dụng biểu mẫu mm-dd-yyyy. Khi xuất hiện, phần tử anh chị em của phần tử này (<TimeoutInSeconds>) sẽ ghi đè <ExpiryDate>.

<ExpirySettings>
    <ExpiryDate ref="{date_variable}">expiration_date</ExpiryDate>
</ExpirySettings>

Thuộc tính

<ExpiryDate ref="" />

Phần tử <ExpirySettings>/<TimeOfDay>

Thời điểm trong ngày mà một mục nhập trong bộ nhớ đệm sẽ hết hạn. Sử dụng biểu mẫu hh:mm:ss . Khi xuất hiện, phần tử anh chị em của phần tử này (<TimeoutInSeconds>) sẽ ghi đè <TimeOfDay>.

Nhập thời gian trong ngày theo định dạng HH:mm:ss, trong đó HH là giờ theo đồng hồ 24 giờ. Ví dụ: 14:30:00 cho 2:30 chiều.

Đối với thời gian trong ngày, vùng và múi giờ mặc định sẽ thay đổi tuỳ thuộc vào nơi mã đang chạy (không thể biết được khi bạn định cấu hình chính sách). Để biết thông tin về cách định cấu hình ngôn ngữ, hãy xem phần Tạo và chỉnh sửa bộ nhớ đệm môi trường.

<ExpirySettings>
    <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

Thuộc tính

Phần tử <ExpirySettings>/<TimeoutInSec>

Số giây sau đó một mục trong bộ nhớ đệm sẽ hết hạn.

Phần tử <ExpirySettings>/<TimeoutInSeconds>

Số giây sau đó một mục trong bộ nhớ đệm sẽ hết hạn. Khi xuất hiện, phần tử này sẽ ghi đè các phần tử cùng cấp của nó, <TimeOfDay> và <ExpiryDate>.

<ExpirySettings>
    <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
</ExpirySettings>

Lưu ý: Cung cấp giá trị thời gian chờ mặc định để sử dụng nếu ref không nhận được giá trị từ duration_variable.

Thuộc tính

Phần tử <Scope>

Liệt kê dùng để tạo tiền tố cho khoá bộ nhớ đệm khi phần tử <Prefix> không được cung cấp trong phần tử <CacheKey>.

<Scope>scope_enumeration</Scope>

Chế độ cài đặt <Scope> xác định một khoá bộ nhớ đệm được thêm vào theo giá trị <Scope>. Ví dụ: khoá bộ nhớ đệm sẽ có dạng sau khi phạm vi được đặt thành Exclusive: orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [serializedCacheKey ].

Nếu phần tử <Prefix> xuất hiện trong <CacheKey>, thì phần tử này sẽ thay thế giá trị của phần tử <Scope>. Các giá trị hợp lệ bao gồm các giá trị liệt kê bên dưới.

Bạn sử dụng phần tử <Scope> cùng với <CacheKey> và <Prefix>. Để biết thêm thông tin, hãy xem phần Xử lý khoá bộ nhớ đệm.

Giá trị được chấp nhận

apifactory__test__weatherapi__16__default__apiAccessToken

Phần tử <SkipCacheLookup>

Xác định một biểu thức. Nếu biểu thức này đánh giá là true tại thời gian chạy, thì biểu thức đó sẽ chỉ định rằng quá trình tra cứu bộ nhớ đệm sẽ bị bỏ qua và bộ nhớ đệm sẽ được làm mới. Xem thêm video này về cách sử dụng SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Trong ví dụ sau, nếu biến bypass-cache được đặt thành true trong tiêu đề đến, thì quá trình tra cứu bộ nhớ đệm sẽ bị bỏ qua và bộ nhớ đệm sẽ được làm mới.

<SkipCacheLookup>request.header.bypass-cache = "true"</SkipCacheLookup>

Phần tử <SkipCachePopulation>

Xác định một biểu thức. Nếu biểu thức này đánh giá là đúng trong thời gian chạy, thì biểu thức này sẽ chỉ định rằng thao tác ghi vào bộ nhớ đệm sẽ bị bỏ qua. Bạn cũng có thể xem video này về cách sử dụng SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Ví dụ: mã sau đây sẽ bỏ qua thao tác ghi vào bộ nhớ đệm nếu mã trạng thái phản hồi là 400 trở lên:

<SkipCachePopulation>response.status.code >= 400</SkipCachePopulation>

Phần tử <UseAcceptHeader>

Đặt thành true để khoá bộ nhớ đệm của mục trong bộ nhớ đệm phản hồi được thêm vào các giá trị từ tiêu đề Chấp nhận phản hồi.

Edge sử dụng tiêu đề yêu cầu Accept, Accept-Encoding, Accept-Language và Accept-Charset khi tính toán khoá bộ nhớ đệm. Phương pháp này giúp ngăn ứng dụng nhận được loại nội dung nghe nhìn mà ứng dụng không yêu cầu.

Ví dụ: hãy xem xét trường hợp có 2 yêu cầu đến từ cùng một URL, trong đó yêu cầu đầu tiên chấp nhận gzip và yêu cầu thứ hai thì không. Yêu cầu đầu tiên sẽ được lưu vào bộ nhớ đệm và mục trong bộ nhớ đệm (có thể) sẽ là một phản hồi được nén bằng gzip. Yêu cầu thứ hai sẽ đọc giá trị được lưu vào bộ nhớ đệm và sau đó có thể trả về một mục được nén gzip cho một máy khách không có khả năng đọc gzip.

Hãy xem phần Định cấu hình khoá bộ nhớ đệm để biết thêm thông tin.

<UseAcceptHeader>false</UseAcceptHeader>

Phần tử <UseResponseCacheHeaders>

Đặt thành true để xem xét tiêu đề phản hồi HTTP khi đặt "thời gian tồn tại" (TTL) của phản hồi trong bộ nhớ đệm. Khi điều này đúng, Edge sẽ xem xét các giá trị của tiêu đề phản hồi sau, so sánh các giá trị đó với những giá trị do <ExpirySettings> đặt khi đặt thời gian tồn tại:

• Cache-Control s-maxage
• Cache-Control max-age
• Expires

Hãy xem phần Đặt thời gian hết hạn của mục trong bộ nhớ đệm để biết thêm thông tin chi tiết.

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

Lưu ý về cách sử dụng

Kích thước tối đa cho mỗi đối tượng được lưu vào bộ nhớ đệm là 256 KB. (Để biết thông tin chi tiết về cách Edge xử lý bộ nhớ đệm, hãy xem bài viết Thông tin nội bộ về bộ nhớ đệm.)

Thông qua cấu hình trong chính sách ResponseCache, bạn có thể yêu cầu Edge đưa các tiêu đề phản hồi HTTP vào việc thiết lập thời gian hết hạn của mục nhập trong bộ nhớ đệm và khoá bộ nhớ đệm. Phần này mô tả cách bạn có thể sử dụng chính sách này với các tiêu đề để quản lý thời gian hết hạn của bộ nhớ đệm và khoá bộ nhớ đệm.

Để biết thêm về cách Edge xử lý tiêu đề phản hồi bằng chính sách ResponseCache, hãy xem phần Hỗ trợ tiêu đề phản hồi HTTP.

Đặt thời gian hết hạn cho mục trong bộ nhớ đệm

Tương tự như chính sách Điền vào bộ nhớ đệm, bạn có thể đặt thời gian hết hạn của mục trong bộ nhớ đệm phản hồi (thời gian tồn tại) bằng cách sử dụng phần tử <ExpirySettings>. Trong chính sách ResponseCache, bạn cũng có thể yêu cầu Edge xem xét các tiêu đề phản hồi khi chúng xuất hiện.

Để sử dụng tiêu đề phản hồi, bạn đặt giá trị phần tử <UseResponseCacheHeaders> thành true. Chế độ cài đặt đó khiến Edge xem xét các tiêu đề phản hồi, so sánh chúng với giá trị do <ExpirySettings> đặt, sau đó sử dụng giá trị thấp nhất trong hai giá trị. Khi xem xét tiêu đề phản hồi, Edge sẽ chọn giá trị có sẵn như mô tả trong phần sau:

Ví dụ: giả sử một phản hồi được lưu vào bộ nhớ đệm với các giá trị sau:

• Không có giá trị Cache-Control s-maxage
• Giá trị Cache-Control max-age là 300
• Ngày Expires sau 3 ngày nữa
• Giá trị <ExpirySettings> TimeoutInSeconds là 600.

Trong trường hợp này, giá trị Cache-Control max-age sẽ được dùng cho TTL vì giá trị này thấp hơn giá trị <ExpirySettings> và vì không có giá trị Cache-Control s-maxage (giá trị này sẽ được ưu tiên hơn max-age).

Định cấu hình khoá bộ nhớ đệm

Giống như các chính sách bộ nhớ đệm cho mục đích chung (chẳng hạn như chính sách Điền vào bộ nhớ đệm), với ResponseCache, bạn sử dụng các phần tử <CacheKey> và <Scope> để định cấu hình việc tạo khoá bộ nhớ đệm cho các mục trong bộ nhớ đệm. Với ResponseCache, bạn cũng có thể tạo các khoá bộ nhớ đệm có ý nghĩa hơn bằng cách thêm tiêu đề Chấp nhận phản hồi vào các giá trị khoá.

Để biết thông tin chung về cách định cấu hình khoá bộ nhớ đệm, hãy xem bài viết Sử dụng khoá bộ nhớ đệm. Để biết thông tin về cách sử dụng tiêu đề Accept, hãy xem <UseAcceptHeader>.

Giới thiệu về tính năng mã hoá bộ nhớ đệm

Edge for Public Cloud: Bộ nhớ đệm chỉ được mã hoá trong các tổ chức có hỗ trợ PCI và HIPAA. Hoạt động mã hoá cho những tổ chức đó được định cấu hình trong quá trình cung cấp tổ chức.

Biến dòng

Các biến Flow được xác định trước sau đây sẽ được điền khi một chính sách ResponseCache được thực thi. Để biết thêm thông tin về các biến trong luồng, hãy xem phần Tài liệu tham khảo về biến.

Mã lỗi

Phần này mô tả các thông báo lỗi và biến luồng được thiết lập khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng mà bạn cần biết nếu đang phát triển các quy tắc lỗi cho một proxy. Để tìm hiểu thêm, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Tiền tố mã lỗi

Không áp dụng

Lỗi thời gian chạy

Chính sách này không gửi bất kỳ lỗi thời gian chạy nào.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách này.

Biến lỗi

Không áp dụng

Ví dụ về phản hồi lỗi

Không áp dụng

Giản đồ

Mỗi loại chính sách được xác định bằng một giản đồ XML (.xsd). Để tham khảo, bạn có thể xem giản đồ chính sách trên GitHub.