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

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về 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 vào tài nguyên. Khi các ứng dụng gửi 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 những 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 của API bằng cách giảm độ trễ và lưu lượng truy cập mạng.

Bạn có thể sẽ 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 cho thấy dữ liệu báo cáo thời tiết chỉ được làm mới 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 gửi đến phần phụ trợ. Điều này cũng làm giảm số bước mạ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 sử dụng cùng với chính sách Tra cứu bộ nhớ đệm (để đọc các mục nhập bộ nhớ đệm) và Chính sách Vô hiệu hoá bộ nhớ đệm (để vô hiệu hoá các mục nhập).

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>

Tham chiếu phần tử

Tham chiếu 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ả các thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Phần tử <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Phần tử <CacheKey>

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

Khoá bộ nhớ đệm được giới hạn kích thước 2 KB.

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

<CacheKey> tạo tên của từng phần dữ liệu được lưu trữ trong bộ nhớ đệm. Khoá thường được thiết lập bằng cách sử dụng 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ẽ để thuộc tính tham chiếu 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 giá trị phần tử <Scope> hoặc giá trị <Prefix>. Ví dụ: các đoạn mã sau đây dẫn đến khoá bộ nhớ đệm của UserToken__apiAccessToken__<value_of_client_id>:

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

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

Phần tử <CacheLookupTimeoutInSeconds>

Chỉ định số giây mà sau đó một lần tra cứu bộ nhớ đệm không thành công sẽ bị coi là thiếu bộ nhớ đệm. Nếu điều này xảy ra, quy trình sẽ tiếp tục theo đường dẫn bỏ lỡ 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 để sử dụng bộ nhớ đệm dùng chung đi kèm. Bạn nên chỉ định CacheResource theo tên nếu muốn xoá các mục nhập có trong bộ nhớ đệm về mặt quản trị. Để biết thêm thông tin về nội dung này, hãy xem 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 bài viết Tạo và chỉnh sửa bộ nhớ đệm của môi trường.

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

Chỉ định một giá trị cần đư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 phản hồi đã lưu vào bộ nhớ đệm.

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

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

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

Bạn sẽ sử dụng phần tử <KeyFragment> cùng với <Prefix> và <Scope>. Để biết thêm thông tin, hãy xem bài viết 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ị liệt kê <Scope>. Nếu được xác định, <Prefix> sẽ thêm giá trị khoá bộ nhớ đệm cho các mục được ghi vào bộ nhớ đệm. Giá trị phần tử <Prefix> ghi đè giá trị phần tử <Scope>.

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

Phần tử <ExcludeErrorResponse>

Hiện tại, theo mặc định, chính sách này sẽ lưu các phản hồi HTTP vào bộ nhớ đệm chứa bất kỳ mã Trạng thái nào. Đ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ụ: các phản hồi có cả mã trạng thái 2xx và 3xx sẽ được lưu vào bộ nhớ đệm theo mặc định.

Đặt phần tử này thành true nếu bạn không muốn lưu các phản hồi mục tiêu có mã trạng thái HTTP vào bộ nhớ đệm; 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à các 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.

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

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

<ExcludeErrorResponse>true</ExcludeErrorResponse>

Phần tử <ExpirySettings>

Chỉ định thời điểm hết hạn một mục trong bộ nhớ đệm. Khi có, <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 hết hạn cho một mục trong bộ nhớ đệm. Sử dụng biểu mẫu mm-dd-yyyy. Nếu có, thành phần đồng cấp 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 gian trong ngày mà mục nhập bộ nhớ đệm sẽ hết hạn. Sử dụng biểu mẫu hh:mm:ss . Nếu có, thành phần đồng cấp 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 thể hiện giờ trên đồng hồ 24 giờ. Ví dụ: 14:30:00 cho 2:30 chiều.

Đối với thời gian trong ngày, ngôn ngữ và múi giờ mặc định sẽ thay đổi tuỳ thuộc vào nơi mã đang chạy (không biết được khi định cấu hình chính sách này). Để biết thông tin về cách định cấu hình ngôn ngữ, hãy xem bài viết Tạo và chỉnh sửa bộ nhớ đệm của 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ục nhập trong bộ nhớ đệm sẽ hết hạn.

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

Số giây sau đó mục nhập trong bộ nhớ đệm sẽ hết hạn. Khi có, phần tử này sẽ ghi đè các thành phần đồng cấp là <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 tham chiếu không nhận được giá trị từ duration_variable.

Thuộc tính

Phần tử <Scope>

Thuật toán 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 khoá bộ nhớ đệm được thêm vào trước theo giá trị <Scope>. Ví dụ: khoá bộ nhớ đệm sẽ có dạng như sau khi phạm vi được đặt thành Exclusive: orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ].

Nếu có phần tử <Prefix> trong <CacheKey>, phần tử này sẽ thay thế giá trị phần tử <Scope>. Giá trị hợp lệ bao gồm những giá trị liệt kê dưới đây.

Bạn sẽ sử dụng phần tử <Scope> cùng với <CacheKey> và <Prefix>. Để biết thêm thông tin, hãy xem bài viết 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 mà nếu có giá trị true trong thời gian chạy, thì biểu thức này sẽ chỉ định rằng nên bỏ qua quá trình tra cứu bộ nhớ đệm và làm mới bộ nhớ đệm. Ngoài ra, hãy xem video này về cách sử dụng SkipCacheLookup.

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

Từ ví dụ sau, nếu biến bỏ qua bộ nhớ đệm đượ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 mà nếu có giá trị true trong thời gian chạy, thì biểu thức này sẽ chỉ định rằng cần bỏ qua thao tác ghi vào bộ nhớ đệm. Ngoài ra, hãy xem video này về cách sử dụng SkipCachePopulation.

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

Ví dụ: thao tác sau đây sẽ bỏ qua quá trình 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 để nối thêm khoá bộ nhớ đệm của mục nhập bộ nhớ đệm phản hồi cùng các giá trị từ tiêu đề Chấp nhận của phản hồi.

Edge sử dụng các 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 ngăn khách hàng nhận được loại nội dung đa phương tiện mà họ không yêu cầu.

Ví dụ: hãy xem xét liệu hai yêu cầu có xuất phát từ cùng một URL hay không, trong đó yêu cầu đầu tiên chấp nhận tệp gzip còn 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 nhập đã lưu vào bộ nhớ đệm (có thể) sẽ là một phản hồi được nén. Yêu cầu thứ hai sẽ đọc giá trị đã lưu trong bộ nhớ đệm và sau đó có thể trả về một mục đã nén cho ứng dụng khách không thể đọc tệp gzip.

Xem bài viết Đị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 để các tiêu đề phản hồi HTTP được xem xét 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 giá trị của các tiêu đề phản hồi sau đây, so sánh các giá trị với các giá trị do <ExpirySettings> thiết lập khi thiết lập thời gian tồn tại:

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

Hãy xem bài viết Đặt thời gian hết hạn của mục 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 của 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, vui lòng xem phần Bộ nhớ đệm nội bộ.)

Thông qua cấu hình trong chính sách ResponseCache, bạn có thể yêu cầu Edge bao gồm các tiêu đề phản hồi HTTP trong quá trình đặt thời hạn của mục nhập bộ nhớ đệm và khoá bộ nhớ đệm. Phần này mô tả rằng bạn có thể sử dụng chính sách 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ý các tiêu đề phản hồi bằng chính sách ResponseCache, hãy xem bài viết Hỗ trợ các tiêu đề phản hồi HTTP.

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

Tương tự như với Chính sách điền bộ nhớ đệm, bạn có thể đặt ngày hết hạn của một mục bộ nhớ đệm phản hồi (thời gian hoạt động của mục đó) 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 có các tiêu đề này.

Để sử dụng tiêu đề phản hồi, bạn cầ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 với giá trị do <ExpirySettings> đặt, sau đó sử dụng giá trị thấp nhất trong hai tiêu đề. Khi xem xét tiêu đề phản hồi, Edge sẽ chọn giá trị có sẵn như mô tả sau đây:

Ví dụ: hãy tưởng tượng một phản hồi được lưu vào bộ nhớ đệm bằng 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 (được ưu tiên hơn max-age).

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

Tương tự như các chính sách bộ nhớ đệm cho mục đích chung như Điền chính sách 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ể làm cho các khoá bộ nhớ đệm trở nên ý nghĩa hơn bằng cách thêm các tiêu đề Accept (Chấp nhận) của 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 Làm việc với khoá bộ nhớ đệm. Để biết thông tin về cách sử dụng tiêu đề Chấp nhận, 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 hỗ trợ PCI và HIPAA. Mã hoá cho các tổ chức đó được định cấu hình trong quá trình cấp phép tổ chức.

Biến luồng

Các biến Luồng (Flow) định sẵn sau đây được điền sẵn khi thực thi chính sách ResponseCache. Để biết thêm thông tin về biến Flow, hãy xem bài viết 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). Giản đồ chính sách có sẵn trên GitHub để bạn tham khảo.