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

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

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

برای آشنایی با انواع دیگر ماندگاری، به افزودن حافظه پنهان و ماندگاری مراجعه کنید.

سناریوهای KVM

در اینجا مواردی وجود دارد که KVM ها به کار می آیند:

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

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

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

KVM ها دارای دامنه هستند

دامنه به معنای "جایی که KVM در دسترس است." KVM ها را می توان در حوزه های زیر ایجاد کرد: organization ، environment ، و apiproxy .

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

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

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

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

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

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

رابط کاربری لبه

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

مدیریت API

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

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

ردیابی و رفع اشکال

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

محدودیت ها

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

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

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

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

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

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

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

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

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

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

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

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

• مدیریت API

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

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

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

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

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

بازیابی KVM

شما نقشه های ارزش کلید رمزگذاری شده و رمزگذاری نشده را به همان روش بازیابی می کنید، با یک تغییر جزئی هنگام بازیابی با خط مشی عملیات نقشه ارزش کلیدی .

• خط مشی : از عنصر <Get> در خط مشی عملیات نقشه ارزش کلیدی برای بازیابی KVM های رمزگذاری شده و رمزگذاری نشده استفاده کنید. یک تفاوت جزئی بازیابی مقادیر رمزگذاری شده با این خط مشی است، جایی که باید یک پیشوند " private. " به نام متغیر اضافه کنید که حاوی مقدار بازیابی شده است، همانطور که در بخش عملیات Get در مبحث مرجع توضیح داده شده است. این پیشوند مقدار را از جلسات Trace و Debug پنهان می کند، در حالی که شما در حال اشکال زدایی پراکسی های API هستید.
• مدیریت API : برای اهداف مدیریت اداری، می‌توانید از ایجاد و ویرایش نقشه‌های ارزش کلیدی محیط برای دریافت KVM و کلید/مقدار استفاده کنید. به عنوان مثال، اگر می خواهید با گرفتن و ذخیره تعاریف JSON از KVM ها نسخه پشتیبان تهیه کنید، از API مدیریت استفاده کنید. اما توجه داشته باشید که مقادیر رمزگذاری شده به صورت ***** در پاسخ API نمایش داده می شوند.
• رابط کاربری مدیریت : می‌توانید با رفتن به APIs > Environment Configuration > Key Value Maps (Classic Edge) یا Admin > Environments > Key Value Maps (New Edge)، KVM‌های محیطی خود را در رابط کاربری مدیریت مشاهده کنید.

مثال KVM

برای مثالی از استفاده از KVM برای پر کردن مقادیر در URL، به https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html مراجعه کنید.