นโยบาย ResponseCache

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X info

แคชข้อมูลจากทรัพยากรแบ็กเอนด์เพื่อลดจำนวนคำขอไปยังทรัพยากร เมื่อแอปส่งคำขอไปยัง URI เดียวกัน คุณสามารถใช้นโยบายนี้เพื่อแสดงผลการตอบกลับที่แคชไว้แทนที่จะส่งต่อคำขอเหล่านั้นไปยังเซิร์ฟเวอร์แบ็กเอนด์ นโยบาย ResponseCache จะช่วยปรับปรุงประสิทธิภาพของ API ผ่านการลดเวลาในการตอบสนองและการจราจรของข้อมูลในเครือข่าย

คุณน่าจะพบว่า ResponseCache มีประโยชน์มากที่สุดเมื่อข้อมูลแบ็กเอนด์ที่ API ใช้ได้รับการอัปเดต เป็นระยะๆ เท่านั้น เช่น สมมติว่าคุณมี API ที่แสดงข้อมูลรายงานสภาพอากาศ ซึ่งรีเฟรชทุก 10 นาทีเท่านั้น การใช้ ResponseCache เพื่อแสดงการตอบกลับที่แคชไว้ระหว่างการรีเฟรชจะช่วยลดจำนวนคำขอที่ส่งไปยังแบ็กเอนด์ได้ ซึ่งยังช่วยลด จำนวนการเปลี่ยนเส้นทางเครือข่ายด้วย

สำหรับการแคชระยะสั้นแบบทั่วไป ให้พิจารณาใช้นโยบายการป้อนข้อมูลแคช นโยบายดังกล่าวใช้ร่วมกับนโยบายแคชการค้นหา (สำหรับการอ่านรายการแคช) และ นโยบายล้างแคช (สำหรับการล้างรายการ)

ตัวอย่าง

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>

การอ้างอิงองค์ประกอบ

การอ้างอิงองค์ประกอบจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย

<?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>

แอตทริบิวต์ <ResponseCache>

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

ตารางต่อไปนี้อธิบายแอตทริบิวต์ทั่วไปในองค์ประกอบระดับบนสุดของนโยบายทั้งหมด

&lt;DisplayName&gt; องค์ประกอบ

ใช้เพิ่มเติมจากแอตทริบิวต์ name เพื่อติดป้ายกำกับนโยบายใน เครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติต่างกัน

<DisplayName>Policy Display Name</DisplayName>

องค์ประกอบ <CacheKey>

กำหนดค่าพอยน์เตอร์ที่ไม่ซ้ำกันไปยังข้อมูลที่จัดเก็บไว้ในแคช

คีย์แคชมีขนาดได้ไม่เกิน 2 KB

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

<CacheKey> สร้างชื่อของข้อมูลแต่ละชิ้นที่จัดเก็บไว้ในแคช โดยมักจะตั้งค่าคีย์โดยใช้ค่าจากส่วนหัวของเอนทิตีหรือพารามิเตอร์การค้นหา ในกรณีดังกล่าว คุณจะต้อง ให้แอตทริบิวต์ ref ขององค์ประกอบระบุตัวแปรที่มีค่าคีย์

ในรันไทม์ ระบบจะเพิ่มค่า <KeyFragment> ไว้หน้าค่าขององค์ประกอบ <Scope> หรือค่า <Prefix> ตัวอย่างเช่น ผลลัพธ์ต่อไปนี้จะทำให้เกิดคีย์แคชของ UserToken__apiAccessToken__<value_of_client_id>:

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

คุณใช้องค์ประกอบ <CacheKey> ร่วมกับ <Prefix> และ <Scope> ดูข้อมูลเพิ่มเติมได้ที่การทำงานกับคีย์แคช

องค์ประกอบ <CacheLookupTimeoutInSeconds>

ระบุจำนวนวินาทีหลังจากนั้นระบบจะถือว่าการค้นหาแคชที่ไม่สำเร็จเป็น ไม่พบแคช หากเกิดกรณีนี้ขึ้น โฟลว์จะกลับมาทำงานตามเส้นทางที่ไม่พบแคช

<CacheLookupTimeoutInSeconds>30</CacheLookupTimeoutInSeconds>

องค์ประกอบ <CacheResource>

ระบุแคชที่ควรจัดเก็บข้อความ ละเว้นองค์ประกอบนี้เพื่อใช้แคชที่แชร์ที่รวมไว้ คุณควรระบุ CacheResource ตามชื่อหากต้องการล้างรายการที่อยู่ในแคชในระดับการดูแลระบบ ดูข้อมูลเพิ่มเติมได้ที่แคช

<CacheResource>cache_to_use</CacheResource>

ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าแคชได้ที่สร้างและแก้ไขแคชสภาพแวดล้อม

องค์ประกอบ <CacheKey>/<KeyFragment>

ระบุค่าที่ควรใส่ในคีย์แคชเพื่อสร้างเนมสเปซสำหรับการจับคู่คำขอที่แคชไว้กับคำตอบที่แคชไว้

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

ซึ่งอาจเป็นคีย์ (ชื่อแบบคงที่ที่คุณระบุ) หรือค่า (รายการแบบไดนามิกที่ตั้งค่าโดย อ้างอิงตัวแปร) ระบบจะต่อสตริงของส่วนที่ระบุทั้งหมดรวมกัน (รวมถึงคำนำหน้า) เพื่อ สร้างคีย์แคช

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

คุณใช้องค์ประกอบ <KeyFragment> ร่วมกับ <Prefix> และ <Scope> ดูข้อมูลเพิ่มเติมได้ที่การทำงานกับคีย์แคช

Attributes

องค์ประกอบ <CacheKey>/<Prefix>

ระบุมูลค่าที่จะใช้เป็นคำนำหน้าคีย์แคช

<Prefix>prefix_string</Prefix>

ใช้ค่านี้แทน <Scope> เมื่อต้องการระบุค่าของคุณเอง แทนค่าที่แจงนับ <Scope> หากกำหนดไว้ <Prefix> จะเพิ่มค่าคีย์แคชไว้หน้ารายการที่เขียนลงในแคช ค่าองค์ประกอบ <Prefix> จะลบล้างค่าองค์ประกอบ <Scope>

คุณใช้องค์ประกอบ <Prefix> ร่วมกับ <CacheKey> และ <Scope> ดูข้อมูลเพิ่มเติมได้ที่การทำงานกับคีย์แคช

องค์ประกอบ <ExcludeErrorResponse>

ปัจจุบันโดยค่าเริ่มต้น นโยบายนี้จะแคชการตอบกลับ HTTP ที่มีรหัสสถานะใดก็ได้ ซึ่งหมายความว่าทั้งการตอบกลับที่สำเร็จและข้อผิดพลาดจะได้รับการแคช เช่น การตอบกลับที่มีทั้งรหัสสถานะ 2xx และ 3xx จะได้รับการแคชโดยค่าเริ่มต้น

ตั้งค่าองค์ประกอบนี้เป็น true หากไม่ต้องการแคชการตอบกลับเป้าหมาย ที่มีรหัสสถานะข้อผิดพลาด HTTP เฉพาะการตอบกลับที่มีรหัสสถานะตั้งแต่ 200 ถึง 205 เท่านั้นที่จะ แคชหากองค์ประกอบนี้เป็นจริง รหัสสถานะ HTTP เหล่านี้เป็นรหัสสถานะ HTTP เพียงรหัสเดียวที่ Edge นับเป็นรหัส "สำเร็จ" และคุณจะเปลี่ยนการเชื่อมโยงนี้ไม่ได้

ดูการอภิปรายเกี่ยวกับรูปแบบแคชการตอบกลับที่องค์ประกอบนี้มีประโยชน์ได้ในโพสต์ชุมชนนี้

หมายเหตุ: ในรุ่นต่อๆ ไป (ซึ่งจะกำหนดในอนาคต) การตั้งค่าเริ่มต้นขององค์ประกอบนี้ จะเปลี่ยนเป็น "จริง" ดูรายละเอียดได้ที่บันทึกประจำรุ่นของ Apigee

<ExcludeErrorResponse>true</ExcludeErrorResponse>

องค์ประกอบ <ExpirySettings>

ระบุว่ารายการในแคชควรหมดอายุเมื่อใด หากมี <TimeoutInSeconds> จะลบล้างทั้ง <TimeOfDay> และ <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>

องค์ประกอบ <ExpirySettings>/<ExpiryDate>

ระบุวันที่ที่รายการแคชควรหมดอายุ ใช้แบบฟอร์ม mm-dd-yyyy เมื่อมีอยู่ <TimeoutInSeconds> ที่เป็นองค์ประกอบร่วมขององค์ประกอบนี้จะลบล้าง <ExpiryDate>

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

Attributes

<ExpiryDate ref="" />

องค์ประกอบ <ExpirySettings>/<TimeOfDay>

เวลาของวันที่รายการแคชควรหมดอายุ ใช้แบบฟอร์ม hh:mm:ss เมื่อมีอยู่ <TimeoutInSeconds> ที่เป็นองค์ประกอบร่วมขององค์ประกอบนี้จะลบล้าง <TimeOfDay>

ป้อนเวลาของวันในรูปแบบ HH:mm:ss โดยที่ HH แทนชั่วโมงในนาฬิกาแบบ 24 ชั่วโมง เช่น 14:30:00 สำหรับ 14:30 น.

สำหรับเวลาของวัน การตั้งค่าภาษาและเขตเวลาเริ่มต้นจะแตกต่างกันไปตามตำแหน่งที่โค้ดทำงาน (ซึ่งไม่สามารถทราบได้เมื่อคุณกำหนดค่านโยบาย) ดูข้อมูลเกี่ยวกับการกำหนดค่าภาษาได้ที่การสร้างและแก้ไขแคชสภาพแวดล้อม

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

Attributes

องค์ประกอบ <ExpirySettings>/<TimeoutInSec>

จำนวนวินาทีหลังจากที่รายการแคชควรหมดอายุ

องค์ประกอบ <ExpirySettings>/<TimeoutInSeconds>

จำนวนวินาทีหลังจากที่รายการแคชควรหมดอายุ เมื่อมีอยู่ องค์ประกอบนี้จะลบล้างองค์ประกอบที่เกี่ยวข้อง <TimeOfDay> และ <ExpiryDate>

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

หมายเหตุ: ระบุค่าการหมดเวลาเริ่มต้นที่จะใช้หาก ref ไม่ได้รับค่าจาก duration_variable

Attributes

องค์ประกอบ <Scope>

การแจงนับที่ใช้เพื่อสร้างคำนำหน้าสำหรับคีย์แคชเมื่อไม่ได้ระบุองค์ประกอบ <Prefix> ในองค์ประกอบ <CacheKey>

<Scope>scope_enumeration</Scope>

<Scope> จะกำหนดคีย์แคชที่นำหน้าตามค่า <Scope> เช่น คีย์แคชจะมีรูปแบบต่อไปนี้เมื่อตั้งค่า ขอบเขตเป็น Exclusive : orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

หากมีองค์ประกอบ <Prefix> ใน <CacheKey> องค์ประกอบดังกล่าวจะ แทนที่ค่าองค์ประกอบ <Scope> ค่าที่ใช้ได้รวมถึงการแจงนับ ด้านล่าง

คุณใช้องค์ประกอบ <Scope> ร่วมกับ <CacheKey> และ <Prefix> ดูข้อมูลเพิ่มเติมได้ที่การทำงานกับคีย์แคช

ค่าที่ยอมรับ

apifactory__test__weatherapi__16__default__apiAccessToken

องค์ประกอบ <SkipCacheLookup>

กำหนดนิพจน์ที่หากประเมินค่าเป็นจริงในขณะรันไทม์ จะระบุว่าควรข้ามการค้นหาแคช และควรรีเฟรชแคช ดูวิดีโอนี้เกี่ยวกับการใช้ SkipCacheLookup ด้วย

<SkipCacheLookup>variable_condition_expression</SkipCacheLookup>

จากตัวอย่างต่อไปนี้ หากตั้งค่าตัวแปร bypass-cache เป็น true ในส่วนหัวขาเข้า ระบบจะข้ามการค้นหาแคชและรีเฟรชแคช

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

องค์ประกอบ <SkipCachePopulation>

กำหนดนิพจน์ที่หากประเมินค่าเป็นจริงในขณะรันไทม์ จะระบุว่าควรข้ามการเขียนไปยังแคช โปรดดูวิดีโอนี้เกี่ยวกับการใช้ SkipCachePopulation ด้วย

<SkipCachePopulation>variable_condition_expression</SkipCachePopulation>

ตัวอย่างเช่น โค้ดต่อไปนี้จะข้ามการเขียนแคชหากรหัสสถานะการตอบกลับเป็น 400 หรือสูงกว่า

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

องค์ประกอบ <UseAcceptHeader>

ตั้งค่าเป็น true เพื่อให้ระบบผนวกคีย์แคชของรายการแคชการตอบกลับด้วยค่าจาก ส่วนหัว Accept ของการตอบกลับ

Edge ใช้ส่วนหัวของคำขอ Accept, Accept-Encoding, Accept-Language และ Accept-Charset เมื่อคำนวณคีย์แคช วิธีนี้ จะช่วยป้องกันไม่ให้ไคลเอ็นต์ได้รับประเภทสื่อที่ไม่ได้ขอ

ตัวอย่างเช่น ลองพิจารณาว่าหากมีคำขอ 2 รายการมาจาก URL เดียวกัน โดยคำขอแรก ยอมรับ gzip แต่คำขอที่ 2 ไม่ยอมรับ ระบบจะแคชคําขอแรก และรายการที่แคชไว้จะ (อาจ) เป็นการตอบกลับที่บีบอัดด้วย gzip คำขอที่ 2 จะอ่านค่าที่แคชไว้และอาจ แสดงผลรายการที่บีบอัดด้วย gzip ให้กับไคลเอ็นต์ที่อ่าน gzip ไม่ได้

ดูข้อมูลเพิ่มเติมได้ที่กำหนดค่าคีย์แคช

<UseAcceptHeader>false</UseAcceptHeader>

องค์ประกอบ <UseResponseCacheHeaders>

ตั้งค่าเป็น true เพื่อให้ระบบพิจารณาส่วนหัวการตอบกลับ HTTP เมื่อตั้งค่า "Time to Live" (TTL) ของการตอบกลับในแคช เมื่อเป็นจริง Edge จะพิจารณาค่าของส่วนหัวการตอบกลับต่อไปนี้ โดยเปรียบเทียบค่ากับค่าที่ตั้งค่าโดย <ExpirySettings> เมื่อตั้งค่า Time to Live

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

ดูรายละเอียดเพิ่มเติมได้ที่การตั้งค่าการหมดอายุของรายการแคช

<UseResponseCacheHeaders>false</UseResponseCacheHeaders>

หมายเหตุการใช้งาน

ขนาดสูงสุดของออบเจ็กต์ที่แคชแต่ละรายการคือ 256 KB (ดูข้อมูลโดยละเอียดเกี่ยวกับวิธีที่ Edge ประมวลผลแคชได้ที่ส่วนประกอบภายในของแคช)

คุณสามารถกำหนดค่าในนโยบาย ResponseCache เพื่อให้ Edge รวมส่วนหัวการตอบกลับ HTTP ในการตั้งค่าการหมดอายุของรายการแคชและคีย์แคช ส่วนนี้อธิบายวิธีใช้ นโยบายกับส่วนหัวเพื่อจัดการการหมดอายุของแคชและคีย์แคช

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่ Edge จัดการส่วนหัวการตอบกลับด้วยนโยบาย ResponseCache ได้ที่การรองรับส่วนหัวการตอบกลับของ HTTP

การตั้งค่าการหมดอายุของรายการแคช

เช่นเดียวกับนโยบายการป้อนข้อมูล แคช คุณสามารถตั้งค่าการหมดอายุของรายการแคชการตอบกลับ (Time to Live (TTL)) ได้โดยใช้ องค์ประกอบ <ExpirySettings> ในนโยบาย ResponseCache คุณยังให้ Edge พิจารณาส่วนหัวการตอบกลับได้ด้วยเมื่อมีส่วนหัวการตอบกลับ

หากต้องการใช้ส่วนหัวของการตอบกลับ ให้ตั้งค่าองค์ประกอบ <UseResponseCacheHeaders> เป็น true การตั้งค่านั้นทำให้ Edge พิจารณาเฮดเดอร์การตอบกลับ เปรียบเทียบกับค่าที่ตั้งโดย <ExpirySettings> แล้วใช้ค่าที่ต่ำที่สุดใน 2 ค่า เมื่อพิจารณาเฮดเดอร์การตอบกลับ Edge จะเลือกค่าที่มีอยู่ตามที่อธิบายไว้ในส่วนต่อไปนี้

เช่น สมมติว่ามีการแคชการตอบกลับด้วยค่าต่อไปนี้

• ไม่มีค่า Cache-Control s-maxage
• ค่า Cache-Control max-age เท่ากับ 300
• Expires ในอีก 3 วัน
• ค่า <ExpirySettings> TimeoutInSeconds เป็น 600

ในกรณีนี้ ระบบจะใช้ค่า Cache-Control max-age สำหรับ TTL เนื่องจากค่าดังกล่าวต่ำกว่าค่า <ExpirySettings> และเนื่องจากไม่มีค่า Cache-Control s-maxage (ซึ่งมีความสำคัญเหนือกว่า max-age)

การกำหนดค่าคีย์แคช

เช่นเดียวกับนโยบายแคชแบบอเนกประสงค์ เช่น นโยบายการป้อนข้อมูลแคช คุณใช้องค์ประกอบ <CacheKey> และ <Scope> กับ ResponseCache เพื่อ กำหนดค่าการสร้างคีย์แคชสำหรับรายการแคช นอกจากนี้ ResponseCache ยังช่วยให้คุณสร้างคีย์แคช ที่มีความหมายมากขึ้นได้ด้วยการต่อส่วนหัว Accept ของการตอบกลับเข้ากับค่าคีย์

ดูข้อมูลทั่วไปเกี่ยวกับการกำหนดค่าคีย์แคชได้ที่การทำงานกับคีย์แคช ดูข้อมูลเกี่ยวกับการใช้ส่วนหัว Accept ได้ที่ <UseAcceptHeader>

เกี่ยวกับการเข้ารหัสแคช

Edge สำหรับระบบคลาวด์สาธารณะ: ระบบจะเข้ารหัสแคชเฉพาะในองค์กรที่เปิดใช้ PCI และ HIPAA ระบบจะกำหนดค่าการเข้ารหัสสำหรับองค์กรเหล่านั้นในระหว่างการจัดสรร องค์กร

ตัวแปรโฟลว์

ระบบจะป้อนค่าตัวแปร Flow ที่กำหนดไว้ล่วงหน้าต่อไปนี้เมื่อมีการดำเนินการนโยบาย ResponseCache ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวแปรโฟลว์ได้ที่ข้อมูลอ้างอิงตัวแปร

รหัสข้อผิดพลาด

ส่วนนี้อธิบายข้อความแสดงข้อผิดพลาดและตัวแปรโฟลว์ที่ตั้งค่าไว้เมื่อนโยบายนี้ทริกเกอร์ข้อผิดพลาด ข้อมูลนี้สำคัญที่ต้องทราบ หากคุณกำลังพัฒนากฎข้อผิดพลาดสำหรับพร็อกซี ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด

คำนำหน้ารหัสข้อผิดพลาด

ไม่มีข้อมูล

ข้อผิดพลาดเกี่ยวกับรันไทม์

นโยบายนี้จะไม่แสดงข้อผิดพลาดเกี่ยวกับรันไทม์

ข้อผิดพลาดในการทำให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้

ตัวแปรของข้อผิดพลาด

ไม่มีข้อมูล

ตัวอย่างการตอบกลับข้อผิดพลาด

ไม่มีข้อมูล

สคีมา

นโยบายแต่ละประเภทกำหนดโดยสคีมา XML (.xsd) สคีมานโยบาย มีอยู่ใน GitHub