سياسة KeyValueMapOperations

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
info

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

الأدوات المستخدمة

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

الفيديوهات

يمكنك مشاهدة الفيديوهات التالية لمعرفة المزيد عن آلات KVM الافتراضية.

فيديو الوصف
لماذا خرائط القيم الرئيسية؟ تعرَّف على سبب حاجتك إلى أجهزة KVM وطريقة عملها.
إنشاء KVM باستخدام واجهة المستخدم واسترداد KVM في وقت التشغيل إنشاء KVM واسترداد قيمته باستخدام سياسة KVM وإدراج القيمة في طلب واجهة برمجة التطبيقات باستخدام متغيرات التدفق
إنشاء وتعديل خريطة قيم مفاتيح (KVM) في وقت تشغيل واجهة برمجة التطبيقات إنشاء KVM في وقت تشغيل واجهة برمجة التطبيقات باستخدام سياسة KVM
تخزين KVM مؤقتًا لتحسين الأداء تحسين أداء سياسة KVM من خلال تخزين البيانات مؤقتًا
تخزين البيانات مشفّرة KVM تخزين المعلومات الحسّاسة في KVM بتنسيق مشفّر واسترداد القيمة في وقت التشغيل باستخدام سياسة KVM والمتغيّرات الخاصة
إدارة الأذونات باستخدام نطاق KVM يمكنك حصر استخدام KVM على المؤسسة أو البيئة أو خادم وكيل لواجهة برمجة التطبيقات أو مراجعة خادم وكيل لواجهة برمجة التطبيقات باستخدام السمة KVM policy scope.
حذف إدخالات 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>

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

GET 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، اضبط سياسة GET لخريطة المفتاح/القيمة:

<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 في خريطة قيم المفاتيح. للحصول على معلومات حول إنشاء خرائط مشفّرة لقيم المفاتيح، راجِع مواضيع "الإنشاء" في Key/Value Maps management API.

<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 Public Cloud. على سبيل المثال، يختلف foobar عن FooBar.

في حال استبعاد هذه السمة، يتم استخدام KVM باسم kvmap.

ضمن نطاق مؤسسة أو بيئة أو خادم وكيل لواجهة برمجة التطبيقات، يمكنك استخدام السمة mapIdentifier لتحديد اسم الخريطة الخاص بك.

لا ينطبق اختياري

يصف الجدول التالي السمات المشتركة بين جميع العناصر الرئيسية للسياسة:

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

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

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

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

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

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

خطأ اختياري
enabled

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

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

صحيح اختياري
async

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

خطأ منهي العمل به

&lt;DisplayName&gt; عنصر

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

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

لا ينطبق

إذا لم تستخدم هذا العنصر، سيتم ضبط قيمة السمة name للسياسة على النحو التالي: استخدام البيانات المختلفة.

التواجد في المنزل اختياري
النوع سلسلة

العنصر <Delete>

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

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

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

العنصر <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>
تلقائي لا ينطبق
التواجد في المنزل اختياري
النوع لا ينطبق

العنصر <ExclusiveCache>

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

العنصر <ExpiryTimeInSecs>

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

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

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

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

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

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

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

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

مثال - تخزين آلة افتراضية KVM مؤقتًا

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

العنصر <Get>

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

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

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

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

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

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

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

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

المفتاح القيمة
top_movies Princess Bride,The Godfather,Citizen Kane
المواطن كين أورسن ويلز
Princess Bride روب راينر
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>

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

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

يقتصر حجم المفتاح على 2 كيلوبايت لكلّ من Edge for the Public Cloud وEdge for the Private Could. يقتصر حجم قيمة KVM على 2 كيلوبايت.

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

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

عنصر <Key>

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

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

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

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

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

العنصر <Parameter>

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

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

  • سلسلة حرفية

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

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

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

السمات

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

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

العنصر <Put>

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

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

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

السمات

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

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

إذا تم ضبطها على true، سيتم تجاوز قيمة المفتاح.

false اختياري

العنصر <Scope>

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

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

<Scope>environment</Scope>
تلقائي environment
التواجد في المنزل اختياري
النوع سلسلة
قيم صالحة:
  • 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>
تلقائي لا ينطبق
التواجد في المنزل مطلوب
النوع سلسلة

السمات

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

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

مرجع الخطأ

تتّبع الأخطاء التي يتم عرضها من سياسات 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. يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات الإدارية للحصول على تفاصيل حول واجهة برمجة التطبيقات Organization key/value maps API. يمكنك استخدام واجهة برمجة التطبيقات، على سبيل المثال، لتحميل مجموعات بيانات كبيرة إلى مخزن المفتاح/القيمة، أو لإنشاء نصوص برمجية لإدارة إدخالات خريطة المفتاح/القيمة. عليك إنشاء خريطة مفتاح/قيمة باستخدام واجهة برمجة التطبيقات قبل الوصول إليها باستخدام سياسة KeyValueMapOperations.

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

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

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

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

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

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

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