سياسة KeyValueMapOperations

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

رمز عمليات خريطة القيم الرئيسية من واجهة مستخدم Edge

الموضوع

توفِّر هذه السياسة الوصول المستنِد إلى السياسة إلى متجر "خريطة قيم المفاتيح" (KVM) المتوفّر في Apigee Edge. يمكن تخزين أزواج المفتاح/القيمة واستردادها وحذفها من الخرائط الحالية المسماة من خلال ضبط سياسات KeyValueMapOperations التي تحدّد عمليات PUT أو GET أو DELETE. (يجب أن يتم تنفيذ عملية واحدة على الأقل من هذه العمليات بموجب السياسة).

الفيديوهات الطويلة

شاهد مقاطع الفيديو التالية لمعرفة المزيد عن KVMs.

حملة فيديو الوصف
ما أهمية "خرائط القيم الرئيسية"؟ تعرَّف على أسباب احتياجك لآلات KVM وكيفية عملها.
إنشاء KVM باستخدام واجهة المستخدم واسترداد KVM في وقت التشغيل يمكنك إنشاء آلة متجه الدعم، واسترداد قيمتها باستخدام سياسة KVM، وإدخال القيمة في طلب واجهة برمجة التطبيقات باستخدام متغيرات التدفق.
إنشاء وتعديل KVM في وقت تشغيل واجهة برمجة التطبيقات إنشاء آلة متجه الدعم في وقت تشغيل واجهة برمجة التطبيقات باستخدام سياسة KVM.
تخزين KVM في ذاكرة التخزين المؤقت لتحسين الأداء تحسين أداء سياسة KVM عن طريق التخزين المؤقت للبيانات.
تخزين KVM مشفّر يمكنك تخزين المعلومات الحساسة في KVM بتنسيق مشفّر واسترداد القيمة أثناء التشغيل باستخدام سياسة KVM والمتغيّرات الخاصة.
إدارة أذونات الوصول باستخدام نطاق KVM يجب حصر KVM على مراجعة المؤسسة أو البيئة أو الخادم الوكيل لواجهة برمجة التطبيقات أو الخادم الوكيل لواجهة برمجة التطبيقات، وذلك باستخدام سمة نطاق سياسة KVM.
حذف إدخالات KVM في وقت تشغيل واجهة برمجة التطبيقات احذف إدخالات KVM في وقت تشغيل واجهة برمجة التطبيقات باستخدام عملية KVM السياسة DELETE.

عيّنات

ضع KVM مع حرفي

عند تنفيذ السياسة التالية، تنشئ الأداة KVM مشفّرًا باسم FooKVM، ثم تنشئ مفتاحًا باسم FooKey_1 يتضمن قيمتين مضمّنتين في السلسلتين الحرفيتين foo وbar (لا يتم ضبطهما باستخدام القيم المستخرَجة من المتغيّرات). عند إضافة المفتاح GET في المثال التالي، يتم تحديد رقم فهرس لاسترداد القيمة التي تريدها.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

لاحظ أن النطاق هو "environment" (البيئة). وهذا يعني أنه يمكنك الاطّلاع على KVM في واجهة مستخدم الإدارة ضمن واجهات برمجة التطبيقات > إعداد البيئة > خرائط القيم الرئيسية. ويتم تحديد جميع أجهزة KVM المعروضة في الصفحة وفقًا للبيئة المحدّدة.

الحصول على KVM من حرفي

تراجع هذه السياسة خريطة FooKVM من المثال السابق وتحصل على القيمة الثانية (index="2") من المفتاح FooKey_1 وتخزّنها في متغيّر يُسمّى foo_variable.

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

وضع KVM مع متغير

ومن الأمثلة البسيطة على خريطة القيم الرئيسية المفيدة خدمة اختصار عناوين URL. يمكن ضبط خريطة قيم المفاتيح لتخزين عناوين URL المختصرة مع عناوين URL الكاملة المقابلة لها.

ينشئ نموذج السياسة هذا ربط القيم الأساسية. تضع السياسة مفتاحًا يتضمّن قيمتَين مرتبطتَين في خريطة مفتاح/قيمة باسم "urlMapper".

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

المفتاح في هذا المثال، urlencoding.requesturl.hashed، هو مثال على متغيّر مخصّص. سيتم إنشاء عنوان URL للطلب المجزّأ من خلال الرمز (JavaScript أو Java، على سبيل المثال) ثم تخزينه في هذا المتغيّر حيث يمكن لسياسة KeyValueMapOperations الوصول إليه.

يتم تخزين قيمتَين لكل مفتاح في "requesturl.hashed":

  • محتوى المتغيّر المخصّص باسم urlencoding.longurl.encoded
  • محتوى المتغيّر المحدّد مسبقًا request.queryparam.url

على سبيل المثال، عند تنفيذ السياسة في وقت التشغيل، قد تكون قيم المتغيّرات على النحو التالي:

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
  • request.queryparam.url: http://apigee.com

سيتم إنشاء الخريطة والإدخال التاليَين للمفتاح/القيمة في مخزن المفتاح/القيمة في Edge مع تحديد نطاقهما على الخادم الوكيل لواجهة برمجة التطبيقات الذي يتم إرفاق السياسة به:

{
    "entry" :[ 
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

سيستمر الإدخال حتى يتم حذفه. يتم توزيع إدخالات مخزن المفتاح/القيم على جميع مثيلات Edge التي تستخدم السحابة الإلكترونية.

الحصول على KVM من متغير

ومن الأمثلة البسيطة على عملية ربط القيم الرئيسية المفيدة خدمة "تقصير عنوان URL". يمكن ضبط خريطة قيم المفاتيح لتخزين عناوين URL المختصرة مع عناوين URL الكاملة المقابلة لها.

لاسترداد قيمة إدخال خريطة المفتاح/القيمة، مثل القيمة المشمولة في علامة التبويب PUT في KeyValueMapOperations، اضبط سياسة للحصول على تعيين قيمة المفتاح:

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/> 
      </Key>
   </Get>
</KeyValueMapOperations>

عند تنفيذ هذه السياسة، وإذا كانت قيمة المتغيّر urlencoding.requesturl.hashed هي ed24e12820f2f900ae383b7cc4f2b31c402db1be، سيتم ضبط المتغيّر المخصّص باسم urlencoding.shorturl على القيمة http://tinyurl.com/38lwmlr.

والآن بعد استرداد البيانات، يمكن للسياسات والرموز البرمجية الأخرى الوصول إليها من خلال استخراج القيمة من تلك المتغيّرات.

استرجاع قيمة مشفّرة من KVM

إذا كانت ربط قيمة المفتاح مشفرة، يمكنك استرداد القيم باستخدام البادئة "private." في قيمة السمة assignTo. في هذا المثال، يحتفظ المتغيّر private.encryptedVar بالقيمة التي تم فك تشفيرها لمفتاح foo لخريطة قيمة المفتاح. للحصول على معلومات حول إنشاء خرائط قيم المفاتيح المشفّرة، يمكنك الاطّلاع على مواضيع "الإنشاء" في واجهة برمجة التطبيقات لإدارة خرائط القيمة/المفتاح.

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter> 
      </Key>
   </Get>
</KeyValueMapOperations>

والآن بعد استرداد البيانات، يمكن للسياسات والرموز البرمجية الأخرى الوصول إليها من خلال استخراج القيمة من ذلك المتغيّر.


مرجع العنصر

يصف مرجع العنصر عناصر وسمات سياسة KeyValueMapOperations:

<KeyValueMapOperations async="false" continueOnError="false" 
    enabled="true" name="Key-Value-Map-Operations-1" 
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

سمات <KeyValueMapOperations>

يعرض المثال التالي السمات في العلامة <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

يوضّح الجدول التالي السمات الخاصة بالعلامة <KeyValueMapOperations>:

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

تحدّد معرّفًا لاستخدامه عند الوصول إلى خريطة تم إنشاؤها بموجب هذه السياسة أو في واجهة مستخدم الإدارة.

إنّ اسم KVM حسّاس لحالة الأحرف مع Apigee Edge for Public Cloud. على سبيل المثال، يختلف foobar عن FooBar.

إذا استبعدت هذه السمة، يتم استخدام أداة KVM تسمى kvmap.

ضمن نطاق Organization/environment/apiproxy، يمكنك استخدام السمة mapIdentifier لتحديد اسم الخريطة.

لا ينطبق إجراء اختياري

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

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

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

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

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

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

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

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

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

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

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

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

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

العنصر <DisplayName>

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

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

لا ينطبق

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

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

عنصر <حذف>

لحذف زوج المفتاح/القيمة المحدّد. يجب استخدام سمة واحدة على الأقل من <Get> أو <Put> أو <Delete>.

احرص على تحديد اسم KVM باستخدام السمة mapIdentifier على العنصر الرئيسي. مثال:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>
تلقائي لا ينطبق
التواجد في المنزل تكون هذه السمة مطلوبة في حال عدم وجود السمة <Get> أو <Put>.
Type لا ينطبق

عنصر <Entry>

القيم الأساسية لخرائط القيم الرئيسية، والتي تتم تعبئتها في خريطة القيم الرئيسية عند إعدادها.

بالنسبة إلى Edge for Public Cloud، يقتصر حجم المفتاح على 2 كيلوبايت. مثال:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>
تلقائي لا ينطبق
التواجد في المنزل إجراء اختياري
Type لا ينطبق

عنصر <OriginalCache>

تمّ الإيقاف. يمكنك استخدام العنصر <Scope> بدلاً من ذلك.

العنصر <ExpiryTimeInSecs>

تحدّد المدة بالثواني التي يعدّل بعدها Edge القيمة المخزّنة مؤقتًا من KVM المحدَّد.

يعني استخدام القيمة 0 أو -1، أو استبعاد هذا العنصر، استخدام القيمة التلقائية التي تبلغ 300 ثانية. مثال:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
تلقائي 300 (5 دقائق)
التواجد في المنزل إجراء اختياري
Type عدد صحيح

KVM هي آلية استمرارية طويلة المدى تخزن المفاتيح والقيم في قاعدة بيانات NoSQL. لهذا السبب، قد تؤدي القراءة من KVM أثناء وقت التشغيل إلى إبطاء أداء الخادم الوكيل. لتحسين الأداء، تتوفر لدى Edge آلية مدمجة للتخزين المؤقت لمفاتيح/قيم KVM في الذاكرة أثناء وقت التشغيل. تقرأ سياسة عمليات KVM هذه دائمًا من ذاكرة التخزين المؤقت لعمليات GET.

يتيح لك العنصر <ExpiryTimeInSecs> التحكّم في مدة تخزين المفاتيح/القيم المستخدَمة في السياسة في ذاكرة التخزين المؤقت قبل إعادة تحميلها مرة أخرى من خلال KVM. ومع ذلك، هناك بعض الاختلافات بين كيفية تأثير عمليات GET وPUT في انتهاء صلاحية ذاكرة التخزين المؤقت.

GET - في المرة الأولى التي يتم فيها تنفيذ عملية KVM GET، يتم تحميل المفاتيح/القيم المطلوبة من KVM (الذي تم تحديد اسمه في سمة جذر السياسة mapIdentifier) إلى ذاكرة التخزين المؤقت، حيث تظل في ذاكرة التخزين المؤقت لعمليات GET اللاحقة إلى أن يحدث ما يلي:

  • تنتهي صلاحية عدد الثواني المحدّد في <ExpiryTimeInSecs>.
    أو
  • تؤدي عملية وضع PUT في سياسة KVM إلى استبدال القيم الموجودة (الشرح بعد ذلك).

PUT - تكتب عملية PUT المفاتيح/القيم في خوارزمية KVM المحددة. إذا تمت كتابة مفتاح PUT إلى مفتاح متوفّر في ذاكرة التخزين المؤقت، تتم إعادة تحميل ذاكرة التخزين المؤقت هذه على الفور، وهي تحتفظ الآن بالقيمة الجديدة لعدد الثواني المحدد في عنصر <ExpiryTimeInSecs> للسياسة.

مثال - التخزين المؤقت لآلة متجه الدعم

  1. تسترد عملية GET قيمة "rating"، التي تضيف القيمة "10" إلى ذاكرة التخزين المؤقت. <ExpiryTimeInSecs> في السياسة هو 60.
  2. بعد 30 ثانية، يتم تنفيذ النهج GET مرة أخرى واسترداد "10" من ذاكرة التخزين المؤقت.
  3. بعد 5 ثوانٍ، تعدّل سياسة وضع السعر قيمة "التقييم" إلى "8"، وتكون قيمة السمة <ExpiryTimeInSecs> في سياسة PUT هي 20. تتم إعادة تحميل ذاكرة التخزين المؤقت على الفور بالقيمة الجديدة التي تم ضبطها الآن لتظل في ذاكرة التخزين المؤقت لمدة 20 ثانية. (في حال عدم حدوث عملية PUT، ستظل ذاكرة التخزين المؤقت التي تم ملؤها في الأصل بواسطة GET الأول موجودة لمدة 30 ثانية أخرى، بعد هذه المدة المتبقية من المدة الأصلية التي تبلغ 60 ثانية).
  4. بعد 15 ثانية، يتم تنفيذ طريقة GET أخرى واسترداد القيمة "8".

عنصر <Get>

لاسترداد قيمة المفتاح المحدد. يجب استخدام سمة واحدة على الأقل من <Get> أو <Put> أو <Delete>.

احرص على تحديد اسم KVM باستخدام السمة mapIdentifier على العنصر الرئيسي.

يمكنك تضمين عدّة عمليات حظر Get في السياسة لاسترداد عناصر متعدّدة من KVM.

تلقائي لا ينطبق
التواجد في المنزل وتكون مطلوبة في حال عدم توفّر <Put> أو <Delete>.
Type لا ينطبق

احصل على منتج واحد من جهاز KVM

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>

الحصول على عدة عناصر من KVM

في المثال التالي، افترض أن KVM يحتوي على المفاتيح والقيم التالية. بالإضافة إلى تخزين قائمة الأفلام الأكثر شعبية على الإطلاق، تخزن KVM اسم المخرج لجميع الأفلام الكبرى.

المفتاح القيمة
top_movies أميرة العروس، الأب الروحي، المواطن كين
المواطن كين أورسون ويلز
أميرة العروس روب رينر
مسلسل The Godfather يوسف شاهين

في ما يلي إعداد سياسة KVM التي يمكننا استخدامها لاسترجاع الفيلم الأكثر رواجًا حاليًا واسم مخرجه:

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

عند استدعاء الخادم الوكيل لواجهة برمجة التطبيقات، ينشئ Edge المتغيرات التالية التي يمكنك استخدامها في تدفق الخادم الوكيل لواجهة برمجة التطبيقات:

  • top.movie.pick=Princess Bride
  • movie.director=Rob Reiner

السمات

يوضّح الجدول التالي سمات العنصر <Get>:

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

تمثّل هذه السمة المتغيّر الذي يجب تخصيص القيمة المستردة له.

إذا كانت خريطة قيمة المفتاح مشفّرة، ابدأ اسم assignTo بـ "private.". على سبيل المثال:

<Get assignTo="private.myvar">

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

للحصول على معلومات حول إنشاء خرائط قيم المفاتيح المشفّرة، يمكنك الاطّلاع على مواضيع "إنشاء" في واجهة برمجة التطبيقات لإدارة خرائط القيمة/المفاتيح وإنشاء خرائط القيم الأساسية للبيئة وتعديلها.

لا ينطبق مطلوبة
المؤشر

رقم الفهرس (في فهرس يستند إلى 1) للعنصر المطلوب جلبه من مفتاح متعدد القيم. على سبيل المثال، تحديد index=1 سيؤدي إلى عرض القيمة الأولى وتخصيصها للمتغيّر assignTo. إذا لم يتم تحديد أي قيمة فهرس، يتم ضبط جميع قيم هذا الإدخال للمتغيّر على أنّه java.util.List.

على سبيل المثال، راجِع علامة التبويب "الحصول على قيمة مشفّرة من KVM" في عيّنات.

لا ينطبق إجراء اختياري

عنصر <InitialEntries>

القيم الأساسية لخرائط القيم الرئيسية، والتي تتم تعبئتها في خريطة القيم الرئيسية عند إعدادها. احرص على تحديد اسم KVM باستخدام السمة mapIdentifier على العنصر الرئيسي، على سبيل المثال:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

عند استخدام هذا العنصر، عند حفظ السياسة في واجهة مستخدم الإدارة على إصدار منشور من الخادم الوكيل، أو عند نشر حزمة الخادم الوكيل لواجهة برمجة التطبيقات التي تحتوي على السياسة التي تحتوي على هذا العنصر، يتم إنشاء المفاتيح تلقائيًا في أداة KVM (على أنّها غير مشفّرة). إذا كانت القيم في السياسة مختلفة عن القيم في KVM، يتم استبدال القيم في KVM عند نشر الخادم الوكيل. وتتم إضافة أي مفاتيح/قيم جديدة إلى آلة متجه الدعم الحالية إلى جانب المفاتيح/القيم الحالية.

يجب أن تكون المفاتيح والقيم التي يعبئها هذا العنصر حرفية. على سبيل المثال، لا يمكن استخدام <Parameter ref="request.queryparam.key"> في هذا العنصر.

يقتصر حجم المفتاح على 2 كيلوبايت في كل من Edge الخاص بالسحابة الإلكترونية العامة وEdge من أجل العدد الخاص. وتقتصر قيمة KVM على 2 كيلوبايت.

لإنشاء آلة متجه الدعم مشفّرة، استخدِم واجهة برمجة التطبيقات لإدارة خرائط القيمة/المفتاح.

تلقائي لا ينطبق
التواجد في المنزل إجراء اختياري
Type لا ينطبق

عنصر <مفتاح>

تحدِّد هذه العلامة المفتاح في إدخال خريطة المفتاح/القيمة. وقد يكون المفتاح مركبًا، أي أنه يمكن إلحاق أكثر من معلَمة واحدة لإنشاء المفتاح. على سبيل المثال، قد يتم دمج userID وrole لإنشاء key. مثال:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

احرص على الاطّلاع على العنصر <Parameter> للحصول على تفاصيل حول كيفية ضبط اسم المفتاح.

في Edge for Public Cloud، يقتصر حجم المفتاح على 2 كيلوبايت. يمكنك الاطّلاع على الاختلافات بين Edge for Public Cloud API وخاصة Cloud API لمعرفة المزيد.

تلقائي لا ينطبق
التواجد في المنزل إجراء اختياري
Type لا ينطبق

عنصر <المَعلمة>

تحدد المفتاح في زوج المفتاح/القيمة. يحدد هذا العنصر الاسم عند إنشاء زوج المفتاح/القيمة أو وضعه أو استرداده أو حذفه.

يمكنك تحديد الاسم باستخدام:

  • سلسلة حرفية

    <Key>
      <Parameter>literal</Parameter>
    </Key>
    
  • يشير هذا المصطلح إلى متغيّر يمكن استرداده في وقت التشغيل باستخدام السمة ref.

    <Key>
      <Parameter ref="variable_name"/>
    </Key>
    
  • مجموعة من القيم الحرفية والمراجع المتغيرة

    <Key>
      <Parameter>targeturl</Parameter>
      <Parameter ref="apiproxy.name"/>
      <Parameter>weight</Parameter>
    </Key>
    

عندما يشتمل العنصر الرئيسي على عدة عناصر مَعلمة، تكون سلسلة المفتاح الفعّالة هي تسلسل قيم كل مَعلمة، مع ربطها بشرطة سفلية مزدوجة. على سبيل المثال، في المثال أعلاه، إذا كان المتغيّر apiproxy.name يحتوي على القيمة "abc1"، سيكون المفتاح الفعّال targeturl__abc1__weight.

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

تلقائي لا ينطبق
التواجد في المنزل مطلوبة
Type سلسلة

السمات

يوضّح الجدول التالي سمات العنصر <Parameter>:

السمة الوصف تلقائي التواجد في المنزل
المرجع تحدّد هذه السمة اسم متغيّر تحتوي قيمته على الاسم الدقيق للمفتاح الذي تريد إنشاءه أو الحصول عليه أو حذفه. لا ينطبق هذه السمة مطلوبة في حال عدم إدخال قيمة حرفية بين علامتَي الفتح والإغلاق. يُحظَّر إذا تم تقديم قيمة حرفية.

عنصر <Put>

تكتب زوج مفتاح/قيمة إلى خريطة قيمة مفتاح، سواء كانت خريطة قيمة المفتاح مشفّرة أو غير مشفرة. في حال عدم توفّر خريطة قيمة المفتاح المحدّدة في السمة mapIdentifier على العنصر الرئيسي، سيتم إنشاء الخريطة تلقائيًا (باعتبارها غير مشفّرة). إذا كانت خريطة قيمة المفتاح متوفرة مسبقًا، تتم إضافة المفتاح/القيمة إليها.

لإنشاء خريطة قيم مفتاح مشفّرة، استخدِم واجهة برمجة التطبيقات لإدارة خرائط القيمة/المفتاح، أو راجِع إنشاء خرائط القيم الأساسية للبيئة وتعديلها لإنشاء أنظمة KVM مشفّرة على مستوى البيئة في واجهة المستخدم.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
تلقائي لا ينطبق
التواجد في المنزل وتكون مطلوبة في حال عدم توفّر <Get> أو <Delete>.
Type لا ينطبق

السمات

يوضّح الجدول التالي سمات العنصر <Put>:

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

في حال ضبط السياسة على true، سيتم إلغاء قيمة المفتاح.

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

عنصر <Scope>

تحدِّد هذه السمة حدود سهولة الوصول إلى خرائط القيم الرئيسية. النطاق التلقائي هو environment، ما يعني أنّه تتم مشاركة إدخالات الخرائط تلقائيًا بين جميع الخوادم الوكيلة لواجهة برمجة التطبيقات التي تعمل في بيئة معيّنة (مثل اختبار أو منتج). في حال ضبط النطاق على apiproxy، لن يمكن الوصول إلى الإدخالات في خريطة قيمة المفتاح إلا من خلال الخادم الوكيل لواجهة برمجة التطبيقات الذي يكتب القيم على الخريطة.

عند الوصول إلى خريطة أو إدخال خريطة، يجب تحديد قيمة النطاق نفسها التي استخدمتها عند إنشاء الخريطة. على سبيل المثال، إذا تم إنشاء الخريطة باستخدام نطاق apiproxy، يجب استخدام نطاق apiproxy عند استرداد قيمه أو إدخال تغييرات أو حذف الإدخالات.

<Scope>environment</Scope>
تلقائي environment
التواجد في المنزل إجراء اختياري
Type سلسلة
قيم صالحة:
  • organization
  • environment
  • apiproxy
  • policy (مراجعة الخادم الوكيل لواجهة برمجة التطبيقات)

عنصر <Value>

تحدّد قيمة المفتاح. يمكنك تحديد القيمة كسلسلة حرفية أو باستخدام السمة ref كمتغيّر ليتم استرداده في وقت التشغيل:

<!-- Specify a literal value -->
<Value>literal<Value>

أو:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

يمكنك أيضًا تضمين عناصر <Value> متعدّدة لتحديد قيمة متعدّدة الأجزاء. يتم دمج القيم في وقت التشغيل.

في المثال التالي، تتم إضافة مفتاحين إلى KVM:

  • المفتاح k1 بالقيم v1,v2
  • المفتاح k2 بالقيم v3,v4
<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>     
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

في المثال التالي، يتم إنشاء مفتاح واحد بقيمتين. لنفترض أنّ اسم المؤسسة هو foo_org واسم الخادم الوكيل لواجهة برمجة التطبيقات هو bar والبيئة هي test:

  • المفتاح foo_org بالقيم bar,test
<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>
تلقائي لا ينطبق
التواجد في المنزل مطلوبة
Type سلسلة

السمات

يوضّح الجدول التالي سمات العنصر <Value>:

السمة الوصف تلقائي التواجد في المنزل
المرجع تحدّد هذه العلامة اسم متغيّر تحتوي قيمته على القيم الأساسية التي تريد ضبطها. لا ينطبق هذه السمة مطلوبة في حال عدم إدخال قيمة حرفية بين علامتَي الفتح والإغلاق. يُحظَّر إذا تم تقديم قيمة حرفية.

مرجع الخطأ

تتبع الأخطاء الناتجة من سياسات Edge تنسيقًا ثابتًا كما هو موضح في مرجع رمز الخطأ.

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

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

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

رمز الخطأ رموز حالة HTTP السبب إصلاح
steps.keyvaluemapoperations.SetVariableFailed 500

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

steps.keyvaluemapoperations.UnsupportedOperationException 500

يحدث هذا الخطأ إذا تم ضبط السمة mapIdentifier على سلسلة فارغة في "سياسة عمليات ربط القيمة الرئيسية".

أخطاء النشر

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

اسم الخطأ السبب إصلاح
InvalidIndex إذا كانت السمة index المحدّدة في العنصر <Get> ضمن سياسة عمليات خريطة القيمة الرئيسية صفرًا أو رقمًا سالبًا، سيتعذّر نشر الخادم الوكيل لواجهة برمجة التطبيقات. يبدأ الفهرس من 1، لذا يتم اعتبار أنّ الفهرس صفرًا أو عددًا صحيحًا سالبًا غير صالح.
KeyIsMissing يحدث هذا الخطأ إذا كان العنصر <Key> غير متوفّر تمامًا أو إذا كان العنصر <Parameter> غير متوفّر داخل العنصر <Key> ضمن <Entry> الخاص بالعنصر <InitialEntries> في سياسة عمليات ربط القيم الرئيسية.
ValueIsMissing يحدث هذا الخطأ إذا كان العنصر <Value> غير متوفّر أسفل العنصر <Entry> للعنصر <InitialEntries> ضِمن سياسة عمليات خريطة القيمة الرئيسية.

المخططات

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

للحصول على نظرة عامة حول خرائط القيم الرئيسية، يُرجى الاطّلاع على استخدام خرائط القيم الرئيسية.

يوفّر متجر خرائط القيم الرئيسية آلية استمرارية بسيطة للبيانات التي يتم تنسيقها على هيئة أزواج مفتاح/قيمة. يمكنك الوصول إليها في وقت التشغيل من خلال السياسات أو الرموز البرمجية. وتحتوي الخريطة على أي بيانات عشوائية بالتنسيق key=value.

على سبيل المثال، localhost=127.0.0.1 أو zip_code=94110 أو first_name=felix. في المثال الأول، تمثّل localhost مفتاح و127.0.0.1 هي قيمة. يتم تخزين كل زوج مفتاح/قيمة كإدخال في خريطة قيم المفتاح. يمكن لخريطة القيمة الرئيسية تخزين العديد من الإدخالات.

في ما يلي مثال على استخدام خرائط القيم الرئيسية. لنفترض أنك تحتاج إلى تخزين قائمة بعناوين IP المرتبطة ببيئات مختلفة في الخلفية. يمكنك إنشاء عملية ربط لقيم المفتاح تُسمى ipAddresses تحتوي على قائمة بأزواج المفتاح/القيمة كإدخالات. على سبيل المثال، يمكن أن يمثّل رمز JSON هذا الخريطة التالية:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

يمكنك استخدام هذه البنية لإنشاء مجموعة من عناوين IP التي يمكن أن تستخدمها السياسات في وقت التشغيل لفرض إضافة عناوين IP إلى القائمة المسموح بها أو إلى القائمة المسموح بها، ولاختيار عنوان ديناميكي للخلفية المستهدفة، وما إلى ذلك. ويتم عادةً استخدام سياسة KeyValueMapOperations لتخزين أو استرداد المعلومات طويلة الأجل التي يجب إعادة استخدامها في معاملات متعدّدة للطلب أو الاستجابة.

يمكن التلاعب بخرائط المفتاح/القيمة من خلال سياسة KeyValueMapOperations أو مباشرةً من خلال واجهة برمجة تطبيقات إدارة Apigee Edge. يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات للإدارة للحصول على تفاصيل حول واجهة برمجة التطبيقات لخرائط القيم/مفتاح المؤسسة. على سبيل المثال، يمكنك استخدام واجهة برمجة التطبيقات لتحميل مجموعات بيانات كبيرة إلى مخزن المفاتيح/القيم أو إنشاء نصوص برمجية لإدارة إدخالات تعيين المفتاح/القيمة. يجب إنشاء خريطة مفتاح/قيمة باستخدام واجهة برمجة التطبيقات قبل الوصول إليها باستخدام سياسة KeyValueMapOperations.

تحديد الأسماء الرئيسية واستردادها

باستخدام العنصرَين <Parameter> و<Value>، يمكنك تحديد قيمة حرفية (حيث تكون القيمة بين علامتَي الفتح والإغلاق) أو استخدام السمة ref لتحديد اسم متغيّر يجب استخدام قيمته في وقت التشغيل.

يستحق عنصر المعلَمة إشارة خاصة لأنه يحدّد اسم المفتاح الذي يتم إنشاؤه، بالإضافة إلى اسم المفتاح الذي تريد استرداده أو حذفه. في ما يلي مثالان على ذلك. يحدد الأول اسم مفتاح حرفيًا، والآخر يحدد اسم مفتاح باستخدام متغير. لنفترض أن ما يلي يُستخدم لإنشاء مفاتيح في آلة متجه الدعم:

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

في الحالة الأولى، يتم تخزين القيمة الحرفية لـ "key_name_literal" في آلة متجه الدعم كاسم المفتاح. في الحالة الثانية، تصبح أي قيمة في key.name.variable اسم المفتاح في KVM. على سبيل المثال، إذا احتوى key.name.variable على القيمة foo، سيتم تسمية المفتاح "foo".

عندما تريد استرداد المفتاح وقيمة مفتاح من خلال عملية GET (أو الحذف باستخدام عملية DELETE)، يجب أن يتطابق إعداد <Parameter> مع اسم المفتاح في KVM. على سبيل المثال، إذا كان اسم المفتاح في KVM هو foo، يمكنك تحديد القيمة الحرفية باستخدام <Parameter>foo</Parameter> أو تحديد متغيّر يحتوي على القيمة الدقيقة "foo"، على النحو التالي: <Parameter ref="variable.containing.foo"/>.

مواضيع ذات صلة