کار با نقشه های ارزش کلیدی

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

مواقعی وجود دارد که می‌خواهید داده‌ها را برای بازیابی در زمان اجرا ذخیره کنید - داده‌هایی که منقضی نمی‌شوند و نباید در منطق پروکسی API شما به صورت hard-code شده باشند. نقشه‌های کلید/مقدار (KVM) برای این کار ایده‌آل هستند. KVM مجموعه‌ای سفارشی از جفت‌های رشته‌ای کلید/مقدار است که یا رمزگذاری شده یا رمزگذاری نشده‌اند. در اینجا دو مثال آورده شده است:

برای آشنایی با انواع دیگر ماندگاری، به افزودن ذخیره‌سازی پنهان و ماندگاری مراجعه کنید.

سناریوهای KVM

در اینجا به مواردی اشاره می‌کنیم که KVMها مفید واقع می‌شوند:

• شما یک پروکسی API دارید که باید یک URL هدف (یا Service Callout) را در یک محیط آزمایشی و یک URL هدف دیگر را در یک محیط عملیاتی فراخوانی کند. به جای کدگذاری URLها در پروکسی خود، می‌توانید پروکسی را طوری تنظیم کنید که تشخیص دهد در کدام محیط قرار دارد، سیاست مربوط به عملیات نقشه ارزش کلیدی (Key Value Map Operations) را اجرا کند و URL هدف صحیح را از یکی از KVM هایی که ایجاد کرده‌اید بازیابی کند. و بعداً، اگر یک یا هر دو هدف شما تغییر کند، به سادگی KVM ها را با URL های جدید به روز می کنید. پروکسی مقادیر جدید را دریافت می کند و نیازی به استقرار مجدد پروکسی نیست.
• شما می‌خواهید اعتبارنامه‌ها، کلیدهای خصوصی یا توکن‌ها را ذخیره کنید - مانند توکن‌های مربوط به سرویس‌های خارجی، اعتبارنامه‌های مورد نیاز برای تولید توکن‌های OAuth یا کلیدهای خصوصی مورد استفاده در Java Callouts یا JavaScript برای رمزگذاری یا امضای JSON Web Token (JWT). به جای ارسال اعتبارنامه‌ها، کلیدها یا توکن‌ها در درخواست یا کدگذاری سخت آنها در منطق پروکسی خود، می‌توانید آنها را در یک KVM (همیشه رمزگذاری شده) ذخیره کنید و به صورت پویا آنها را در فراخوانی‌ها به اهدافی که به آنها نیاز دارند، بازیابی کنید.

شما موقعیت‌های دیگری را کشف خواهید کرد که در آن‌ها ذخیره‌سازی جفت‌های رشته‌ای کلید/مقدار مفید است. به‌طورکلی، استفاده از KVMها را در موارد زیر در نظر بگیرید:

• مکان‌های خاص در کد شما در زمان اجرا به مقادیر متفاوتی نیاز دارند.
• داده‌های حساس باید بدون کدگذاری دقیق منتقل شوند.
• شما می‌خواهید مقادیری را ذخیره کنید که مانند حافظه پنهان منقضی نشوند.

KVM ها دامنه دارند

محدوده (scope) به معنای «جایی که یک KVM در دسترس است» است. KVMها می‌توانند در محدوده‌های زیر ایجاد شوند: organization ، environment و apiproxy .

برای مثال، اگر فقط یک پروکسی API به داده‌ها در KVM نیاز دارد، می‌توانید KVM را در محدوده apiproxy ایجاد کنید، جایی که فقط آن پروکسی API بتواند به داده‌ها دسترسی داشته باشد.

یا ممکن است بخواهید همه پروکسی‌های API در محیط تست شما به یک نقشه کلید-مقدار دسترسی داشته باشند، که در این صورت باید یک نقشه کلید-مقدار در محدوده محیط ایجاد کنید. پروکسی‌های مستقر در محیط "prod" نمی‌توانند به KVMها در محدوده محیط "test" دسترسی داشته باشند. اگر می‌خواهید کلیدهای KVM یکسانی در محیط عملیاتی نیز در دسترس باشند، یک KVM موازی در محدوده محیط "prod" ایجاد کنید.

اگر می‌خواهید همه پروکسی‌ها در همه محیط‌ها به یک KVM یکسان دسترسی داشته باشند، KVM را در محدوده organization ایجاد کنید.

درباره KVM های رمزگذاری شده

KVM های رمزگذاری شده با یک کلید رمزنگاری AES-128 تولید شده توسط Apigee رمزگذاری می‌شوند. کلیدی که برای رمزگذاری KVM استفاده می‌شود در محدوده KVM ذخیره می‌شود. به عنوان مثال، در یک سازمان، تمام KVM های رمزگذاری شده‌ای که در محدوده محیط ایجاد می‌کنید با استفاده از همان کلید در محدوده محیط ایجاد می‌شوند.

Edge نمایش مقادیر رمزگذاری شده را به روش‌های زیر مدیریت می‌کند. (برای اطلاعات بیشتر در مورد ایجاد KVM های رمزگذاری شده، به مدیریت و استفاده از KVM ها مراجعه کنید.)

رابط کاربری اج

نقشه‌های کلید-مقدار رمزگذاری‌شده، مقادیری را که با ستاره در رابط کاربری (*****) پوشانده شده‌اند، نمایش می‌دهند. برای مثال:

رابط برنامه‌نویسی کاربردی مدیریت

در API مدیریت، مقادیر رمزگذاری شده به صورت ماسک شده بازگردانده می‌شوند. در زیر نمونه‌ای از پاسخ API مدیریت در فراخوانی Get encrypted KVM آمده است:

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

ردیابی و اشکال‌زدایی

وقتی از سیاست عملیات نقشه کلید مقدار برای بازیابی مقادیر رمزگذاری شده KVM استفاده می‌کنید، نام متغیری را برای ذخیره مقدار ارائه می‌دهید. برای دریافت یک مقدار رمزگذاری شده، باید پیشوند " private. " را به نام متغیر اضافه کنید، که از نمایش کلیدها/مقادیر KVM در جلسات ردیابی و اشکال‌زدایی جلوگیری می‌کند.

محدودیت‌ها

در سازمان‌هایی که سرویس‌های پایداری اصلی (CPS) در آنها فعال است:

• نام/شناسه KVM به حروف کوچک و بزرگ حساس است.
• اندازه کلید به 2 کیلوبایت محدود شده است.
• اندازه مقدار به 10 کیلوبایت محدود شده است.

برای Apigee Edge برای Private Cloud، هر KVM نباید از ۱۵ مگابایت تجاوز کند (این اندازه ترکیبی کلیدها و مقادیر است). اگر از این حد تجاوز کنید، Apigee Edge برای Private Cloud خطا برمی‌گرداند. برای تعیین اندازه KVM های خود، می‌توانید از دستور nodetool cfstats استفاده کنید.

KVM های بزرگتر می توانند منجر به کاهش عملکرد شوند. در نتیجه، شما باید KVM های بزرگ و یکپارچه را به KVM های کوچکتر تقسیم کنید تا عملکرد را بهبود بخشید.

مدیریت و استفاده از KVM ها

شما می‌توانید KVMها را به روش‌های مختلفی ایجاد، مدیریت و استفاده کنید. این بخش گزینه‌های مختلف برای ایجاد و سپس بازیابی KVMهای رمزگذاری شده و رمزگذاری نشده را شرح می‌دهد.

ایجاد و به‌روزرسانی KVMها

شما می‌توانید KVM ها را به روش‌های زیر ایجاد و به‌روزرسانی کنید:

• سیاست عملیات نقشه ارزش کلیدی (بدون رمزگذاری)

  برای ایجاد و به‌روزرسانی KVM در زمان اجرا توسط پروکسی‌های API خود، از سیاست عملیات نقشه کلید مقدار استفاده کنید. (در این سیاست، نام KVM را در ویژگی mapIdentifier روی عنصر والد مشخص می‌کنید.)

  عنصر <InitialEntries> به شما امکان می‌دهد به محض ذخیره سیاست در رابط کاربری یا استقرار پروکسی API (در صورتی که آن را به صورت آفلاین توسعه داده باشید)، مجموعه‌ای از ورودی‌های پایه را در یک KVM جدید ایجاد و پر کنید. اگر مقادیر در سیاست تغییر کنند، مقادیر موجود بازنویسی می‌شوند. هر کلید/مقدار جدید در کنار کلید/مقدارهای موجود به KVM موجود اضافه می‌شود.

  عنصر <Put> در صورتی که KVM جدیدی از قبل وجود نداشته باشد، آن را ایجاد می‌کند و یک کلید با یک یا چند مقدار ایجاد می‌کند. اگر KVM از قبل وجود داشته باشد، کلید/مقدارهای آن اضافه می‌شوند (یا در صورت وجود کلید، به‌روزرسانی می‌شوند). می‌توانید از چندین عنصر <Put> در یک سیاست KVM استفاده کنید.

• رابط برنامه‌نویسی کاربردی مدیریت

  API مدیریتی برای کار با KVMها به عنوان مدیر سیستم است، نه در زمان اجرا در پروکسی‌های API شما. به عنوان مثال، ممکن است یک اسکریپت داخلی داشته باشید که از API مدیریتی برای حذف و ایجاد مجدد KVMها در یک محیط آزمایشی استفاده کند، یا ممکن است بخواهید مقدار یک کلید را در یک KVM تنظیم مجدد کنید تا همه پروکسی‌ها بتوانند آن را دریافت کنند. (برای دستکاری KVMها در زمان اجرا، از سیاست عملیات نقشه ارزش کلیدی در پروکسی‌های خود استفاده کنید).

  API مدیریت Key/Value Map به شما امکان می‌دهد KVMها و کلیدها/مقادیر رمزگذاری شده را در همه حوزه‌ها (سازمان، محیط و apiproxy) ایجاد، به‌روزرسانی و حذف کنید.

  برای ایجاد یک KVM رمزگذاری شده با رابط برنامه‌نویسی کاربردی مدیریت، "encrypted" : "true" را به فایل JSON اضافه کنید. شما فقط می‌توانید KVMها را هنگام ایجاد رمزگذاری کنید. نمی‌توانید KVM موجود را رمزگذاری کنید.

• رابط کاربری مدیریت

  در رابط کاربری مدیریت Edge، می‌توانید KVMهای با محدوده محیطی ایجاد و به‌روزرسانی کنید، که تنها محدوده KVM هستند که در رابط کاربری ظاهر می‌شوند. رابط کاربری مدیریت، روش خوبی برای مدیریت دستی داده‌های KVM برای پروکسی‌های API در زمان اجرا است. برای اطلاعات بیشتر به ایجاد و ویرایش نقشه‌های کلید-مقدار محیطی مراجعه کنید.

بازیابی KVM ها

شما نگاشت‌های کلید-مقدار رمزگذاری‌شده و رمزگذاری‌نشده را به یک روش بازیابی می‌کنید، با یک تفاوت جزئی هنگام بازیابی با سیاست عملیات نگاشت کلید-مقدار .

• سیاست : از عنصر <Get> در سیاست عملیات نقشه کلید مقدار برای بازیابی KVM های رمزگذاری شده و رمزگذاری نشده استفاده کنید. یک تفاوت جزئی در بازیابی مقادیر رمزگذاری شده با این سیاست وجود دارد، که در آن باید یک پیشوند " private. " به نام متغیری که حاوی مقدار بازیابی شده است اضافه کنید، همانطور که در بخش عملیات Get از موضوع مرجع توضیح داده شده است. این پیشوند، مقدار را از جلسات Trace و اشکال زدایی پنهان می‌کند در حالی که شما در حال اشکال زدایی پروکسی‌های API هستید.
• API مدیریت : برای اهداف مدیریت اداری، می‌توانید از نقشه‌های کلید-مقدار محیط ایجاد و ویرایش برای دریافت KVMها و کلیدها/مقدارها استفاده کنید. به عنوان مثال، اگر می‌خواهید با دریافت و ذخیره تعاریف JSON از KVMها پشتیبان‌گیری کنید، از API مدیریت استفاده کنید. با این حال، توجه داشته باشید که مقادیر رمزگذاری شده در پاسخ API به صورت ***** نمایش داده می‌شوند.
• رابط کاربری مدیریت : شما می‌توانید KVM های خود را که در محدوده محیط قرار دارند، در رابط کاربری مدیریت با رفتن به APIها > پیکربندی محیط > نقشه‌های کلید-مقدار (لبه کلاسیک) یا Admin > محیط‌ها > نقشه‌های کلید-مقدار (لبه جدید) مشاهده کنید.

مثال KVM

برای مثالی از استفاده از KVM برای پر کردن مقادیر در یک URL، به Templateize target URL با KVM توسط environment مراجعه کنید.