سياسة تعبئة ذاكرة التخزين المؤقت

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
المعلومات

تحدِّد هذه السياسة طريقة كتابة القيم المخزَّنة مؤقتًا في وقت التشغيل.

تم تصميم سياسة تعبئة ذاكرة التخزين المؤقت لكتابة الإدخالات في ذاكرة تخزين مؤقت قصيرة المدى للأغراض العامة. ويتم استخدامه بالتزامن مع سياسة البحث عن ذاكرة التخزين المؤقت (لقراءة إدخالات ذاكرة التخزين المؤقت) وسياسة إلغاء صلاحية ذاكرة التخزين المؤقت (لإلغاء صلاحية الإدخالات).

للتخزين المؤقت لاستجابات موارد الخلفية، يمكنك الاطّلاع على سياسة ذاكرة التخزين المؤقت للاستجابة.

مرجع العنصر

في ما يلي قائمة بالعناصر التي يمكنك ضبطها في هذه السياسة.

<PopulateCache async="false" continueOnError="false" enabled="true" name="Populate-Cache-1">
    <DisplayName>Populate Cache 1</DisplayName>
    <Properties/>
    <CacheKey>
        <Prefix/>
        <KeyFragment ref=""/>
    </CacheKey>
    <!-- Omit this element if you're using the included shared cache. -->
    <CacheResource/>
    <Scope>Exclusive</Scope>
    <ExpirySettings>
        <TimeoutInSeconds>300</TimeoutInSeconds>
    </ExpirySettings>
    <Source>flowVar</Source>
</PopulateCache>

سمات <PopulateCache>

يوضِّح الجدول التالي السمات الشائعة لجميع العناصر الرئيسية للسياسة:

السمة الوصف تلقائي التواجد في المنزل
name

الاسم الداخلي للسياسة وقد تحتوي قيمة السمة name على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. لا يمكن أن تتجاوز هذه القيمة 255 حرفًا.

ويمكنك اختياريًا استخدام العنصر <DisplayName> لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف للغة طبيعية.

لا ينطبق مطلوبة
continueOnError

اضبط القيمة على false لعرض رسالة خطأ عند تعذُّر تنفيذ السياسة. وهو سلوك متوقّع لمعظم السياسات.

اضبط القيمة على true لمواصلة تنفيذ التدفق حتى بعد تعذُّر تنفيذ السياسة.

false إجراء اختياري
enabled

اضبط القيمة على true لفرض السياسة.

اضبط القيمة على false من أجل إيقاف السياسة. ولن يتم فرض السياسة حتى إذا ظلت مرتبطة بمسار.

صحيح إجراء اختياري
async

تم إيقاف هذه السمة نهائيًا.

false منهي العمل به

العنصر <DisplayName>

استخدِم هذه السمة بالإضافة إلى السمة name لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الإدارية باستخدام اسم مختلف بلغة طبيعية.

<DisplayName>Policy Display Name</DisplayName>
تلقائي

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم استخدام قيمة السمة name الخاصة بالسياسة.

التواجد في المنزل إجراء اختياري
Type سلسلة

العنصر <CacheKey>

تحدِّد هذه السياسة مؤشرًا فريدًا يشير إلى جزء من البيانات المخزَّنة في ذاكرة التخزين المؤقت.

يقتصر حجم مفاتيح ذاكرة التخزين المؤقت على 2 كيلوبايت.

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

الخيار التلقائي:

لا ينطبق

الحضور:

مطلوبة

النوع:

لا ينطبق

تنشئ <CacheKey> اسم كل جزء من البيانات مخزَّنة في ذاكرة التخزين المؤقت.

في وقت التشغيل، يتم إرفاق قيم <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>. لمزيد من المعلومات، يمكنك الاطّلاع على العمل باستخدام مفاتيح ذاكرة التخزين المؤقت.

عنصر<CacheResource>

تحدِّد هذه السياسة ذاكرة التخزين المؤقت التي يجب تخزين الرسائل فيها.

يمكنك حذف هذا العنصر تمامًا إذا كانت هذه السياسة (وسياستي LookupCache وInvalidateCache المتوافقة) تستخدمان ذاكرة التخزين المؤقت المشتركة المضمّنة.

<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>. لمزيد من المعلومات، يمكنك الاطّلاع على العمل باستخدام مفاتيح ذاكرة التخزين المؤقت.

السمات

السمة Type تلقائي مطلوبة الوصف
المرجع سلسلة لا

تمثّل هذه السمة المتغيّر المطلوب الحصول على القيمة منه. يجب عدم استخدامها إذا كان هذا العنصر يحتوي على قيمة حرفية.

العنصر <CacheKey>/<Prefix>

تُحدِّد قيمة لاستخدامها كبادئة مفتاح ذاكرة التخزين المؤقت.

<Prefix>prefix_string</Prefix>

الخيار التلقائي:

لا ينطبق

الحضور:

إجراء اختياري

النوع:

سلسلة

استخدِم هذه القيمة بدلاً من <Scope> عندما تريد تحديد قيمة لك بدلاً من قيمة <Scope> العددية. وفي حال تحديدها، يضيف <Prefix> قيمة مفتاح ذاكرة التخزين المؤقت للإدخالات المكتوبة في ذاكرة التخزين المؤقت. تؤدي قيمة العنصر <Prefix> إلى إلغاء قيمة العنصر <Scope>.

ويمكنك استخدام العنصر <Prefix> بالاقتران مع <CacheKey> و<Scope>. لمزيد من المعلومات، يمكنك الاطّلاع على العمل باستخدام مفاتيح ذاكرة التخزين المؤقت.

العنصر <ExpirySettings>

تُحدِّد هذه السياسة وقت انتهاء صلاحية إدخال ذاكرة التخزين المؤقت. عند استخدام هذه السمة، <TimeoutInSeconds> تتجاهل كل من <TimeOfDay> و<ExpiryDate>.

<ExpirySettings>
  <!-- use exactly one of the following child elements -->
  <TimeoutInSeconds ref="duration_variable">seconds_until_expiration</TimeoutInSeconds>
  <ExpiryDate ref="date_variable">expiration_date</ExpiryDate>
  <TimeOfDay ref="time_variable">expiration_time</TimeOfDay>
</ExpirySettings>

الخيار التلقائي:

لا ينطبق

الحضور:

مطلوبة

النوع:

لا ينطبق

العناصر الثانوية من <ExpirySettings>

استخدم عنصرًا فرعيًا واحدًا فقط. يقدّم الجدول التالي وصفًا لعناصر <ExpirySettings> الثانوية:

عنصر فرعي الوصف
<TimeoutInSeconds>

عدد الثواني التي تنتهي بعدها صلاحية إدخال ذاكرة التخزين المؤقت.

<ExpirySettings>
  <TimeoutInSeconds ref="var-containing-duration">expiry</TimeoutInSeconds>
</ExpirySettings>

يحل هذا العنصر محل عنصر TimeoutInSec المتوقّف الآن.

<ExpiryDate>

تُحدِّد التاريخ الذي يجب أن تنتهي فيه صلاحية إدخال ذاكرة التخزين المؤقت. حدِّد سلسلة بالصيغة mm-dd-yyyy.

<ExpirySettings>
  <ExpiryDate ref="var-containing-date">expiry</ExpiryDate>
</ExpirySettings>

إذا كان التاريخ المحدَّد في الماضي، ستطبِّق السياسة الحد الأقصى لمدة البقاء على الإدخال المخزّنة مؤقتًا. وهذا الحد الأقصى هو 30 يومًا.

<TimeOfDay>

تُحدِّد الوقت من اليوم الذي ستنتهي فيه صلاحية إدخال ذاكرة التخزين المؤقت. حدِّد سلسلة بالصيغة HH:mm:ss، حيث يمثّل HH الساعة بتنسيق 24 ساعة، في المنطقة الزمنية للتوقيت العالمي المتفق عليه. على سبيل المثال، تشير الساعة 14:30:00 إلى 2:30 بعد الظهر.

<ExpirySettings>
  <TimeOfDay ref="var-containing-time">expiry</TimeOfDay>
</ExpirySettings>

يجب تحديد عنصر واحد فقط من العناصر الثانوية المحتملة. في حال تحديد عناصر متعدّدة، سيكون ترتيب الأولوية هو:TimeoutInSeconds وExpiryDate وTimeOfDay.

مع كل عنصر من العناصر الفرعية أعلاه في <ExpirySettings>، إذا حددت السمة ref الاختيارية على العنصر الفرعي، ستسترجع السياسة قيمة انتهاء الصلاحية من متغيّر السياق المحدّد. في حال عدم تحديد المتغيّر، تستخدم السياسة القيمة النصية الحرفية للعنصر الفرعي.

عنصر <Scope>

تعداد يُستخدَم لإنشاء بادئة لمفتاح ذاكرة التخزين المؤقت عندما لا يتوفّر عنصر <Prefix> في العنصر <CacheKey>

<Scope>scope_enumeration</Scope>

الخيار التلقائي:

"حصرية"

الحضور:

إجراء اختياري

النوع:

سلسلة

يحدد الإعداد <Scope> مفتاح ذاكرة تخزين مؤقت تتم إضافته قبل قيمة <Scope>. على سبيل المثال، سيتخذ مفتاح ذاكرة التخزين المؤقت الشكل التالي عند ضبط النطاق على Exclusive:

orgName__envName__apiProxyName__deployedRevisionNumber__proxy|TargetName__ [ serializedCacheKey ]

إذا كان العنصر <Prefix> متوفّرًا في <CacheKey>، سيحلّ محلّ قيمة العنصر <Scope>. وتشمل القيم الصالحة التعداد أدناه.

ويمكنك استخدام العنصر <Scope> بالاقتران مع <CacheKey> و<Prefix>. لمزيد من المعلومات، يمكنك الاطّلاع على العمل باستخدام مفاتيح ذاكرة التخزين المؤقت.

القِيم المقبولة

Global

تتم مشاركة مفتاح ذاكرة التخزين المؤقت بين كل الخوادم الوكيلة لواجهة برمجة التطبيقات المنشورة في البيئة. تتم إضافة مفتاح ذاكرة التخزين المؤقت بالتنسيق orgName __ envName __.

إذا عرَّفت إدخال <CacheKey> باستخدام apiAccessToken <KeyFragment> والنطاق <Global>، سيتم تخزين كل إدخال على أنّه orgName__envName__apiAccessToken، متبوعة بالقيمة التسلسلية لرمز الدخول. بالنسبة إلى خادم وكيل لواجهة برمجة التطبيقات تم نشره في بيئة تُسمى "test" في مؤسسة تُسمّى "apifactory"، سيتم تخزين رموز الدخول ضمن مفتاح ذاكرة التخزين المؤقت التالي: apifactory__test__apiAccessToken.

Application

يتم استخدام اسم الخادم الوكيل لواجهة برمجة التطبيقات كبادئة.

تتم إضافة مفتاح ذاكرة التخزين المؤقت بالتنسيق orgName__envName__apiProxyName.

Proxy

يتم استخدام إعداد ProxyEndpoint كبادئة.

تتم إضافة مفتاح ذاكرة التخزين المؤقت على النحو التالي: orgName__envName__apiProxyName__deployedRevisionNumber__proxyEndpointName .

Target

يتم استخدام ضبط نقطة النهاية كبادئة.

إضافة مفتاح ذاكرة التخزين المؤقت بالتنسيق orgName__envName__apiProxyName__deployedRevisionNumber__targetEndpointName .

Exclusive

تلقائي: وهذه الطريقة هي الأكثر تحديدًا، وبالتالي تشكّل خطرًا ضئيلاً بحدوث تضارب في مساحات الاسم ضمن ذاكرة تخزين مؤقت معيّنة.

تكون البادئة واحدة من شكلين:

  • في حال إرفاق السياسة بمسار ProxyEndpoint، ستكون البادئة على شكل ApiProxyName_ProxyEndpointName.
  • في حال إرفاق السياسة على TargetEndpoint، ستظهر البادئة ApiProxyName_TargetName.

إضافة مفتاح ذاكرة التخزين المؤقت على النحو التالي: orgName__envName__apiProxyName__deployedRevisionNumber__proxyNameITargetName

على سبيل المثال، قد تبدو السلسلة الكاملة على النحو التالي:

apifactory__test__weatherapi__16__default__apiAccessToken
.

عنصر <المصدر>

تحدّد هذه السمة المتغيّر الذي يجب كتابة قيمته في ذاكرة التخزين المؤقت.

<Source>source_variable</Source>

الخيار التلقائي:

لا ينطبق

الحضور:

مطلوبة

النوع:

سلسلة

ملاحظات الاستخدام

ويمكنك استخدام هذه السياسة للتخزين المؤقت للأغراض العامة. في وقت التشغيل، تكتب السياسة <PopulateCache> البيانات من المتغيّر الذي حدّدته في العنصر <Source> إلى ذاكرة التخزين المؤقت التي حدّدتها في العنصر <CacheResource>. يمكنك استخدام العناصر <CacheKey> و<Scope> و<Prefix> لتحديد مفتاح يمكنك استخدامه من السياسة <LookupCache> لاسترداد القيمة. استخدِم العنصر <ExpirySettings> لضبط وقت انتهاء صلاحية القيمة المخزّنة مؤقتًا.

إنّ التخزين في ذاكرة التخزين المؤقت للأغراض العامة من خلال سياسة التعبئة والذاكرة وسياسة البحث عن ذاكرة التخزين المؤقت وسياسة إلغاء صلاحية ذاكرة التخزين المؤقت يستخدم إمّا ذاكرة تخزين مؤقت تضبطها أو تكون ذاكرة تخزين مؤقت مشتركة يتم تضمينها بشكل تلقائي. في معظم الحالات، من المفترض أن تلبّي ذاكرة التخزين المؤقت المشتركة الأساسية احتياجاتك. لاستخدام ذاكرة التخزين المؤقت هذه، ما عليك سوى حذف العنصر <CacheResource>.

حدود ذاكرة التخزين المؤقت: يتم تطبيق حدود مختلفة لذاكرة التخزين المؤقت، مثل الاسم وحجم القيمة وإجمالي عدد ذاكرات التخزين المؤقت وعدد العناصر في ذاكرة التخزين المؤقت وتاريخ انتهاء الصلاحية.

لمزيد من المعلومات حول مخزن البيانات الأساسي، اطّلِع على العمليات الداخلية لذاكرة التخزين المؤقت. لمزيد من المعلومات حول إعداد ذاكرات التخزين المؤقت، يمكنك الاطّلاع على إنشاء ذاكرة تخزين مؤقت للبيئة وتعديلها.

لمحة عن تشفير ذاكرة التخزين المؤقت

Edge for Public Cloud: يتم تشفير ذاكرة التخزين المؤقت فقط في المؤسسات التي تستخدم PCI وHIPAA. يتم ضبط التشفير لتلك المؤسسات أثناء توفير المتطلبات اللازمة في المؤسسة.

رموز الخطأ

يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد للأخطاء للتعامل معها. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.

أخطاء في وقت التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

رمز الخطأ حالة HTTP يحدث عند
policies.populatecache.EntryCannotBeCached 500 يتعذّر تخزين أحد الإدخالات مؤقتًا. وكائن الرسالة الذي يتم تخزينه مؤقتًا ليس مثيلاً لفئة قابلة للتسلسل.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

اسم الخطأ السبب إصلاح
InvalidCacheResourceReference يحدث هذا الخطأ إذا تم ضبط العنصر <CacheResource> في السياسة PopulateCache على اسم غير متوفر في البيئة التي يتم فيها تفعيل الخادم الوكيل لواجهة برمجة التطبيقات.
CacheNotFound ذاكرة التخزين المؤقت المحددة في العنصر <CacheResource> غير موجودة.

متغيرات الخطأ

ويتم ضبط هذه المتغيّرات عندما تؤدي هذه السياسة إلى ظهور خطأ. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات.

المتغيرات المكان مثال
fault.name="fault_name" fault_name هو اسم الخطأ، كما هو موضَّح في جدول أخطاء وقت التشغيل أعلاه. اسم الخطأ هو الجزء الأخير من رمز الخطأ. fault.name = "EntryCannotBeCached"
populatecache.policy_name.failed policy_name هو اسم السياسة التي حدّدها المستخدم التي أدت إلى حدوث الخطأ. populatecache.POP-CACHE-1.failed = true

مثال على الردّ على الخطأ

{
  "fault": {
    "faultstring": "[entry] can not be cached. Only serializable entries are cached.",
    "detail": {
      "errorcode": "steps.populatecache.EntryCannotBeCached"
    }
  }
}

مثال لقاعدة خطأ

<FaultRule name="Populate Cache Fault">
    <Step>
        <Name>AM-EntryCannotBeCached</Name>
        <Condition>(fault.name Matches "EntryCannotBeCached") </Condition>
    </Step>
    <Condition>(populatecache.POP-CACHE-1.failed = true) </Condition>
</FaultRule>