עבודה עם מפות חשובות

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

יש מקרים שבהם רוצים לאחסן נתונים לצורך אחזור בזמן הריצה – נתונים שלא עומדים לפוג ולא צריכים להיות מקודדים באופן קשיח בלוגיקה של שרת ה-API של שרת ה-API. לשם כך, אידיאליות של מיפוי ערכי מפתח (KVM). KVM הוא אוסף מותאם אישית של צמדי מפתח/ערך מחרוזת מוצפנים או לא מוצפנים. כדי להבין זאת טוב יותר, הינה שתי דוגמאות:

מידע נוסף על סוגים אחרים של שמירת נתונים זמין במאמר הוספה של שמירה במטמון והתמדה.

תרחישי KVM

הנה כמה מצבים שבהם מכונות KVM יכולות להיות שימושיות במיוחד:

• יש לכם שרת proxy ל-API שצריך לקרוא לכתובת URL אחת של יעד (או של יתרונות מרכזיים של שירות) בסביבת בדיקה ולכתובת URL אחרת המשמשת כיעד בסביבת הייצור. במקום לכתוב בתוך ה-proxy כתובות URL שמוטמעות בתוך הקוד, אפשר לבקש משרת ה-Proxy לזהות באיזו סביבה הוא נמצא, להפעיל את המדיניות הרלוונטית של פעולות במפת ערכי המפתחות ולאחזר את כתובת ה-URL הנכונה של היעד מאחת מה-KVMs שיצרתם. לאחר מכן, אם אחד או יותר מהיעדים שלך ישתנה, עליך לעדכן את מכונות ה-KVM בכתובות ה-URL החדשות. שרת ה-proxy אוסף את הערכים החדשים, ולא נדרשת פריסה מחדש של שרת ה-proxy.
• כשרוצים לאחסן פרטי כניסה, מפתחות פרטיים או אסימונים, כמו אסימונים לשירותים חיצוניים, פרטי כניסה שנדרשים ליצירת אסימוני OAuth או מפתחות פרטיים שמשמשים בהסברים ב-Java או ב-JavaScript להצפנה או לחתימה על JSON Web Token (JWT). במקום להעביר בבקשה פרטי כניסה, מפתחות או אסימונים, או לתכנת אותם בתוך הקוד בלוגיקה של שרת ה-proxy, אפשר לאחסן אותם ב-KVM (מוצפנים תמיד) ולאחזר אותם באופן דינמי בקריאות ליעדים שדורשים אותם.

תגלו מצבים אחרים שבהם כדאי לשמור צמדי מפתח/ערך של מחרוזת מפתח/ערך. באופן כללי, כדאי להשתמש במכונות KVM כאשר:

• למקומות ספציפיים בקוד נדרשים ערכים שונים בזמן ריצה.
• יש להעביר מידע אישי רגיש בלי לכתוב אותו בתוך הקוד.
• ברצונך לשמור ערכים שאין להם תאריך תפוגה, כמו מטמון.

למכונות KVM יש היקף

המשמעות של היקף היא "איפה ש-KVM זמין". אפשר ליצור מכונות KVM בהיקפים הבאים: organization, environment ו-apiproxy.

לדוגמה, אם רק שרת proxy אחד של API דורש נתונים ב-KVM, אפשר ליצור את ה-KVM בהיקף של apiproxy, שבו רק לשרת ה-API הזה תהיה גישה לנתונים.

לחלופין, יכול להיות שתרצו שלכל שרתי ה-proxy של ה-API בסביבת הבדיקה תהיה גישה למפת ערכי מפתח. במקרה כזה כדאי ליצור מפה של ערכי מפתח בהיקף של סביבה. שרתי proxy שפרוסים בסביבת ה-prod לא יכולים לגשת למכונות KVM בהיקף של סביבת הבדיקה. אם רוצים שאותם מפתחות KVM יהיו זמינים בסביבת הייצור, צריך ליצור KVM מקביל עם היקף לסביבת ה-prod.

אם רוצים שכל שרתי ה-proxy בכל הסביבות יקבלו גישה לאותה KVM, צריך ליצור את ה-KVM בהיקף organization.

מידע על מכונות KVM מוצפנות

מכונות KVM מוצפנים מוצפנות באמצעות מפתח הצפנה מסוג AES-128 שנוצר על ידי Apigee. המפתח שמשמש להצפנה של KVM מאוחסן בהיקף ה-KVM. לדוגמה, בארגון, כל מכונות ה-KVM המוצפנות שאתם יוצרים ברמת הסביבה נוצרות באמצעות אותו מפתח ברמת הסביבה.

Edge מטפל בהצגת ערכים מוצפנים בדרכים הבאות. (מידע נוסף על יצירת מכונות KVM מוצפנות מפורט במאמר ניהול של מכונות KVM ושימוש בהן).

ממשק המשתמש של Edge

במיפוי של ערכי מפתח מוצפנים מוצגים ערכים מוסווים בכוכביות (*****) בממשק המשתמש. לדוגמה:

Management API

ב-Management API, הערכים המוצפנים מוחזרים לאחר אנונימיזציה. לפניכם דוגמה של תגובה של ממשק API לניהול בקריאה ל-KVM מוצפן:

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

מעקב וניפוי באגים

כשמשתמשים במדיניות Key Value Map Operations כדי לאחזר ערכי KVM מוצפנים, צריך לציין את שם המשתנה שיאחסן את הערך. כדי לקבל ערך מוצפן, צריך להוסיף את הקידומת 'private.' לשם המשתנה. כך לא יופיעו מפתחות/ערכים של KVM בסשנים של מעקב וניפוי באגים.

מגבלות

בארגונים שהופעלו בהם שירותי ליבה של התמדה (CPS):

• השם/מזהה ה-KVM הוא תלוי אותיות רישיות.
• גודל המפתח מוגבל ל-2KB.
• גודל הערך מוגבל ל-10KB.

ב-Apigee Edge לענן פרטי, כל KVM לא יכול לחרוג מ-15MB (הגודל המשולב של המפתחות והערכים). אם חורגים מהמגבלה, תוצג הודעת שגיאה ב-Apigee Edge לענן פרטי. כדי לבדוק את הגודל של מכונות ה-KVM, אפשר להשתמש בפקודה nodetool cfstats.

מכונות KVM גדולות יותר עלולות לפגוע בביצועים. כתוצאה מכך, כדי לשפר את הביצועים צריך לפצל מכונות KVM גדולות ומונוליתיות למכונות קטנות יותר.

ניהול מכונות KVM ושימוש בהן

אפשר ליצור מכונות KVM, לנהל אותן ולהשתמש בהן במגוון דרכים. בקטע הזה מתוארות אפשרויות שונות ליצירה ולאחזור של מכונות KVM מוצפנים ולא מוצפנים.

יצירה ועדכון של מכונות KVM

אפשר ליצור ולעדכן מכונות KVM בדרכים הבאות:

• מדיניות בנושא פעולות במפת ערך מפתח (ללא הצפנה)

  כדי ליצור ולעדכן קובצי KVM בזמן ריצה באמצעות שרתי proxy של API, צריך להשתמש במדיניות של Key Value Map Operations. (במדיניות מציינים את שם ה-KVM במאפיין mapIdentifier ברכיב ההורה).

  הרכיב <InitialEntries> מאפשר ליצור ולאכלס קבוצת ערכים בסיסית ב-KVM חדש, מיד אחרי ששומרים את המדיניות בממשק המשתמש או אחרי שפורסים את שרת ה-API של ה-API (אם פיתחתם אותו במצב אופליין). אם הערכים ישתנו במדיניות, הערכים הקיימים יוחלפו. המפתחות או הערכים החדשים יתווספו ל-KVM הקיים לצד המפתחות או הערכים הקיימים.

  הרכיב <Put> יוצר KVM חדש, אם הוא לא קיים, ויוצר מפתח עם ערך אחד או יותר. אם ה-KVM כבר קיים, המפתח/הערכים מתווספים (או מעודכנים אם המפתח כבר קיים). אפשר להשתמש בכמה רכיבי <Put> במדיניות KVM.

• Management API

  ה-Management API מיועד לעבודה עם מכונות וירטואליות (KVM) כאדמינים ולא במהלך זמן ריצה בשרתי ה-API של ה-API. לדוגמה, יכול להיות שיש לכם סקריפט פנימי שמשתמש ב-API לניהול כדי למחוק וליצור מחדש מכונות KVM בסביבת בדיקה, או לאפס את הערך של מפתח ב-KVM כדי שכל שרתי ה-proxy יאספו. (למניפולציה של מכונות KVM בזמן ריצה, משתמשים במדיניות Key Value Map Operations בשרתי ה-proxy שלכם).

  Key/Value Maps Management API מאפשר ליצור, לעדכן ולמחוק מפתחות/ערכים מוצפנים, מפתחות/ערכים מוצפנים בכל ההיקפים (ארגון, סביבה ו-apiproxy).

  כדי ליצור KVM מוצפן באמצעות ממשק ה-API לניהול, צריך להוסיף את "encrypted" : "true" למטען הייעודי (payload) של JSON. אפשר להצפין מכונות KVM רק כשיוצרים אותן. אי אפשר להצפין KVM קיים.

• ממשק משתמש לניהול

  בממשק המשתמש לניהול Edge אפשר ליצור ולעדכן מכונות KVM ברמת הסביבה, שהן ההיקף היחיד של KVM שמופיע בממשק המשתמש. ממשק המשתמש לניהול מאפשר לנהל נתוני KVM באופן ידני דרך שרתי proxy של API בזמן ריצה. מידע נוסף זמין במאמר יצירה ועריכה של מפות של ערכי מפתח של סביבה.

אחזור KVMs

מאחזרים מיפוי של ערכי מפתח מוצפנים ולא מוצפנים באותו אופן, עם שינוי קל אחד באחזור באמצעות המדיניות בנושא פעולות במפת ערכי מפתח.

• Policy: שימוש ברכיב <Get> במדיניות Key Value Map Operations כדי לאחזר מכונות KVM מוצפנים ולא מוצפנים. ההבדל הקטן היחיד הוא אחזור ערכים מוצפנים באמצעות המדיניות. צריך להוסיף את הקידומת "private." לשם המשתנה שיכיל את הערך שאוחזר, כפי שמתואר בקטע 'קבלת פעולה' של נושא ההפניה. הקידומת הזו מסתירה את הערך מסשנים של מעקב וניפוי באגים בזמן ניפוי באגים בשרתי proxy של API.
• Management API: למטרות ניהול אדמיניסטרטיבי, תוכלו להשתמש במאמר יצירה ועריכה של מפות של ערכי מפתחות של הסביבה כדי לקבל מכונות KVM ומפתחות/ערכים. לדוגמה, אם רוצים לגבות מכונות KVM באמצעות קבלה ואחסון של הגדרות ה-JSON, צריך להשתמש ב-Management API. עם זאת, חשוב לזכור שהערכים המוצפנים מוצגים כ-***** בתגובת ה-API.
• Management UI: אפשר להציג את מכונות ה-KVM ברמת הסביבה בממשק המשתמש של הניהול. לשם כך צריך לעבור אל APIs > Environment Configuration > Key Value Maps (Classic Edge) או Admin > Environments > Key Value Maps (ממשק חדש של Edge).

דוגמה ל-KVM

דוגמה לשימוש ב-KVM כדי לאכלס ערכים בכתובת URL: https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.