מדיניות 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> רכיב

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

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

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

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

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

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

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

1. פעולת GET מאחזרת את הערך שלrating, שמוסיף את הערך '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 יוצר את הדברים הבאים משתנים שבהם אפשר להשתמש בתהליך ה-Proxy ל-API:

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

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

גודל המפתח מוגבל ל-2KB גם ב-Edge עבור ענן ציבורי וגם Edge ל'פרטי'. ערך ה-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>
  

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

<Scope> רכיב

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

סכימות

הערות שימוש

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

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