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

הדף הזה רלוונטי ל-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 המתאים.

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

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

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

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

במקרים מסוימים, קבוצות של מאפיינים הן חלופה טובה ל-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, משתמשים בהגדרה 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 מוצגת רשימה של מיפויים קיימים של מפתח וערך. אם לא יצרתם מיפויים כאלה, הרשימה תהיה ריקה.

  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 שלכם, משתמשים במדיניות KeyValueMapOperations. במדיניות, מציינים את השם של ה-KVM במאפיין mapIdentifier ברכיב האב.

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

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

ניפוי באגים

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

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

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

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

  1. ניגשים לרשימת זוגות מפתח/ערך בסביבה שלכם (ראו יצירת זוגות מפתח/ערך).
  2. בדף Key value maps (מיפויים של ערכי מפתח) מוצגת רשימה של מיפויים קיימים של ערכי מפתח.
  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. לוחצים על הכרטיסייה Key value maps בדף Environment details.

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

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

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

Apigee API

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