מדיניות KeyValueMapOperations

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

מה

מאפשרת גישה למאגר של מפת מפתח-ערך (KVM) שזמין ב-Apigee Edge על סמך מדיניות. אפשר לאחסן, לאחזר ולמחוק צמדי מפתח/ערך ממפות קיימות עם שם באמצעות הגדרת מדיניות של KeyValueMapOperations שמציינת פעולות PUT,‏ GET או DELETE. (המדיניות צריכה לבצע לפחות אחת מהפעולות האלה).

סרטונים

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

דוגמאות

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter>
      </Key>
   </Get>
</KeyValueMapOperations>

הפניה לרכיב

הפניה לרכיב מתארת את הרכיבים והמאפיינים של מדיניות KeyValueMapOperations:

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

מאפייני <KeyValueMapOperations>

בדוגמה הבאה מוצגים המאפיינים בתג <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

בטבלה הבאה מפורטים המאפיינים הספציפיים לתג <KeyValueMapOperations>:

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

אלמנט <Delete>

מחיקת צמד המפתח/הערך שצוין. צריך להשתמש לפחות באחד מהמאפיינים הבאים: <Get>, <Put> או <Delete>.

חשוב לציין את השם של זוג הערכים של מפתח/ערך באמצעות המאפיין mapIdentifier ברכיב ההורה. לדוגמה:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

אלמנט <Entry>

ערכי seed למיפויים של ערכי מפתח, שמאוכלסים במיפויים של ערכי מפתח כשהם מאותחלים.

ב-Edge for Public Cloud, גודל המפתח מוגבל ל-2KB. לדוגמה:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

אלמנט <ExclusiveCache>

הוצא משימוש. במקומו צריך להשתמש ברכיב <Scope>.

אלמנט <ExpiryTimeInSecs>

ההגדרה הזו קובעת את משך הזמן בשניות שבסיומו Edge ירענן את הערך ששמור במטמון מתוך ה-KVM שצוין.

אם הערך הוא 0 או ‎-1, או אם לא כוללים את הרכיב הזה, המערכת תשתמש בערך ברירת המחדל של 300 שניות. לדוגמה:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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

רכיב <ExpiryTimeInSecs> מאפשר לקבוע כמה זמן יישמרו במטמון המפתחות והערכים שמשמשים במדיניות לפני שהם יתעדכנו שוב מ-KVM. עם זאת, יש הבדלים בין האופן שבו פעולות GET ו-PUT משפיעות על תפוגת המטמון.

‫GET – בפעם הראשונה שמופעלת פעולת GET של KVM, המפתחות או הערכים המבוקשים מ-KVM (שהשם שלו מצוין במאפיין הבסיס mapIdentifier של המדיניות) נטענים למטמון, והם נשארים שם לפעולות GET הבאות עד שאחד מהמקרים הבאים מתרחש:

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

‫PUT – פעולת PUT כותבת מפתחות/ערכים ל-KVM שצוין. אם הפקודה PUT כותבת למפתח שכבר קיים במטמון, המטמון הזה מתרענן באופן מיידי ועכשיו הוא מכיל את הערך החדש למספר השניות שצוין ברכיב <ExpiryTimeInSecs> של המדיניות.

דוגמה – שמירה במטמון של KVM

1. פעולת GET מאחזרת את הערך של 'rating', שמוסיף את הערך '10' למטמון. הערך של <ExpiryTimeInSecs> במדיניות הוא 60.
2. 30 שניות לאחר מכן, מדיניות ה-GET מופעלת שוב ומאחזרת את הערך '10' מהמטמון.
3. 5 שניות לאחר מכן, מדיניות PUT מעדכנת את הערך של 'דירוג' ל-'8', והערך של <ExpiryTimeInSecs> במדיניות PUT הוא 20. המטמון מתעדכן מיידית עם הערך החדש, שמוגדר עכשיו להישאר במטמון למשך 20 שניות. (אם לא היה PUT, המטמון שאוכלס במקור על ידי ה-GET הראשון עדיין היה קיים למשך 30 שניות נוספות, מתוך 60 השניות המקוריות).
4. 15 שניות לאחר מכן, מתבצעת עוד בקשת GET ומקבלים את הערך '8'.

אלמנט <Get>

הפונקציה מאחזרת את הערך של המפתח שצוין. צריך להשתמש לפחות באחד מהמאפיינים הבאים: <Get>, <Put> או <Delete>.

חשוב לציין את השם של זוג הערכים של מפתח/ערך באמצעות המאפיין mapIdentifier ברכיב האב.

אפשר לכלול כמה בלוקים של Get במדיניות כדי לאחזר כמה פריטים מ-KVM.

קבלת פריט בודד מ-KVM

<Get assignTo="myvar" index="1">
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Get>

קבלת כמה פריטים ממכונת KVM

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

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

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

כשמתבצעת קריאה לשרת proxy ל-API, ‏ Edge יוצר את המשתנים הבאים שאפשר להשתמש בהם בתהליך של שרת ה-proxy ל-API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

מאפיינים

בטבלה הבאה מפורטים המאפיינים של הרכיב <Get>:

<Get assignTo="private.myvar">

אלמנט <InitialEntries>

ערכי seed למיפויים של ערכי מפתח, שמאוכלסים במיפויים של ערכי מפתח כשהם מאותחלים. חשוב לציין את השם של זוג המפתחות והערכים באמצעות המאפיין mapIdentifier ברכיב ההורה. לדוגמה:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

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

המפתחות והערכים שמאוכלסים על ידי הרכיב הזה חייבים להיות ליטרלים. לדוגמה, אי אפשר להשתמש ב-<Parameter ref="request.queryparam.key"> בתוך הרכיב הזה.

גודל המפתח מוגבל ל-2KB גם ב-Edge for the Public Cloud וגם ב-Edge for the Private Could. הערך של KVM מוגבל ל-2KB.

כדי ליצור KVM מוצפן, משתמשים ב-Key/Value Maps management API.

רכיב <Key>

מציין את המפתח ברשומה של מפה עם מפתח/ערך. מפתח יכול להיות מורכב, כלומר אפשר לצרף יותר מפרמטר אחד כדי ליצור את המפתח. לדוגמה, אפשר לשלב את המשאבים userID ו-role כדי ליצור את המשאב key. לדוגמה:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

חשוב לעיין ברכיב <Parameter> כדי לקבל מידע ספציפי על אופן ההגדרה של שם המפתח.

ב-Edge for Public Cloud, גודל המפתח מוגבל ל-2KB. מידע נוסף מופיע במאמר ההבדלים בין Edge for Public Cloud API לבין Private Cloud API.

אלמנט <Parameter>

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

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

• מחרוזת מילולית

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• משתנה לאחזור בזמן הריצה, באמצעות המאפיין ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• שילוב של ערכים מילוליים והפניות למשתנים

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

כשהאלמנט Key כולל כמה אלמנטים של Parameter, מחרוזת המפתח האפקטיבית היא שרשור של הערכים של כל פרמטר, עם קו תחתון כפול ביניהם. לדוגמה, בדוגמה שלמעלה, אם למשתנה apiproxy.name יש את הערך abc1, אז המפתח בפועל יהיה targeturl__abc1__weight.

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

מאפיינים

בטבלה הבאה מפורטים המאפיינים של הרכיב <Parameter>:

אלמנט <Put>

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

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

<Put override="false">
   <Key>
      <Parameter ref="mykeyvar"/>
   </Key>
   <Value ref="myvalvar1"/>
</Put>

מאפיינים

בטבלה הבאה מפורטים המאפיינים של הרכיב <Put>:

אלמנט <Scope>

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

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

<Scope>environment</Scope>

רכיב <Value>

מציין את הערך של מפתח. אפשר לציין את הערך כמחרוזת מילולית או, באמצעות מאפיין ref, כמשתנה שיש לאחזר בזמן הריצה:

<!-- Specify a literal value -->
<Value>literal<Value>

או:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

אפשר גם לכלול כמה רכיבי <Value> כדי לציין ערך מרובה חלקים. הערכים משולבים בזמן הריצה.

בדוגמה הבאה, שני מפתחות נוספים ל-KVM:

• מפתח k1 עם ערכים v1,v2
• מפתח k2 עם ערכים v3,v4

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

בדוגמה הבאה, נוצר מפתח אחד עם שני ערכים. נניח ששם הארגון הוא foo_org, שם ה-proxy ל-API הוא bar והסביבה היא test:

• מפתח foo_org עם ערכים bar,test

<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>

מאפיינים

בטבלה הבאה מפורטים המאפיינים של הרכיב <Value>:

הפניה לשגיאה

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

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

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

סכימות

הערות שימוש

במאמר עבודה עם מיפויים של צמדי מפתח/ערך מופיעה סקירה כללית של מיפויים של צמדי מפתח/ערך.

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

לדוגמה, localhost=127.0.0.1, ‏ zip_code=94110 או first_name=felix. בדוגמה הראשונה, localhost הוא מפתח ו-127.0.0.1 הוא ערך. כל צמד מפתח/ערך מאוחסן כרשומה במיפוי של מפתח ערך. במפה עם מפתח/ערך אפשר לאחסן הרבה רשומות.

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

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

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

אפשר לשנות מפות של מפתח/ערך באמצעות מדיניות KeyValueMapOperations, או ישירות באמצעות Apigee Edge Management API. פרטים על Organization key/value maps API זמינים במאמרי העזרה של ה-API לניהול. אפשר להשתמש ב-API כדי, לדוגמה, להעלות מערכי נתונים גדולים למאגר של זוגות מפתח/ערך, או ליצור סקריפטים לניהול של רשומות במפת זוגות מפתח/ערך. תצטרכו ליצור מפה עם מפתח/ערך באמצעות ה-API לפני שתגשו אליה באמצעות המדיניות KeyValueMapOperations.

ציון שמות של מפתחות ואחזור שלהם

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

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

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

במקרה הראשון, הערך המילולי של key_name_literal מאוחסן ב-KVM כשם המפתח. במקרה השני, הערך שנמצא ב-key.name.variable הופך לשם המפתח ב-KVM. לדוגמה, אם key.name.variable הכיל את הערך foo, שם המפתח יהיה foo.

כשרוצים לאחזר את המפתח ואת ערך המפתח באמצעות פעולת GET (או למחוק באמצעות פעולת DELETE), ההגדרה <Parameter> צריכה להיות זהה לשם המפתח ב-KVM. לדוגמה, אם שם המפתח ב-KVM הוא foo, אפשר לציין את הערך המילולי עם <Parameter>foo</Parameter> או לציין משתנה שמכיל את הערך המדויק foo, כך: <Parameter ref="variable.containing.foo"/>.

נושאים קשורים

• ‫Organization key/value maps API