שימוש במפות של מפתח/ערך

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בקטע הזה מוסבר איך להשתמש במיפויים של מפתח/ערך (KVM).

סקירה כללית

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

בהמשך מפורטים שלושה תרחישי שימוש כלליים לאחסון נתונים במשתני KVM:

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

    לדוגמה: יש לכם proxy ל-API שצריך לקרוא לכתובת URL אחת של יעד (או Service Callout) בסביבת בדיקה ולכתובת URL אחרת של יעד בסביבת ייצור. במקום להגדיר כתובות URL בתוך הקוד של proxy ל-API, אפשר להגדיר אותו כך שיזהה את הסביבה שבה הוא נמצא, יבצע את מדיניות KeyValueMapOperations שקשורה אליה ויאחזר את כתובת ה-URL הנכונה של היעד מ-KVM המתאים.

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

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

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

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

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

מידע על היקף השימוש ב-KVM

ההיקף מגדיר איפה KVM זמין. אפשר ליצור משתני KVM בהיקפים הבאים:

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

מידע על הצפנה ב-KVM

ב-Apigee, כל הרשומות ב-KVM עבור היקפי proxy ל-API, ארגון וסביבה מוגנות באמצעות מפתח Cloud KMS שסופק כשמוקצה ארגון Apigee (ראו את השדה runtimeDatabaseEncryptionKey במשאב Organization). ב-Apigee נעשה שימוש ב-AES256 כתקן הצפנה.

ב-Apigee hybrid, אפשר לספק מפתחות הצפנה נפרדים לכל רשומות ה-KVM עבור API proxy, ארגון והיקפי סביבה. ‫Apigee מקבל גדלים של צופן AES128, ‏ AES196 או AES256 כסטנדרט ההצפנה.

מידע על אנונימיזציה של KVM

כברירת מחדל, ערכי KVM מוצגים כטקסט פשוט. אפשר להפעיל אנונימיזציה של KVM כדי להסתיר ערכים באמצעות כוכביות (*****). כדי להפעיל או להשבית אנונימיזציה של KVM, משתמשים בהגדרה Mask values בממשק המשתמש או בדגל maskedValues בבקשת ה-API.

הערכים מוסתרים ברמת KVM. אי אפשר להסוות רשומות KVM בודדות. אפשר להסוות את כל הערכים ב-KVM או לא להסוות אף אחד מהם.

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

יצירת מכונות KVM

יוצרים KVM כמו שמתואר בקטעים הבאים.

ממשק המשתמש של Apigee

כדי ליצור KVM חדש (ריק) או להציג רשימה של KVM:

  1. במסוף Google Cloud , עוברים לדף Apigee > Management > Environments.

    מעבר אל Environments

  2. בוחרים את הסביבה שרוצים לערוך מתוך רשימת הסביבות הזמינות.
  3. לוחצים על הכרטיסייה Key value maps (מפות של מפתח/ערך) בדף Environment details (פרטי הסביבה).

    בדף Key value maps (מיפויים של זוגות מפתח/ערך) מוצגת רשימה של מיפויי KVM קיימים. אם לא יצרתם אף KVM, הרשימה תהיה ריקה.

  4. כדי ליצור KVM חדש (ריק), לוחצים על + Create Key value map.

    תיפתח תיבת הדו-שיח Create key value map (יצירת מיפוי של זוגות מפתח/ערך).

  5. מזינים שם ל-KVM בשדה Key value map name (שם מיפוי של זוגות מפתח/ערך).

    השם יכול להכיל רק אותיות, מספרים ומקפים, והוא לא יכול להיות ארוך מ-255 תווים. הוא לא יכול לכלול רווחים או תווים מיוחדים אחרים. לדוגמה: my-kvm-1

  6. לוחצים על Mask values (הסתרת ערכים) כדי להסתיר את כל הערכים. אם לא בוחרים את האפשרות הזו, ערכי ה-KVM מוצגים כטקסט רגיל. מידע נוסף זמין במאמר מידע על אנונימיזציה של KVM.
  7. לוחצים על יצירה.

    ה-KVM החדש מוצג ברשימה.

Apigee API

אפשר להשתמש בממשקי Apigee API כדי ליצור, להציג ולמחוק KVM בהיקפים הבאים:

מדיניות KVM

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

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

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

ניפוי באגים

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

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

אפשר להשתמש ב-Apigee APIs כדי לקבל KVMs להיקפים הבאים:

לדוגמה, כדי לקבל KVM בהיקף של API proxy, מזינים בקשת GET לכתובת ה-URL הבאה:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

עדכון של מכונות KVM

אפשר להשתמש ב-Apigee APIs כדי לעדכן את KVMs בהיקפים הבאים:

לדוגמה, כדי לקבל KVM בהיקף של API proxy, מזינים בקשת GET לכתובת ה-URL הבאה:

https://apigee.googleapis.com/v1/organizations/ORG/apis/API/keyvaluemaps/KVM

ניהול ערכי KVM

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

ניהול ערכי KVM באמצעות API

משתמשים בממשקי ה-API של Apigee כדי לנהל ערכי KVM בהיקפים הבאים:

ניהול ערכי KVM באמצעות מדיניות KeyValueMapOperations

משתמשים במדיניות KeyValueMapOperations כדי להוסיף, לקבל או למחוק ערכים מ-KVM.

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

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

כדי למחוק ערכים של KVM, משתמשים ברכיב <Delete> של המדיניות KeyValueMapOperations. מידע נוסף זמין במאמר בנושא האלמנט<Delete>.

מחיקת מכונות וירטואליות של KVM

מוחקים את ה-KVM כמו שמתואר בקטעים הבאים.

ממשק המשתמש של Apigee

כדי למחוק KVM:

  1. במסוף Google Cloud , עוברים לדף Apigee > Management > Environments.

    מעבר אל Environments

  2. בוחרים את שם הסביבה שרוצים לערוך מתוך רשימת הסביבות הזמינות.
  3. לוחצים על הכרטיסייה Key value maps (מפות של מפתח/ערך) בדף Environment details (פרטי הסביבה).

    בדף Key value maps (מיפויים של זוגות מפתח/ערך) מוצגת רשימה של מיפויי KVM קיימים.

  4. מאתרים את השורה של מכונת ה-KVM שרוצים למחוק.
  5. לוחצים על בעמודה פעולות.
  6. בתיבת הדו-שיח, לוחצים על מחיקת מיפוי ערכי מפתח כדי לאשר את הפעולה.

    ה-KVM נמחק ומוסר מהרשימה.

Apigee API

כדי למחוק KVM על סמך ההיקף שלו, משתמשים באחד מממשקי ה-API הבאים של Apigee: