นโยบาย KeyValueMapOperations

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X
ข้อมูล

ไอคอนการดำเนินการแมปค่าคีย์จาก Edge UI

อะไร

ให้สิทธิ์เข้าถึงพื้นที่เก็บข้อมูล Key Value Map (KVM) ที่มีให้ใช้งานใน Apigee Edge ตามนโยบาย คุณจัดเก็บ เรียกดู และลบคู่คีย์/ค่าจากแผนที่ที่มีอยู่ที่มีชื่อได้โดยการกำหนดค่านโยบาย KeyValueMapOperatings ที่ระบุการดำเนินการ PUT, GET หรือ DELETE (การดำเนินการเหล่านี้อย่างน้อย 1 รายการต้องดำเนินการโดยนโยบาย)

วิดีโอ

ดูข้อมูลเพิ่มเติมเกี่ยวกับ KVM ได้ในวิดีโอต่อไปนี้

วิดีโอ คำอธิบาย
เหตุใดจึงต้องใช้คีย์-ค่าแมป ดูเหตุผลที่ต้องมี KVM และวิธีการทำงาน
สร้าง KVM โดยใช้ UI และเรียกข้อมูล KVM ที่รันไทม์ สร้าง KVM, ดึงค่าโดยใช้นโยบาย KVM และแทรกค่าลงในคำขอ API โดยใช้ตัวแปรโฟลว์
สร้างและอัปเดต KVM ที่รันไทม์ API สร้าง KVM ที่รันไทม์ API โดยใช้นโยบาย KVM
แคช KVM เพื่อเพิ่มประสิทธิภาพ ปรับปรุงประสิทธิภาพของนโยบาย KVM โดยการแคชข้อมูล
จัดเก็บ KVM ที่เข้ารหัส จัดเก็บข้อมูลที่ละเอียดอ่อนใน KVM ในรูปแบบที่เข้ารหัสและดึงค่าขณะรันไทม์โดยใช้นโยบาย KVM และตัวแปรส่วนตัว
จัดการการเข้าถึงโดยใช้ขอบเขต KVM จำกัด KVM ให้กับองค์กร, สภาพแวดล้อม, พร็อกซี API หรือการแก้ไขพร็อกซี API โดยใช้แอตทริบิวต์ขอบเขตนโยบาย KVM
ลบรายการ KVM ที่รันไทม์ API ลบรายการ KVM ที่รันไทม์ API โดยใช้การดำเนินการ DELETE ของนโยบาย KVM

ลองฟัง

PUT KVM ที่มีลิเทอรัล

เมื่อนโยบายต่อไปนี้ทำงาน ระบบจะสร้าง KVM ที่เข้ารหัสชื่อ FooKVM จากนั้นสร้างคีย์ชื่อ FooKey_1 โดยมีการตั้งค่า 2 ค่าด้วยสตริงลิเทอรัล 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>

โปรดสังเกตว่าขอบเขตคือ "สภาพแวดล้อม" ซึ่งหมายความว่าคุณจะเห็น KVM ใน UI การจัดการในส่วน API > การกำหนดค่าสภาพแวดล้อม > แมปค่าคีย์ KVM ที่แสดงในหน้าดังกล่าวทั้งหมดจะกำหนดขอบเขตตามสภาพแวดล้อมที่เลือก

รับ KVM จากลิเทอรัล

นโยบายนี้จะดูแมป FooKVM จากตัวอย่างก่อนหน้า รับค่าที่ 2 (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>

PUT KVM ที่มีตัวแปร

ตัวอย่างง่ายๆ ของแมปค่าคีย์ที่เป็นประโยชน์คือบริการย่อ URL คุณกำหนดค่าแมปค่าคีย์ให้จัดเก็บ URL แบบย่อพร้อมกับ URL แบบเต็มที่เกี่ยวข้องได้

ตัวอย่างนโยบายนี้จะสร้างแมปค่าคีย์ นโยบายนี้จะใส่คีย์ที่มีค่าที่เชื่อมโยงกัน 2 ค่าลงในแมปคีย์/ค่าที่ชื่อว่า "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) จากนั้นจะจัดเก็บไว้ในตัวแปรนี้ ซึ่งนโยบาย KeyValueMapEnforcement สามารถเข้าถึงได้

สำหรับแต่ละคีย์ ระบบจะจัดเก็บ requesturl.hashed ไว้ 2 ค่า ดังนี้

  • เนื้อหาของตัวแปรที่กําหนดเองชื่อ urlencoding.longurl.encoded
  • เนื้อหาของตัวแปรที่กําหนดไว้ล่วงหน้า request.queryparam.url

เช่น เมื่อนโยบายทำงานขณะรันไทม์ ค่าของตัวแปรอาจเป็นดังนี้

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

ระบบจะสร้างการแมปและรายการคีย์/ค่าต่อไปนี้ในที่เก็บคีย์/ค่าของ Edge และกำหนดขอบเขตเป็นพร็อกซี API ที่มีการแนบนโยบายไปด้วย

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

รายการจะยังคงอยู่จนกว่าจะลบออก รายการคีย์/ค่าใน Store จะกระจายไปยังอินสแตนซ์ของ Edge ที่เรียกใช้ระบบคลาวด์

รับ KVM จากตัวแปร

ตัวอย่างง่ายๆ ของแมปค่าคีย์ที่มีประโยชน์คือบริการ "ย่อ" URL คุณกำหนดค่าแมปค่าคีย์ให้จัดเก็บ URL แบบย่อพร้อมกับ URL แบบเต็มที่เกี่ยวข้องได้

หากต้องการดึงค่าของรายการแมปคีย์/ค่า เช่น ค่าที่อยู่ในแท็บ KeyValueMapOperatings PUT ให้กำหนดค่านโยบายเพื่อรับแมปค่าคีย์ ดังนี้

<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

หากแมปค่าคีย์มีการเข้ารหัส ให้ดึงค่าโดยใช้คำนำหน้า "private." ในค่าแอตทริบิวต์ assignTo ในตัวอย่างนี้ ตัวแปร private.encryptedVar เก็บค่าที่ถอดรหัสของคีย์ foo ของการแมปคีย์ค่า ดูรายละเอียดการสร้างแมปค่าคีย์ที่เข้ารหัสที่หัวข้อ "สร้าง" ของ API การจัดการ Maps คีย์/ค่า

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

เมื่อเรียกข้อมูลแล้ว นโยบายและโค้ดอื่นๆ จะเข้าถึงข้อมูลดังกล่าวได้โดยการดึงค่าจากตัวแปรนั้น


การอ้างอิงองค์ประกอบ

การอ้างอิงองค์ประกอบจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย KeyValueMapOperatings ดังต่อไปนี้

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

แอตทริบิวต์ <KeyValueMapOperatings>

ตัวอย่างต่อไปนี้แสดงแอตทริบิวต์ในแท็ก <KeyValueMapOperations>

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

ตารางต่อไปนี้อธิบายแอตทริบิวต์เฉพาะสำหรับแท็ก <KeyValueMapOperations>

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
mapIdentifier

ระบุตัวระบุที่จะใช้เมื่อเข้าถึงแผนที่ที่สร้างโดยนโยบายนี้หรือใน UI การจัดการ

ชื่อ KVM พิจารณาตัวพิมพ์เล็กและตัวพิมพ์ใหญ่กับ Apigee Edge สำหรับระบบคลาวด์สาธารณะ เช่น foobar นั้นแตกต่างจาก FooBar

หากยกเว้นแอตทริบิวต์นี้ ระบบจะใช้ KVM ชื่อ kvmap

ภายในขอบเขตขององค์กร/สภาพแวดล้อม/apiproxy คุณสามารถใช้แอตทริบิวต์ mapIdentifier เพื่อระบุชื่อแมปของคุณเอง

ไม่มีข้อมูล ไม่บังคับ

ตารางต่อไปนี้อธิบายแอตทริบิวต์ที่ใช้ร่วมกันในองค์ประกอบระดับบนสุดของนโยบายทั้งหมด

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
name

ชื่อภายในของนโยบาย ค่าของแอตทริบิวต์ name มีตัวอักษร ตัวเลข ช่องว่าง ขีดกลาง ขีดล่าง และจุด ค่านี้ต้องมีอักขระไม่เกิน 255 ตัว

(ไม่บังคับ) ใช้องค์ประกอบ <DisplayName> เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติที่แตกต่างออกไป

ไม่มีข้อมูล จำเป็น
continueOnError

ตั้งค่าเป็น false เพื่อแสดงผลข้อผิดพลาดเมื่อนโยบายล้มเหลว ซึ่งถือเป็นเรื่องปกติสำหรับนโยบายส่วนใหญ่

ตั้งค่าเป็น true เพื่อให้การดำเนินการโฟลว์ดำเนินต่อไปได้แม้ว่านโยบายจะล้มเหลวก็ตาม

false ไม่บังคับ
enabled

ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย

ตั้งค่าเป็น false เพื่อปิดนโยบาย ระบบจะไม่บังคับใช้นโยบายแม้ว่าจะยังแนบอยู่กับขั้นตอนก็ตาม

จริง ไม่บังคับ
async

แอตทริบิวต์นี้เลิกใช้งานแล้ว

false เลิกใช้

องค์ประกอบ <DisplayName>

ใช้เพิ่มเติมจากแอตทริบิวต์ name เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI การจัดการด้วยชื่อที่เป็นภาษาธรรมชาติที่แตกต่างออกไป

<DisplayName>Policy Display Name</DisplayName>
ค่าเริ่มต้น

ไม่มีข้อมูล

หากคุณไม่ใส่องค์ประกอบนี้ ระบบจะใช้ค่าของแอตทริบิวต์ name ของนโยบาย

การมีบุคคลอยู่ ไม่บังคับ
Type สตริง

องค์ประกอบ <Delete>

ลบคู่คีย์/ค่าที่ระบุ ต้องใช้ <Get>, <Put> หรือ <Delete> อย่างน้อย 1 รายการ

อย่าลืมระบุชื่อของ KVM ที่มีแอตทริบิวต์ mapIdentifier ในองค์ประกอบระดับบนสุด เช่น

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>
ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ต้องระบุหากไม่มี <Get> หรือ <Put>
Type ไม่มีข้อมูล

องค์ประกอบ <Entry>

ค่า Seed สำหรับแมปค่าคีย์ ซึ่งป้อนข้อมูลในแมปค่าคีย์เมื่อเริ่มต้น

สำหรับ Edge for Public Cloud คีย์จะมีขนาดไม่เกิน 2 KB เช่น

<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>
ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ไม่บังคับ
Type ไม่มีข้อมูล

องค์ประกอบ <ExclusiveCache>

เลิกใช้งานแล้ว โปรดใช้องค์ประกอบ <Scope> แทน

องค์ประกอบ <ExpiryTimeInSecs>

ระบุระยะเวลาเป็นวินาทีหลังจากที่ Edge รีเฟรชค่าที่แคชไว้จาก KVM ที่ระบุ

ค่า 0 หรือ -1 หรือยกเว้นองค์ประกอบนี้หมายความว่าระบบจะใช้ค่าเริ่มต้น 300 วินาที เช่น

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
ค่าเริ่มต้น 300 (5 นาที)
การมีบุคคลอยู่ ไม่บังคับ
Type จำนวนเต็ม

KVM เป็นกลไกแบบถาวรระยะยาวที่จัดเก็บคีย์และค่าในฐานข้อมูล NoSQL ด้วยเหตุนี้ การอ่านจาก KVM ขณะรันไทม์อาจทำให้พร็อกซีทำงานช้าลง 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 จะเรียกค่า "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> อย่างน้อย 1 รายการ

อย่าลืมระบุชื่อของ KVM ที่มีแอตทริบิวต์ mapIdentifier ในองค์ประกอบระดับบนสุด

คุณรวมการบล็อก Get หลายรายการในนโยบายเพื่อเรียกข้อมูลหลายรายการจาก KVM ได้

ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ต้องระบุหากไม่มี <Put> หรือ <Delete>
Type ไม่มีข้อมูล

รับรายการเดียวจาก KVM

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

รับหลายรายการจาก KVM

ในตัวอย่างต่อไปนี้ สมมติว่าเป็น KVM ที่มีคีย์และค่าต่อไปนี้ นอกจากการจัดเก็บรายชื่อภาพยนตร์ที่ได้รับความนิยมสูงสุดตลอดกาลแล้ว KVM ยังเก็บข้อมูลชื่อผู้กำกับสำหรับภาพยนตร์ฟอร์มยักษ์ทุกเรื่องด้วย

คีย์ ค่า
top_movies เจ้าหญิงเจ้าสาว,เจ้าพ่อเพลง,Citizen Kane
พลเมือง เคน ออร์สัน เวลส์
เจ้าสาว ร็อบ ไรเนอร์
เจ้าพ่อ ฟรานซิส ฟอร์ด คอปโปลา

ต่อไปนี้คือการกำหนดค่านโยบาย 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>

เมื่อมีการเรียกพร็อกซี API แล้ว Edge จะสร้างตัวแปรต่อไปนี้ที่คุณสามารถใช้ในขั้นตอนพร็อกซี API ได้

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

Attributes

ตารางต่อไปนี้อธิบายแอตทริบิวต์ขององค์ประกอบ <Get>

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
assignTo

ตัวแปรที่ควรกําหนดค่าที่ดึงมา

หากแมปค่าคีย์มีการเข้ารหัส ให้ขึ้นต้นชื่อ assignTo ด้วย "private." เช่น

<Get assignTo="private.myvar">

นโยบายจะแสดงข้อผิดพลาดหากคุณพยายามเรียกข้อมูลแมปค่าคีย์ที่เข้ารหัสโดยไม่ใช้คำนำหน้า คำนำหน้าซึ่งจำเป็นสำหรับวัตถุประสงค์ด้านความปลอดภัยพื้นฐานระหว่างการแก้ไขข้อบกพร่องจะซ่อนค่าที่เข้ารหัสจากการติดตามพร็อกซี API และเซสชันการแก้ไขข้อบกพร่อง

สำหรับข้อมูลเกี่ยวกับการสร้างแมปค่าคีย์ที่เข้ารหัส โปรดดูหัวข้อ "สร้าง" ของ API การจัดการ Maps คีย์/ค่าและการสร้างและแก้ไขแมปค่าคีย์ของสภาพแวดล้อม

ไม่มีข้อมูล จำเป็น
index

หมายเลขดัชนี (ในดัชนีแบบ 1) ของรายการที่จะดึงข้อมูลจากคีย์ที่มีหลายค่า เช่น การระบุ index=1 จะคืนค่าแรกและกําหนดให้กับตัวแปร assignTo หากไม่ได้ระบุค่าดัชนี ระบบจะกำหนดค่าทั้งหมดของรายการนั้นให้กับตัวแปรเป็น java.util.List

โปรดดูตัวอย่างในแท็บ "รับค่าที่เข้ารหัสจาก KVM" ในตัวอย่าง

ไม่มีข้อมูล ไม่บังคับ

องค์ประกอบ <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>

เมื่อใช้องค์ประกอบนี้ เมื่อคุณบันทึกนโยบายใน UI การจัดการในพร็อกซีเวอร์ชันที่ทำให้ใช้งานได้แล้ว หรือติดตั้งใช้งานกลุ่มพร็อกซี API ที่มีนโยบายร่วมกับองค์ประกอบนี้ ระบบจะสร้างคีย์โดยอัตโนมัติใน KVM (เป็นไม่ได้เข้ารหัส) หากค่าในนโยบายแตกต่างจากค่าใน KVM ระบบจะเขียนทับค่าใน KVM เมื่อมีการทำให้พร็อกซีใช้งานได้ ระบบจะเพิ่มคีย์/ค่าใหม่ลงใน KVM ที่มีอยู่ควบคู่ไปกับคีย์/ค่าที่มีอยู่

คีย์และค่าที่องค์ประกอบนี้ป้อนข้อมูลต้องเป็นลิเทอรัล ตัวอย่างเช่น องค์ประกอบนี้ไม่รองรับ <Parameter ref="request.queryparam.key">

เราจำกัดขนาดคีย์ไว้ที่ 2 KB สำหรับทั้ง Edge สำหรับ Public Cloud และ Edge สำหรับ Privateเชิญ ค่า KVM จำกัดไว้ที่ 2 KB

หากต้องการสร้าง KVM ที่เข้ารหัส ให้ใช้ Maps Management API ของคีย์/ค่า

ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ไม่บังคับ
Type ไม่มีข้อมูล

องค์ประกอบ <Key>

ระบุคีย์ในรายการแมปคีย์/ค่า คีย์อาจเป็นแบบผสมได้ ซึ่งหมายความว่าจะมีพารามิเตอร์ต่อท้ายได้มากกว่า 1 รายการเพื่อสร้างคีย์ เช่น userID และ role อาจรวมกันเพื่อสร้าง key เช่น

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

อย่าลืมดูองค์ประกอบ <Parameter> สำหรับข้อมูลเฉพาะเกี่ยวกับวิธีตั้งชื่อคีย์

Edge for Public Cloud จะจำกัดขนาดของคีย์ไว้ที่ 2 KB โปรดดูข้อมูลเพิ่มเติมในความแตกต่างระหว่าง Edge สำหรับ Public Cloud API และ Private Cloud API

ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ไม่บังคับ
Type ไม่มีข้อมูล

องค์ประกอบ <Parameters>

ระบุคีย์ในคู่คีย์/ค่า องค์ประกอบนี้จะระบุชื่อเมื่อสร้าง วาง ดึงข้อมูล หรือลบคู่คีย์/ค่า

คุณสามารถระบุชื่อโดยใช้:

  • สตริงตามตัวอักษร

    <Key>
      <Parameter>literal</Parameter>
    </Key>
    
  • ตัวแปรที่จะดึงข้อมูลขณะรันไทม์โดยใช้แอตทริบิวต์ ref

    <Key>
      <Parameter ref="variable_name"/>
    </Key>
    
  • การรวมกันของลิเทอรัลและการอ้างอิงตัวแปร

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

เมื่อองค์ประกอบคีย์มีองค์ประกอบพารามิเตอร์หลายรายการ สตริงคีย์ที่มีประสิทธิภาพคือการเชื่อมค่าของแต่ละพารามิเตอร์เข้าด้วยกันด้วยขีดล่าง 2 ขีด เช่น ในตัวอย่างด้านบน หากตัวแปร apiproxy.name มีค่า "abc1" คีย์ที่มีผลจะเป็น targeturl__abc1__weight

ไม่ว่าคุณจะกำลังรับ อัปเดต หรือลบรายการคีย์/ค่า ชื่อคีย์ต้องตรงกับชื่อของคีย์ในแมปค่าคีย์ ดูหลักเกณฑ์ในการระบุและการเรียกชื่อคีย์

ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ จำเป็น
Type สตริง

Attributes

ตารางต่อไปนี้อธิบายแอตทริบิวต์ขององค์ประกอบ <Parameter>

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
อ้างอิง ระบุชื่อของตัวแปรที่มีค่าซึ่งมีชื่อของคีย์ที่คุณต้องการสร้าง รับ หรือลบ ไม่มีข้อมูล ต้องระบุหากไม่ได้ระบุค่าลิเทอรัลระหว่างแท็กเปิดกับแท็กปิด ไม่อนุญาตหากมีการระบุค่าลิเทอรัล

<Put> องค์ประกอบ

เขียนคู่คีย์/ค่าลงในแมปค่าคีย์ ไม่ว่าแมปค่าคีย์มีการเข้ารหัสหรือไม่เข้ารหัส หากไม่มีแมปค่าคีย์ที่ระบุในแอตทริบิวต์ mapIdentifier ในองค์ประกอบระดับบนสุด ระบบจะสร้างแผนที่โดยอัตโนมัติ (เป็นไม่ได้เข้ารหัส) หากมีการแมปคีย์-ค่าอยู่แล้ว ระบบจะเพิ่มคีย์/ค่าลงในการจับคู่นั้น

ในการสร้างแมปค่าคีย์ที่เข้ารหัส ให้ใช้ Maps Management API คีย์/ค่า หรือดูการสร้างและแก้ไขแมปค่าคีย์ของสภาพแวดล้อมเพื่อสร้าง KVM ที่กำหนดขอบเขตสภาพแวดล้อมที่เข้ารหัสใน UI

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ ต้องระบุหากไม่มี <Get> หรือ <Delete>
Type ไม่มีข้อมูล

Attributes

ตารางต่อไปนี้อธิบายแอตทริบิวต์ขององค์ประกอบ <Put>

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
ลบล้าง

หากตั้งค่าเป็น true ระบบจะลบล้างค่าของคีย์

false ไม่บังคับ

องค์ประกอบ <Scope>

กำหนดขอบเขตของความสามารถเข้าถึงได้ง่ายสำหรับแมปค่าคีย์ ขอบเขตเริ่มต้นคือ environment ซึ่งหมายความว่าโดยค่าเริ่มต้น รายการแผนที่จะแชร์โดยพร็อกซี API ทั้งหมดที่ทำงานในสภาพแวดล้อม (เช่น การทดสอบหรือการใช้งาน) หากคุณกำหนดขอบเขตเป็น apiproxy ข้อมูลในแมปค่าคีย์จะเข้าถึงได้โดยพร็อกซี API ที่เขียนค่าลงในแมปเท่านั้น

โปรดทราบว่าเมื่อเข้าถึงแผนที่หรือรายการแผนที่ คุณต้องระบุค่าขอบเขตเดียวกันกับที่คุณใช้เมื่อสร้างแผนที่ ตัวอย่างเช่น หากแผนที่สร้างขึ้นโดยมีขอบเขตเป็น apiproxy คุณต้องใช้ขอบเขต apiproxy เมื่อเรียกข้อมูลค่า วางการเปลี่ยนแปลง หรือลบรายการ

<Scope>environment</Scope>
ค่าเริ่มต้น environment
การมีบุคคลอยู่ ไม่บังคับ
Type สตริง
ค่าที่ถูกต้อง:
  • organization
  • environment
  • apiproxy
  • policy (การแก้ไขพร็อกซี 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> หลายรายการเพื่อระบุค่าที่มีหลายส่วนก็ได้ ระบบจะรวมค่าเข้าด้วยกันขณะรันไทม์

ในตัวอย่างต่อไปนี้ จะมีการเพิ่มคีย์ 2 คีย์ใน 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>

ในตัวอย่างต่อไปนี้ คีย์หนึ่งจะสร้างขึ้นโดยมี 2 ค่า สมมติว่าชื่อองค์กรคือ foo_org ชื่อพร็อกซี API คือ bar และสภาพแวดล้อมคือ test:

  • คีย์ foo_org ที่มีค่า bar,test
<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>
ค่าเริ่มต้น ไม่มีข้อมูล
การมีบุคคลอยู่ จำเป็น
Type สตริง

Attributes

ตารางต่อไปนี้อธิบายแอตทริบิวต์ขององค์ประกอบ <Value>

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การมีบุคคลอยู่
อ้างอิง ระบุชื่อของตัวแปรที่มีค่าซึ่งมีค่าคีย์ที่คุณต้องการตั้งค่า ไม่มีข้อมูล ต้องระบุหากไม่ได้ระบุค่าลิเทอรัลระหว่างแท็กเปิดกับแท็กปิด ไม่อนุญาตหากมีการระบุค่าลิเทอรัล

การอ้างอิงข้อผิดพลาด

ข้อผิดพลาดที่แสดงผลจากนโยบาย Edge มีรูปแบบที่สอดคล้องกันตามที่อธิบายไว้ในข้อมูลอ้างอิงรหัสข้อผิดพลาด

ส่วนนี้จะอธิบายโค้ดข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงผลและตัวแปรข้อผิดพลาดที่ Edge กําหนดเมื่อนโยบายนี้ทําให้เกิดข้อผิดพลาด ข้อมูลนี้เป็นสิ่งสำคัญที่ต้องทราบหากคุณกำลังกำหนดกฎข้อผิดพลาดเพื่อจัดการกับข้อผิดพลาด ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด

ข้อผิดพลาดเกี่ยวกับรันไทม์

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อนโยบายทำงาน

รหัสข้อผิดพลาด สถานะ HTTP สาเหตุ แก้ไข
steps.keyvaluemapoperations.SetVariableFailed 500

ข้อผิดพลาดนี้เกิดขึ้นหากคุณพยายามเรียกค่าจากแมปค่าคีย์ที่เข้ารหัส แล้วตั้งค่าเป็นตัวแปรที่มีชื่อไม่ได้ขึ้นต้นด้วย private คำนำหน้าซึ่งจำเป็นสำหรับวัตถุประสงค์ด้านความปลอดภัยขั้นพื้นฐานระหว่างการแก้ไขข้อบกพร่อง จะซ่อนค่าที่เข้ารหัสจากการติดตามพร็อกซี API และเซสชันการแก้ไขข้อบกพร่อง

steps.keyvaluemapoperations.UnsupportedOperationException 500

ข้อผิดพลาดนี้เกิดขึ้นหากมีการตั้งค่าแอตทริบิวต์ mapIdentifier เป็นสตริงว่างเปล่าในนโยบายการดำเนินการแมปค่าคีย์

ข้อผิดพลาดในการทำให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้

ชื่อข้อผิดพลาด สาเหตุ แก้ไข
InvalidIndex หากแอตทริบิวต์ index ที่ระบุในองค์ประกอบ <Get> ของนโยบายการดำเนินการแมปค่าคีย์เป็น 0 หรือเป็นตัวเลขลบ จะทำให้การทำให้พร็อกซี API ใช้งานได้ไม่สำเร็จ ดัชนีจะเริ่มต้นจาก 1 ดังนั้นดัชนีที่เป็นจำนวนเต็ม 0 หรือจำนวนเต็มลบจึงถือว่าไม่ถูกต้อง
KeyIsMissing ข้อผิดพลาดนี้เกิดขึ้นหากองค์ประกอบ <Key> หายไปทั้งหมด หรือองค์ประกอบ <Parameter> หายไปภายในองค์ประกอบ <Key> ภายใต้องค์ประกอบ <Entry> ขององค์ประกอบ <InitialEntries> ของนโยบายการดำเนินการแมปค่าคีย์
ValueIsMissing ข้อผิดพลาดนี้เกิดขึ้นหากองค์ประกอบ <Value> หายไปใต้องค์ประกอบ <Entry> ขององค์ประกอบ <InitialEntries> ของนโยบายการดำเนินการแมปค่าคีย์

สคีมา

หมายเหตุการใช้งาน

โปรดดูภาพรวมของแมปค่าคีย์ที่หัวข้อการทํางานกับแมปค่าคีย์

การจัดเก็บแมปค่าคีย์มีกลไกการคงอยู่ของข้อมูลที่จัดรูปแบบเป็นคู่คีย์-ค่าที่ใช้ทรัพยากรน้อย คุณเข้าถึงรายการเหล่านี้ได้ขณะรันไทม์ผ่านนโยบายหรือโค้ด แผนที่มีข้อมูลที่กำหนดเองในรูปแบบ 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 เพื่อเลือกที่อยู่เป้าหมายแบ็กเอนด์แบบไดนามิก และอื่นๆ ได้ โดยทั่วไปแล้ว นโยบาย KeyValueMapOperatings จะใช้เพื่อจัดเก็บหรือเรียกข้อมูลเป็นระยะเวลานานซึ่งจำเป็นต้องใช้ซ้ำในธุรกรรมคำขอ/การตอบกลับหลายรายการ

คุณจัดการแมปคีย์/ค่าได้ผ่านนโยบาย KeyValueMapEnforcements หรือผ่าน Apigee Edge Management API โดยตรง โปรดดูรายละเอียดเกี่ยวกับ API การแมปคีย์/ค่าองค์กรจากเอกสารอ้างอิง API การจัดการ คุณใช้ API ได้ เช่น อัปโหลดชุดข้อมูลขนาดใหญ่ไปยังที่เก็บคีย์/ค่า หรือสร้างสคริปต์เพื่อจัดการรายการแมปคีย์/ค่า คุณจะต้องสร้างแมปคีย์/ค่าด้วย API ก่อนที่จะเข้าถึงด้วยนโยบาย KeyValueMapEnforcements

การระบุและเรียกชื่อคีย์

เมื่อใช้องค์ประกอบ <Parameter> และ <Value> คุณจะระบุค่าลิเทอรัล (โดยที่ค่าอยู่ระหว่างแท็กเปิดกับแท็กปิด) หรือใช้แอตทริบิวต์ ref เพื่อระบุชื่อของตัวแปรที่ควรใช้ค่าในรันไทม์ก็ได้

องค์ประกอบพารามิเตอร์ควรมีการพูดถึงแบบพิเศษ เนื่องจากจะเป็นตัวกำหนดชื่อของคีย์ที่สร้างขึ้น รวมถึงชื่อคีย์ที่คุณต้องการเรียกหรือลบ ต่อไปนี้เป็นตัวอย่าง 2 ตัวอย่าง รายการแรกระบุชื่อคีย์ตามตัวอักษร และคีย์ที่สองระบุชื่อคีย์โดยใช้ตัวแปร สมมติว่าข้อมูลต่อไปนี้ใช้สำหรับสร้างคีย์ใน KVM:

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

ในอินสแตนซ์แรก ระบบจะจัดเก็บค่าลิเทอรัลของ "key_name_literal" ไว้ใน KVM เป็นชื่อคีย์ ในอินสแตนซ์ที่ 2 ค่าใดก็ตามที่อยู่ใน key.name.variable จะกลายเป็นชื่อของคีย์ใน KVM เช่น หาก key.name.variable มีค่า foo คีย์จะมีชื่อว่า "foo"

เมื่อต้องการเรียกข้อมูลคีย์และค่าคีย์ด้วยการดำเนินการ GET (หรือลบด้วยการดำเนินการ DELETE) การตั้งค่า <พารามิเตอร์> ต้องตรงกับชื่อคีย์ใน KVM เช่น หากชื่อคีย์ใน KVM คือ "foo" คุณจะระบุค่าลิเทอรัลด้วย <Parameter>foo</Parameter> หรือระบุตัวแปรที่มีค่า "foo" ตรงตามค่าก็ได้ เช่น <Parameter ref="variable.containing.foo"/>

หัวข้อที่เกี่ยวข้อง