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

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

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

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

תרחישי KVM

דוגמאות למצבים שבהם KVMs יכולה להיות שימושית:

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

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

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

למכונות וירטואליות יש היקף

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

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

לחלופין, יכול להיות שתרצו שלכל שרתי ה-proxy ל-API בסביבת הבדיקה תהיה גישה למיפוי של ערכי מפתח, במקרה כזה תצרו מפת ערכי מפתח בהיקף הסביבה. שרתי proxy שנפרסו 'prod' לא ניתן לגשת למכונות הווירטואליות ב-"test" של הסביבה. אם רוצים להשתמש באותו 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"
}

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

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

מגבלות

בארגונים עם ליבה Persistence Services (CPS) מופעלים:

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

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

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

ניהול KVMs ושימוש בהם

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

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

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

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

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

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

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

• Management API

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

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

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

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

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

אחזור KVM

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

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

דוגמה ל-KVM

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