מדיניות KeyValueMapsOperations

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מה

מספקת גישה מבוססת-מדיניות לחנות Key Value Map (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>:

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

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

רכיב <Delete>

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

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

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

רכיב <Entry>

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

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

<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 תמיד קוראת מהמטמון לפעולות GET.

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

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

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

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

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

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

רכיב <Get>

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

חשוב לציין את שם ה-KVM באמצעות המאפיין 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 יוצרת את המשתנים הבאים שאפשר להשתמש בהם בתהליך ה-API של שרת ה-proxy:

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

מאפיינים

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

<Get assignTo="private.myvar">

רכיב <InitialEntries>

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

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

גודל המפתח מוגבל ל-2KB גם ל-Edge for Public Cloud וגם ל-Edge for Private Is. ערך ה-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 ברכיב ההורה לא קיימת, המפה נוצרת באופן אוטומטי (כלא מוצפנת). אם מפת ערכי המפתח כבר קיימת, המפתח/הערך יתווסף אליה.

כדי ליצור מפת ערכי מפתח מוצפנת באמצעות Key/Value Maps management API, תוכלו גם לקרוא את המאמר יצירה ועריכה של מפות ערכי מפתח של סביבה כדי ליצור מכונות KVM מוצפנים עם רמת סביבה בממשק המשתמש.

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

מאפיינים

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

רכיב <היקף>

מגדיר את גבול הנגישות למפות של ערכי מפתח. היקף ברירת המחדל הוא environment, כלומר, כברירת מחדל, רשומות המפות משותפות לכל שרתי ה-proxy של ממשק ה-API שפועלים בסביבה (לדוגמה, בדיקה או ייצור). אם מגדירים את ההיקף ל-apiproxy, רק שרת ה-API של ה-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 הוא value. כל צמד מפתח/ערך מאוחסן כרשומה במפת ערכי המפתח. מפה של ערכי מפתח יכולה לאחסן ערכים רבים.

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

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

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

אפשר לשנות מפות של מפתח/ערכים באמצעות המדיניות KeyValueMapOperations, או ישירות דרך ממשק ה-API לניהול Apigee Edge. לפרטים על ה-API של מפתח/ערך מפות של ארגון, אפשר לעיין בחומר העזר בנושא Management 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"/>.

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

• API של מפות ערך/מפתח של הארגון