التعامل مع خرائط القيمة الرئيسية

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

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

للتعرّف على الأنواع الأخرى من البيانات الثابتة، يُرجى الاطّلاع على مقالة إضافة التخزين المؤقت والبي1انات الثابتة.

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

في ما يلي بعض الحالات التي تكون فيها خرائط القيمة الرئيسية مفيدة:

• لديك خادم وكيل لواجهة برمجة تطبيقات يحتاج إلى استدعاء عنوان URL واحد للهدف (أو Service Callout) في بيئة اختبار وبيئة التشغيل الفعلي عنوان URL آخر للهدف في. بدلاً من برمجة عناوين URL في الخادم الوكيل، يمكنك أن يكتشف الخادم الوكيل البيئة التي يعمل فيها، وأن ينفّذ سياسة عمليات خريطة القيمة الرئيسية ذات الصلة، وأن يسترد عنوان URL الصحيح للهدف من إحدى خرائط القيمة الرئيسية التي أنشأتها. وفي وقت لاحق، إذا تغيّر أحد أهدافك أو كلاهما، ما عليك سوى تعديل خرائط القيمة الرئيسية باستخدام عناوين URL الجديدة. ويستخدِم الخادم الوكيل القيم الجديدة، ولا يلزم إعادة نشر الخادم الوكيل.
• تريد تخزين بيانات الاعتماد أو المفاتيح الخاصة أو الرموز المميّزة، مثل الرموز المميّزة للخدمات الخارجية أو بيانات الاعتماد المطلوبة لإنشاء رموز OAuth المميّزة أو المفاتيح الخاصة المستخدَمة في Java Callouts أو JavaScript للتشفير أو توقيع JSON Web Token (JWT). بدلاً من تمرير بيانات الاعتماد أو المفاتيح أو الرموز المميّزة في الطلب أو برمجة هذه البيانات في منطق الخادم الوكيل، يمكنك تخزينها في خريطة قيمة رئيسية (مشفّرة دائمًا) واستردادها ديناميكيًا في عمليات استدعاء الأهداف التي تتطلبها.

ستكتشف حالات أخرى يكون فيها تخزين أزواج السلاسل للقيمة والمفتاح مفيدًا. بشكل عام، ننصحك باستخدام خرائط القيمة الرئيسية في الحالات التالية:

• تتطلب أماكن معيّنة في الرمز قيمًا مختلفة في وقت التشغيل.
• يجب تمرير البيانات الحسّاسة بدون برمجة هذه البيانات.
• تريد تخزين قيم لا تنتهي صلاحيتها كما قد يحدث في ذاكرة التخزين المؤقت.

خرائط القيمة الرئيسية لها نطاق

يعني النطاق "المكان الذي تتوفّر فيه خريطة القيمة الرئيسية". يمكن إنشاء خرائط القيمة الرئيسية على النطاقات التالية: organization, environment, وapiproxy.

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

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

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

لمحة عن خرائط القيمة الرئيسية المشفّرة

يتم تشفير خرائط القيمة الرئيسية المشفّرة باستخدام مفتاح تشفير AES-128 الذي أنشأته Apigee. يتم تخزين المفتاح المستخدَم لـ تشفير خريطة القيمة الرئيسية على نطاق خريطة القيمة الرئيسية. على سبيل المثال، ضمن مؤسسة، يتم إنشاء جميع خرائط القيمة الرئيسية المشفّرة التي تنشئها على نطاق البيئة باستخدام المفتاح نفسه على نطاق البيئة.

تعالج Edge عرض القيم المشفّرة بالطرق التالية. (يُرجى الاطّلاع على مقالة إدارة خرائط القيمة الرئيسية واستخدامها للحصول على معلومات عن إنشاء خرائط القيمة الرئيسية المشفّرة.)

واجهة مستخدم Edge

تعرض خرائط القيمة الرئيسية المشفّرة قيمًا محجوبة بعلامات النجمة في واجهة المستخدم (*****). على سبيل المثال:

واجهة برمجة تطبيقات الإدارة

في واجهة برمجة تطبيقات الإدارة، يتم عرض القيم المشفّرة محجوبة. في ما يلي نموذج لردّ من واجهة برمجة تطبيقات الإدارة على طلب Get encrypted KVM:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

التتبُّع وتصحيح الأخطاء

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

الحدود

في المؤسسات التي تم تفعيل Core Persistence Services (CPS) فيها:

• يكون اسم/معرّف خريطة القيمة الرئيسية حسّاسًا لحالة الأحرف.
• يقتصر حجم المفتاح على 2 كيلوبايت.
• يقتصر حجم القيمة على 10 كيلوبايت.

بالنسبة إلى Apigee Edge for Private Cloud، يجب ألا تتجاوز كل خريطة قيمة رئيسية 15 ميغابايت (هذا هو الحجم المجمّع للمفاتيح والقيم). إذا تجاوزت هذا الحد، ستعرض Apigee Edge for Private Cloud خطأً. لتحديد حجم خرائط القيمة الرئيسية، يمكنك استخدام الأمر nodetool cfstats.

يمكن أن تؤدي خرائط القيمة الرئيسية الأكبر حجمًا إلى تدهور الأداء. نتيجةً لذلك، عليك تقسيم خرائط القيمة الرئيسية الكبيرة والمتكاملة إلى خرائط أصغر لتحسين الأداء.

إدارة خرائط القيمة الرئيسية واستخدامها

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

إنشاء خرائط القيمة الرئيسية وتعديلها

يمكنك إنشاء خرائط القيمة الرئيسية وتعديلها بالطرق التالية:

• سياسة عمليات خريطة القيمة الرئيسية (بدون تشفير)

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

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

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

• Management API

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

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

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

• واجهة مستخدم الإدارة

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

استرداد خرائط القيمة الرئيسية

يمكنك استرداد خرائط القيمة الرئيسية المشفّرة وغير المشفّرة بالطريقة نفسها، مع اختلاف بسيط عند الاسترداد باستخدام سياسة عمليات خريطة القيمة الرئيسية.

• السياسة: استخدِم العنصر <Get> في سياسة عمليات خريطة القيمة الرئيسية لاسترداد خرائط القيمة الرئيسية المشفّرة وغير المشفّرة. يكمن الاختلاف البسيط في استرداد القيم المشفّرة باستخدام السياسة، حيث يجب إضافة البادئة "private." إلى اسم المتغيّر الذي سيحتوي على القيمة المستردة، كما هو موضّح في قسم عملية Get من موضوع المرجع. تخفي هذه البادئة القيمة من جلسات التتبُّع وتصحيح الأخطاء أثناء تصحيح أخطاء الخوادم الوكيلة لواجهة برمجة التطبيقات.
• Management API: لأغراض الإدارة، يمكنك استخدام مقالة إنشاء خرائط القيمة الرئيسية للبيئة وتعديلها للحصول على خرائط القيمة الرئيسية والمفاتيح/القيم. على سبيل المثال، إذا كنت تريد الاحتفاظ بنسخة احتياطية من خرائط القيمة الرئيسية من خلال الحصول على تعريفات JSON وتخزينها، استخدِم واجهة برمجة تطبيقات الإدارة. يُرجى العِلم، أنّ القيم المشفّرة تظهر على شكل ***** في ردّ واجهة برمجة التطبيقات.
• واجهة مستخدم الإدارة: يمكنك الاطّلاع على خرائط القيمة الرئيسية على نطاق البيئة في واجهة مستخدم الإدارة من خلال الانتقال إلى واجهات برمجة التطبيقات > إعدادات البيئة > خرائط القيمة الرئيسية (Classic Edge) أو المشرف > البيئات > خرائط القيمة الرئيسية (New Edge).

مثال على خريطة قيمة رئيسية

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