Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

מדיניות KeyValueMapOperations

מדיניות ניתנת להרחבה

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

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

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

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

הערה: החל מגרסה 1.4.0 של Apigee Hybrid,‏ Apigee מצפין את כל ה-KVM כברירת מחדל. כדי להסתיר את פרטי ה-KVM בסשן ניפוי באגים, צריך להשתמש במאפיין private. עם כל המשתנים כשניגשים ל-KVM באמצעות הפקודה GET. אם לא משתמשים במאפיין private., ה-KVM עדיין מוצפן, אבל המידע של ה-KVM יופיע מפוענח בסשן של Debug ולא תופעל חריגה.

סרטון: בסרטון הבא מוצג מבוא כללי ל-KVM.

דוגמאות

הצבת KVM עם ליטרל

כשמריצים את המדיניות הבאה, נוצר KVM מוצפן בשם FooKVM, ואז נוצר מפתח בשם FooKey_1 עם שני ערכים שמוגדרים באמצעות המחרוזות המילוליות foo ו-bar (לא מוגדרים עם ערכים שחולצו ממשתנים). כשמשתמשים במפתח GET בדוגמה הבאה, מציינים מספר אינדקס כדי לאחזר את הערך הרצוי.

<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>

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

קבלת KVM מליטרל

המדיניות הזו בודקת את המפה FooKVM מהדוגמה הקודמת, מקבלת את הערך השני (index="2") מהמפתח FooKey_1 ומאחסנת אותו במשתנה שנקרא foo_variable.

<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>

גישה דינמית ל-KVM

המדיניות הזו משתמשת ברכיב <MapName> כדי להפנות באופן דינמי ל-KVM עם משתנה של זרימת נתונים. האלמנט שולף את מזהה ה-KVM ממשתנה הזרימה. שימו לב שהמאפיין mapIdentifier לא מופיע כאן. אי אפשר להשתמש במאפיין <MapName> עם המאפיין mapIdentifier.

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <MapName ref="flow.variable"/>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

הצבת KVM עם משתנה

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

בדוגמה הזו של מדיניות נוצרת מכונת KVM. המדיניות משתמשת בפקודה PUT כדי להציב מפתח עם שני ערכים משויכים ב-KVM בשם urlMapper.

<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>

המפתח בדוגמה הזו, urlencoding.requesturl.hashed, הוא דוגמה למשתנה מותאם אישית. כתובת ה-URL של הבקשה עם הגיבוב תיווצר על ידי קוד (לדוגמה, JavaScript או Java) ואז תישמר במשתנה הזה, שבו מדיניות KeyValueMapOperations יכולה לגשת אליו.

לכל מפתח, requesturl.hashed, נשמרים שני ערכים:

התוכן של המשתנה המותאם אישית שנקרא urlencoding.longurl.encoded
התוכן של המשתנה המוגדר מראש request.queryparam.url

לדוגמה, כשמדיניות מופעלת בזמן ריצה, הערכים של המשתנים יכולים להיות:

urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
request.queryparam.url: http://apigee.com

ה-KVM והערך הבאים ייווצרו במאגר המפתחות/ערכים של Apigee ויחולו על proxy ל-API שאליו מצורפת המדיניות:

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

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

קבלת KVM ממשתנה

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

כדי לאחזר את הערך של רשומה ב-KVM, כמו זו שמוסברת בכרטיסייה KeyValueMapOperations PUT, צריך להגדיר מדיניות ל-GET ה-KVM:

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

כשהמדיניות הזו מופעלת, אם הערך של המשתנה urlencoding.requesturl.hashed הוא ed24e12820f2f900ae383b7cc4f2b31c402db1be, המשתנה המותאם אישית שנקרא urlencoding.shorturl יוגדר עם הערך http://tinyurl.com/38lwmlr.

אחרי שהנתונים מאוחזרים, מדיניות וקוד אחרים יכולים לגשת אליהם על ידי חילוץ הערך מהמשתנים האלה.

קבלת ערך מ-KVM

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

בדוגמה הזו, המשתנה private.encryptedVar מכיל את הערך המפוענח של המפתח foo ב-KVM.

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

אחרי שהנתונים אוחזרו, מדיניות וקוד אחרים יכולים לגשת אליהם על ידי חילוץ הערך מהמשתנה הזה.

<KeyValueMapOperations>

מספק גישה מבוססת-מדיניות למיפוי של זוגות מפתח/ערך (KVM).

תחביר

<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>KEY_NAME_LITERAL</Parameter>
      </Key>
      <Value>VALUE_LITERAL</Value>
      <Value>VALUE_LITERAL</Value>
    </Entry>
  </InitialEntries>
  <Put override="BOOLEAN">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </Key>
  </Put>
  <Get assignTo="VARIABLE_NAME" index="INDEX_NUMBER">
    <Key>
       <Parameter>KEY_NAME_LITERAL</Parameter>
    </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>:

הערה: המאפיין mapIdentifier מציין את השם של KVM שאיתו רוצים ליצור אינטראקציה. אפשר גם לציין KVM באופן דינמי באמצעות הרכיב <MapName>.

מאפיין תיאור ברירת מחדל נוכחות

מאפיין	תיאור	ברירת מחדל	נוכחות
`mapIdentifier`	מציינים מזהה שמציין למדיניות לאיזה KVM היא צריכה לגשת. אם גם המזהה הזה וגם `<MapName>` חסרים, נעשה שימוש ב-KVM בשם `kvmap`. אסור להשתמש במאפיין הזה אם מציינים את הרכיב `<MapName>`.	לא רלוונטי	אופציונלי

mapIdentifier

מציינים מזהה שמציין למדיניות לאיזה KVM היא צריכה לגשת.

אם גם המזהה הזה וגם <MapName> חסרים, נעשה שימוש ב-KVM בשם kvmap. אסור להשתמש במאפיין הזה אם מציינים את הרכיב <MapName>.

לא רלוונטי

אופציונלי

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

מאפיין	תיאור	ברירת מחדל	נוכחות
`name`	השם הפנימי של המדיניות. הערך של מאפיין `name` יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב `<DisplayName>` כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.	לא רלוונטי	חובה
`continueOnError`	מגדירים את הערך `false` כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות. הגדרה ל-`true` מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מידע נוסף: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי	FALSE	אופציונלי
`enabled`	מגדירים את המדיניות למצב `true` כדי לאכוף אותה. מגדירים את הערך `false` כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.	TRUE	אופציונלי
`async`	המאפיין הזה הוצא משימוש.	FALSE	הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

ברירת מחדל

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

לא רלוונטי

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

נוכחות אופציונלי

סוג String

רכיבי צאצא

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

אלמנט <Delete>

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

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

<Delete>
   <Key>
      <Parameter>KEY_NAME_LITERAL</Parameter>
   </Key>
</Delete>

ברירת מחדל	לא רלוונטי
נוכחות	חובה אם לא צוינו הערכים `<Get>` או `<Put>`.
סוג	לא רלוונטי

אלמנט <Entry>

ערכי Seed ל-KVM, שמאוכלסים ב-KVM כשהוא מאותחל. ב-Apigee, גודל המפתח מוגבל ל-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>

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

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

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

ברירת מחדל	‫`300` (5 דקות)
נוכחות	אופציונלי
סוג	מספר שלם

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

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

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

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

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

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

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

הערות

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

אלמנט <Get>

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

‫Apigee מצפין את כל הנתונים שמאוחסנים ב-KVM. פרטים נוספים מופיעים במאמר בנושא מפתחות הצפנה. כשמשתמשים ב-<Get>, ‏ Apigee מפענח את הנתונים המאוחסנים ומקצה אותם למשתנה בהקשר של ההודעה. שם המשתנה מצוין באמצעות המאפיין assignTo.

חשוב לציין את השם של KVM באמצעות המאפיין mapIdentifier ברכיב הבסיס או באמצעות האלמנט <MapName>.

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

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

ברירת מחדל	לא רלוונטי
נוכחות	חובה אם לא צוינו הערכים `<Put>` או `<Delete>`.
סוג	לא רלוונטי

מאפיינים

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

מאפיין תיאור ברירת מחדל נוכחות

מאפיין	תיאור	ברירת מחדל	נוכחות
`assignTo`	המשתנה שאליו יש להקצות את הערך שאוחזר.	לא רלוונטי	חובה
`index`	מספר האינדקס (באינדקס שמתחיל מ-1) של הפריט לאחזור ממפתח עם כמה ערכים. לדוגמה, אם מציינים `index=1`, הערך הראשון יוחזר ויוקצה למשתנה `assignTo`. אם לא מציינים ערך אינדקס, כל הערכים של הערך הזה מוקצים למשתנה כ`java.util.List`. דוגמה מופיעה בכרטיסייה Get Value from KVM בSamples.	לא רלוונטי	אופציונלי

assignTo

המשתנה שאליו יש להקצות את הערך שאוחזר.

לא רלוונטי

חובה

index

מספר האינדקס (באינדקס שמתחיל מ-1) של הפריט לאחזור ממפתח עם כמה ערכים. לדוגמה, אם מציינים index=1, הערך הראשון יוחזר ויוקצה למשתנה assignTo. אם לא מציינים ערך אינדקס, כל הערכים של הערך הזה מוקצים למשתנה כjava.util.List.

דוגמה מופיעה בכרטיסייה Get Value from KVM בSamples.

לא רלוונטי

אופציונלי

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

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

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

החרגת נתונים שאוחזרו מסשנים של ניפוי באגים

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

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

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

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

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

מפתח	ערך
top_movies	Princess Bride,The Godfather,Citizen Kane
האזרח קיין	אורסון וולס
Princess Bride	רוב ריינר
הסנדק	פרנסיס פורד קופולה

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

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

<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, ‏ Apigee יוצר את המשתנים הבאים עם ערכים תואמים, שאפשר להשתמש בהם בהמשך בתהליך של proxy ל-API:

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

הערך של top.movie.pick הוא רק הפריט הראשון ברשימה המופרדת בפסיקים, כי רכיב <Get> הראשון משתמש במאפיין index עם הערך 1. לאחר מכן, הרכיב השני <Get> משתמש בערך שהוקצה ל-top.movie.pick כמפתח לאחזור ערך לתוך movie.director.

אלמנט <InitialEntries>

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

הערה: אסור להשתמש ב-<InitialEntries> אם משתמשים ברכיב <MapName>.

לדוגמה:

<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>

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

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

גודל המפתח מוגבל ל-2KB.

ברירת מחדל	לא רלוונטי
נוכחות	אופציונלי
סוג	לא רלוונטי

אלמנט <Key>

מציין את המפתח ברשומה של KVM. הרכיב הזה מופיע כצאצא של <Get>,‏ <Put> או <Delete>, או כצאצא של הרכיב <Entry> שהוא צאצא של <InitialEntries>. דוגמה למפתח קבוע:

<Key>
  <Parameter>KEY_NAME_LITERAL</Parameter>
</Key>

מפתח יכול להיות מורכב, עם רכיבים דינמיים, כלומר אפשר לצרף יותר מ-<Parameter> אחד כדי ליצור את המפתח. לדוגמה, אפשר לשלב את התוכן של המשתנים userID ו-role כדי ליצור מפתח דינמי. הנה דוגמה להגדרת שלב שמציין מפתח מורכב שנקבע באופן דינמי:

<Key>
  <Parameter ref='userID'/>
  <Parameter ref='role'/>
</Key>

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

גודל המפתח מוגבל ל-2KB.

הערה: השם ratelimit שמור. מידע נוסף זמין בפוסט הזה בקהילת Apigee.

ברירת מחדל	לא רלוונטי
נוכחות	אופציונלי
סוג	לא רלוונטי

אלמנט <MapName>

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

דוגמאות:

<!-- use one of the following forms -->

<MapName>literal_string</MapName>

<MapName ref="flow.variable"></MapName>

<MapName ref="flow.variable">literal_string</MapName>

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

אם משתמשים במאפיין <MapName> במדיניות, לא מציינים את המאפיין mapIdentifier. מידע נוסף זמין במאמר בנושא מאפייני מדיניות.

אם המפה לא קיימת כשפורסים את ה-proxy, המפה לא תיצור ושגיאת זמן ריצה תופיע ב-Apigee כשמבצעים את המדיניות. אם מספקים את משתנה הזרימה, אסור להשתמש ברכיב <InitialEntries>. תקבלו שגיאת אימות במהלך הפריסה.

רכיב `<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.

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

ברירת מחדל	לא רלוונטי
נוכחות	חובה
סוג	String

מאפיינים

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

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

אלמנט <Put>

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

כדי ליצור KVM באמצעות ממשק המשתמש או ה-API, אפשר לעיין במאמרים הבאים:

שימוש ב-KVM באמצעות ממשק המשתמש של Apigee כדי ליצור KVM מוצפנים בהיקף סביבה בממשק המשתמש
Organization-scoped key value maps API
ממשק API של מפות מפתח-ערך בהיקף סביבה
API של מפות מפתח-ערך בהיקף של proxy ל-API

גודל המפתח מוגבל ל-2KB.

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

ברירת מחדל	לא רלוונטי
נוכחות	חובה אם לא צוינו הערכים `<Get>` או `<Delete>`.
סוג	לא רלוונטי

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

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

מאפיינים

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

מאפיין תיאור ברירת מחדל נוכחות

לקבוע ידנית

מאפיין	תיאור	ברירת מחדל	נוכחות
לקבוע ידנית	אם הערך הוא `true`, הוא משנה את הערך של מקש. ‫`<Put override="false">` יכתוב אם ורק אם אין כרגע רשומה שנשמרה בחנות KVM עבור המפתח הזה.	`true`	אופציונלי

אם הערך הוא true, הוא משנה את הערך של מקש.

‫<Put override="false"> יכתוב אם ורק אם אין כרגע רשומה שנשמרה בחנות KVM עבור המפתח הזה.

true

אופציונלי

אלמנט <Scope>

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

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

<Scope>environment</Scope>

ברירת מחדל	`environment`
נוכחות	אופציונלי
סוג	String
ערכים אפשריים	`organization` `environment` `apiproxy` `policy` (גרסה של proxy ל-API)

אלמנט <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>

ברירת מחדל	לא רלוונטי
נוכחות	חובה
סוג	String

מאפיינים

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

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

הפניה לשגיאה

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

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

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

קוד תקלה	סטטוס HTTP	מטרה	תיקון
`steps.keyvaluemapoperations.UnsupportedOperationException`	`500`	השגיאה הזו מתרחשת אם המאפיין `mapIdentifier` מוגדר כמחרוזת ריקה במדיניות `KeyValueMapOperations`.

שגיאות פריסה

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

שם השגיאה	מטרה	תיקון
`InvalidIndex`	אם הערך של המאפיין `index` שצוין ברכיב `<Get>` של מדיניות `KeyValueMapOperations` הוא אפס או מספר שלילי, פריסת ה-proxy ל-API תיכשל. האינדקס מתחיל מ-`1`, ולכן אינדקס של אפס או מספר שלם שלילי נחשב לא תקין.
`KeyIsMissing`	השגיאה הזו מתרחשת אם רכיב `<Key>` חסר לחלוטין או אם רכיב `<Parameter>` חסר בתוך רכיב `<Key>` מתחת לרכיב `<Entry>` של מדיניות `<InitialEntries>` של `KeyValueMapOperations`.
`ValueIsMissing`	השגיאה הזו מתרחשת אם הרכיב `<Value>` חסר מתחת לרכיב `<Entry>` של הרכיב `<InitialEntries>` במדיניות `KeyValueMapOperations`.

סכימות

הערות שימוש

סקירה כללית על KVM זמינה במאמר שימוש במיפוי של זוגות מפתח/ערך.

באמצעות ממשק המשתמש של Apigee, אפשר להגדיר KVMs רק בהיקף הסביבה, כמו שמתואר במאמר שימוש ב-KVMs בממשק המשתמש של Apigee. באמצעות Apigee API, אפשר להגדיר KVM בהיקף של הארגון, הסביבה או ה-proxy ל-API, כמו שמתואר בקטעים הבאים:

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

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

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

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

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

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

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

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

אלמנט <Parameter> ראוי לציון מיוחד, כי הוא קובע את שם המפתח שנוצר, וגם את שם המפתח שרוצים לאחזר או למחוק. בהמשך מפורטות שתי דוגמאות. הראשון מציין שם מפתח באופן מילולי, והשני מציין שם מפתח באמצעות משתנה. נניח שהפרטים הבאים משמשים ליצירת מפתחות ב-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 הוא my_key, אפשר לציין את הערך המילולי עם <Parameter>my_key</Parameter> או לציין משתנה שמכיל את הערך המדויק mny_key, כך: <Parameter ref="variable.containing.foo"/>.

הערה: השם ratelimit שמור. מידע נוסף זמין במאמר Quota Policy - Throws NullPointerException.

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

מידע נוסף על KVMs זמין בנושאים הבאים:

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

דוגמאות

הצבת KVM עם ליטרל

קבלת KVM מליטרל

גישה דינמית ל-KVM

הצבת KVM עם משתנה

קבלת KVM ממשתנה

קבלת ערך מ-KVM

<KeyValueMapOperations>

תחביר

מאפייני <KeyValueMapOperations>

אלמנט <DisplayName>

רכיבי צאצא

אלמנט <Delete>

אלמנט <Entry>

אלמנט <ExclusiveCache>

אלמנט <ExpiryTimeInSecs>

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

אלמנט <Get>

מאפיינים

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

החרגת נתונים שאוחזרו מסשנים של ניפוי באגים

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

אלמנט <InitialEntries>

אלמנט <Key>

אלמנט <MapName>

רכיב <Parameter>

מאפיינים

אלמנט <Put>

מאפיינים

אלמנט <Scope>

אלמנט <Value>

מאפיינים

הפניה לשגיאה

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

שגיאות פריסה

סכימות

הערות שימוש

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

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

מדיניות KeyValueMapOperations

רכיב `<Parameter>`