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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

תרחישי KVM

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

• יש לכם API proxy שצריך לקרוא לכתובת URL אחת של יעד (או Service Callout) בסביבת בדיקה ולכתובת URL אחרת של יעד בסביבת ייצור. במקום להגדיר כתובות URL בהארדקוד בשרת ה-proxy, אפשר להגדיר את שרת ה-proxy כך שיזהה את הסביבה שבה הוא נמצא, יפעיל את המדיניות שקשורה לפעולות של מיפוי זוגות מפתח/ערך ויאחזר את כתובת ה-URL הנכונה של היעד מאחד ממיפויי זוגות מפתח/ערך שיצרתם. אם בהמשך אחד מהיעדים או שניהם משתנים, פשוט מעדכנים את זוגות המפתח/ערך עם כתובות ה-URL החדשות. ה-proxy מאחזר את הערכים החדשים, ואין צורך בפריסה מחדש של ה-proxy.
• אתם רוצים לאחסן פרטי כניסה, מפתחות פרטיים או אסימונים – כמו אסימונים לשירותים חיצוניים, פרטי כניסה שנדרשים ליצירת אסימוני OAuth או מפתחות פרטיים שמשמשים ב-Java Callouts או ב-JavaScript להצפנה או לחתימה על אסימון אינטרנט מסוג JSON ‏ (JWT). במקום להעביר פרטי כניסה, מפתחות או טוקנים בבקשה, או לקודד אותם באופן קשיח בלוגיקה של ה-proxy, אפשר לאחסן אותם ב-KVM (תמיד מוצפנים) ולאחזר אותם באופן דינמי בקריאות ליעדים שדורשים אותם.

תגלו מצבים נוספים שבהם אחסון של צמדי מפתח/ערך מסוג String יכול להיות שימושי. באופן כללי, כדאי להשתמש ב-KVMs במקרים הבאים:

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

ל-KVM יש היקף

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

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

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

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

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

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

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

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

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

Management API

ב-Management API, ערכים מוצפנים מוחזרים עם מסכה. בהמשך מוצגת דוגמה לתגובה של Management API לקריאה של Get encrypted 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 for Private Cloud, כל KVM לא יכול לחרוג מ-15MB (זהו הגודל המשולב של המפתחות והערכים). אם חורגים מהמגבלה הזו, Apigee Edge for Private Cloud מחזיר שגיאה. כדי לקבוע את הגודל של מכונות ה-KVM, אפשר להשתמש בפקודה nodetool cfstats.

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

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

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

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

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

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

  כדי ליצור ולעדכן KVM בזמן ריצה באמצעות שרתי proxy של API, משתמשים במדיניות של פעולות במפת ערכי מפתח. (במדיניות, מציינים את השם של KVM במאפיין mapIdentifier ברכיב ההורה).

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

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

• ‫Management API

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

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

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

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

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

אחזור של KVM

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

• מדיניות: משתמשים ברכיב <Get> במדיניות Key Value Map Operations כדי לאחזר KVM מוצפנים ולא מוצפנים. ההבדל הקטן היחיד הוא בשליפת ערכים מוצפנים באמצעות המדיניות. במקרה כזה, צריך להוסיף את הקידומת private. לשם המשתנה שיכיל את הערך שנשלף, כמו שמתואר בקטע 'פעולת Get' בנושא ההפניה. הקידומת הזו מסתירה את הערך מפגישות של מעקב וניפוי באגים בזמן ניפוי באגים בשרתי proxy של API.
• ‫Management API: למטרות ניהול אדמיניסטרטיבי, אפשר להשתמש ב-Creating and editing environment key value maps כדי לקבל KVM ומפתחות/ערכים. לדוגמה, אם רוצים לגבות מכונות וירטואליות של KVM על ידי אחזור והגדרה של הגדרות JSON, צריך להשתמש ב-Management API. חשוב לזכור שערכים מוצפנים מוצגים כ-***** בתגובת ה-API.
• ממשק משתמש לניהול: כדי לראות את מיפויי זוגות הערכים של KVM בהיקף הסביבה, עוברים אל ממשקי API > הגדרת סביבה > מיפויי זוגות ערכים (Classic Edge) או אל Admin > סביבות > מיפויי זוגות ערכים (New Edge).

דוגמה ל-KVM

דוגמה לשימוש ב-KVM כדי לאכלס ערכים בכתובת URL מופיעה במאמר בנושא יצירת תבנית של כתובת יעד עם KVM לפי סביבה.