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

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

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

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

תרחישי KVM

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

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

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

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

ל-KVM יש היקף

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

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

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

אם רוצים שכל השרתים הפרוקסי בכל הסביבות יוכלו לגשת לאותו 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 בדרכים הבאות:

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

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

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

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

• ‫Management API

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

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

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

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

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

אחזור של מכונות KVM

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

• מדיניות: משתמשים ברכיב <Get> במדיניות הפעולות של מיפוי ערכי מפתח כדי לאחזר KVM מוצפנים ולא מוצפנים. ההבדל הקטן היחיד הוא בשליפת ערכים מוצפנים באמצעות המדיניות. במקרה כזה, צריך להוסיף את הקידומת private. לשם המשתנה שיכיל את הערך שנשלף, כמו שמתואר בקטע 'פעולת Get' בנושא ההפניה. הקידומת הזו מסתירה את הערך מפגישות של מעקב וניפוי באגים בזמן ניפוי באגים בשרתי proxy של API.
• ‫Management API: למטרות ניהול אדמיניסטרטיבי, אפשר להשתמש ביצירה ועריכה של מיפויים של מפתחות וערכים של סביבות כדי לקבל מיפויים של מפתחות וערכים ומפתחות/ערכים. לדוגמה, אם רוצים לגבות מכונות KVM על ידי אחזור והגדרה של הגדרות JSON, צריך להשתמש ב-Management API. חשוב לזכור שערכים מוצפנים מוצגים כ-***** בתגובת ה-API.
• ממשק משתמש לניהול: אפשר לראות את מיפויי זוגות הערכים של KVM בהיקף סביבה בממשק המשתמש לניהול. כדי לעשות את זה, עוברים אל ממשקי API > הגדרת סביבה > מיפויי זוגות ערכים (גרסה קלאסית של Edge) או אל Admin > סביבות > מיפויי זוגות ערכים (גרסה חדשה של Edge).

דוגמה ל-KVM

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