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

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

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

מידע על היקף KVM

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

היקף תיאור
proxy ל-API רק ל-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, משתמשים בהגדרה הסתרת ערכים בממשק המשתמש או בדגל maskedValues בבקשת ה-API.

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

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

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

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

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

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

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

    מעבר אל Environments

  2. בוחרים את הסביבה שרוצים לערוך מתוך רשימת הסביבות הזמינות.
  3. בדף פרטי הסביבה, לוחצים על הכרטיסייה מפות מפתח/ערך.

    בדף מיפוי ערכי מפתח מוצגת רשימה של 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

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

  1. ניגשים לרשימת זוגות מפתח/ערך בסביבה שלכם (ראו יצירת זוגות מפתח/ערך).
  2. בדף מיפוי ערכי מפתח מוצגת רשימה של KVM קיימים.
  3. לוחצים על השם של KVM כדי לראות את הרשומות וההגדרות שלו.

Apigee API

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

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

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

עדכון של מכשירי KVM

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

כדי לעדכן את ההגדרה Mask values של KVM קיים בממשק המשתמש של Apigee:

  1. ניגשים לרשימת זוגות מפתח/ערך בסביבה שלכם (ראו יצירת זוגות מפתח/ערך).
  2. בוחרים את השם של ה-KVM כדי לפתוח את דף הפרטים שלו.
  3. מחליפים את המצב של ההגדרה הסתרת ערכים.
  4. לוחצים על Save.

Apigee API

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

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

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

ניהול ערכי KVM

אפשר לנהל את ערכי ה-KVM באמצעות השיטות הבאות:

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

כדי לנהל רשומות KVM בממשק המשתמש של Apigee:

  1. ניגשים לרשימת זוגות מפתח/ערך בסביבה שלכם (ראו יצירת זוגות מפתח/ערך).
  2. בוחרים את השם של ה-KVM כדי לפתוח את דף הפרטים שלו.
  3. כדי לנהל את הרשומות:
    • הוספת רשומה: לוחצים על + הוספה. ממלאים את השדות Key (מפתח) ו-Value (ערך) ולוחצים על Add (הוספה).
    • עריכת רשומה: לוחצים על עריכה לצד הרשומה. מעדכנים את הערך ולוחצים על שמירה.
    • מחיקת רשומה: לוחצים על מחיקה לצד הרשומה. לוחצים על מחיקה בתיבת הדו-שיח לאישור.

Apigee API

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

המדיניות KeyValueMapOperations

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

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

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

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

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

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

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

כדי למחוק KVM:

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

    מעבר אל Environments

  2. בוחרים את שם הסביבה שרוצים לערוך מתוך רשימת הסביבות הזמינות.
  3. בדף פרטי הסביבה, לוחצים על הכרטיסייה מפות מפתח/ערך.

    בדף מיפוי ערכי מפתח מוצגת רשימה של KVM קיימים.

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

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

Apigee API

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