การทํางานกับแผนที่ค่าคีย์

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

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

ดูข้อมูลเกี่ยวกับการคงอยู่ประเภทอื่นๆ ได้ที่การเพิ่มการแคชและการคงอยู่

สถานการณ์ KVM

สถานการณ์ที่ KVM มีประโยชน์มีดังนี้

• คุณมีพร็อกซี API ที่ต้องเรียกใช้ URL เป้าหมาย (หรือคำขอราคาเสนอบริการ) ในสภาพแวดล้อมการทดสอบ และ URL เป้าหมายอีกรายการหนึ่งในสภาพแวดล้อมเวอร์ชันที่ใช้งานจริง คุณสามารถให้พร็อกซีตรวจหาสภาพแวดล้อมของพร็อกซีแทนฮาร์ดโค้ด URL เรียกใช้นโยบายการดำเนินการแมปค่าคีย์ที่เกี่ยวข้อง และเรียกข้อมูล URL เป้าหมายที่ถูกต้องจาก KVM ที่คุณสร้างขึ้น 1 รายการได้ และหลังจากนั้น หากเป้าหมายข้อใดข้อหนึ่งหรือทั้ง 2 ข้อมีการเปลี่ยนแปลง คุณก็เพียงอัปเดต KVM ด้วย URL ใหม่ พร็อกซีจะรับค่าใหม่ และไม่จำเป็นต้องทำให้พร็อกซีใช้งานได้อีกครั้ง
• คุณต้องการจัดเก็บข้อมูลเข้าสู่ระบบ คีย์ส่วนตัว หรือโทเค็น เช่น โทเค็นสำหรับบริการภายนอก ข้อมูลเข้าสู่ระบบที่จำเป็นในการสร้างโทเค็น OAuth หรือคีย์ส่วนตัวที่ใช้ใน Java คำขอราคาเสนอ หรือ JavaScript สำหรับการเข้ารหัสหรือการลงชื่อ JSON Web Token (JWT) แทนที่จะส่งผ่านข้อมูลเข้าสู่ระบบ คีย์ หรือโทเค็นในคำขอหรือฮาร์ดโค้ดไว้ในตรรกะพร็อกซี คุณอาจจัดเก็บคีย์เหล่านั้นไว้ใน KVM (เข้ารหัสเสมอ) และเรียกข้อมูลแบบไดนามิกในการเรียกไปยังเป้าหมายที่ต้องการได้

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

• บางตำแหน่งในโค้ดของคุณต้องการค่าที่ต่างกันในระหว่างรันไทม์
• ข้อมูลที่ละเอียดอ่อนจะต้องส่งผ่านโดยไม่ต้องฮาร์ดโค้ดข้อมูล
• คุณต้องการจัดเก็บค่าที่ไม่มีวันหมดอายุในลักษณะเดียวกับแคช

KVM มีขอบเขต

ขอบเขตหมายถึง "พื้นที่ที่ KVM พร้อมใช้งาน" คุณสร้าง KVM ในขอบเขตต่อไปนี้: organization, environment และ apiproxy

ตัวอย่างเช่น หากมีพร็อกซี API เพียง 1 รายการที่ต้องใช้ข้อมูลใน KVM คุณก็สร้าง KVM ที่ขอบเขต apiproxy ได้ ซึ่งมีเพียงพร็อกซี API นั้นเท่านั้นที่จะเข้าถึงข้อมูลได้

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

หากต้องการให้พร็อกซีทั้งหมดในทุกสภาพแวดล้อมเข้าถึง KVM เดียวกัน ให้สร้าง KVM ที่ขอบเขต organization

เกี่ยวกับ KVM ที่เข้ารหัส

ระบบจะเข้ารหัส KVM ที่เข้ารหัสด้วยคีย์การเข้ารหัส AES-128 ที่ Apigee สร้างขึ้น ระบบจะจัดเก็บคีย์ที่ใช้เข้ารหัส KVM ไว้ในขอบเขตของ KVM ตัวอย่างเช่น ภายในองค์กร ระบบจะสร้าง KVM ที่เข้ารหัสทั้งหมดที่คุณสร้างในขอบเขตสภาพแวดล้อมโดยใช้คีย์ที่กำหนดขอบเขตสภาพแวดล้อมเดียวกัน

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

UI ของ Edge

แมปค่าคีย์ที่เข้ารหัสจะแสดงค่าที่มีเครื่องหมายดอกจันใน UI (*****) เช่น

Management API

ใน API การจัดการ ระบบจะมาสก์ค่าที่เข้ารหัส ต่อไปนี้คือตัวอย่างการตอบสนองของ API การจัดการในการเรียก KVM ที่เข้ารหัส

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

ติดตามและแก้ไขข้อบกพร่อง

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

ข้อจำกัด

ในองค์กรที่เปิดใช้ Core Persistence Services (CPS) ไว้ดังนี้

• ชื่อ/ตัวระบุ KVM จะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
• คีย์ต้องมีขนาดไม่เกิน 2 KB
• ค่าต้องไม่เกิน 10 KB

สำหรับ Apigee Edge สำหรับ Private Cloud นั้น KVM แต่ละรายการไม่ควรเกิน 15 MB (ซึ่งเป็นขนาดคีย์และค่ารวมกัน) หากมีการใช้งานเกินขีดจำกัดนี้ Apigee Edge สำหรับ Private Cloud จะแสดงข้อผิดพลาด หากต้องการกำหนดขนาดของ KVM ให้ใช้คำสั่ง nodetool cfstats

KVM ที่มีขนาดใหญ่กว่าอาจส่งผลให้ประสิทธิภาพลดลง ด้วยเหตุนี้ คุณจึงควรแยก KVM ขนาดใหญ่แบบโมโนลิธออกเป็นขนาดเล็กๆ เพื่อปรับปรุงประสิทธิภาพ

การจัดการและการใช้ KVM

คุณสร้าง จัดการ และใช้ KVM ได้หลายวิธี ส่วนนี้จะอธิบายถึงตัวเลือกต่างๆ ในการสร้างและเรียกข้อมูล KVM ทั้งที่เข้ารหัสและไม่ได้เข้ารหัส

การสร้างและการอัปเดต KVM

คุณสร้างและอัปเดต KVM ได้ด้วยวิธีต่อไปนี้

• นโยบายการดำเนินการแมปค่าคีย์ (ไม่มีการเข้ารหัส)

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

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

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

• API การจัดการ

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

  Key/Value Maps Management API ช่วยให้คุณสร้าง อัปเดต และลบ KVM และคีย์/ค่าที่เข้ารหัสได้ในขอบเขตทั้งหมด (องค์กร สภาพแวดล้อม และ apiproxy)

  หากต้องการสร้าง KVM ที่เข้ารหัสด้วย API การจัดการ ให้เพิ่ม "encrypted" : "true" ไปยังเพย์โหลด JSON คุณจะเข้ารหัส KVM ได้ก็ต่อเมื่อสร้าง KVM เท่านั้น คุณเข้ารหัส KVM ที่มีอยู่ไม่ได้

• UI การจัดการ

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

กำลังดึงข้อมูล KVM

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

• นโยบาย: ใช้องค์ประกอบ <Get> ในนโยบายการดำเนินการแมปค่าคีย์เพื่อเรียกข้อมูล KVM ที่เข้ารหัสและไม่ได้เข้ารหัส ความแตกต่างเล็กน้อยอย่างหนึ่งคือการดึงข้อมูลค่าที่เข้ารหัสด้วยนโยบาย ซึ่งคุณต้องเพิ่ม "private." นำหน้าชื่อของตัวแปรซึ่งมีค่าที่ดึงมา ตามที่อธิบายไว้ในส่วนรับการดำเนินการของหัวข้ออ้างอิง คำนำหน้าดังกล่าวจะซ่อนค่าจากเซสชันการติดตามและแก้ไขข้อบกพร่องขณะที่คุณกำลังแก้ไขข้อบกพร่องพร็อกซี API
• Management API: ใช้เพื่อการจัดการด้านการดูแลระบบ คุณสามารถใช้การสร้างและแก้ไขแมปคีย์ค่าของสภาพแวดล้อมเพื่อรับ KVM และคีย์/ค่า เช่น หากต้องการสำรองข้อมูล KVM โดยรับและจัดเก็บการกำหนด JSON ให้ใช้ Management API อย่างไรก็ตาม โปรดทราบว่าค่าที่เข้ารหัสจะแสดงเป็น ***** ในการตอบกลับของ API
• UI การจัดการ: คุณสามารถดู KVM ที่กำหนดขอบเขตสภาพแวดล้อมได้ใน UI การจัดการ โดยไปที่ API > การกำหนดค่าสภาพแวดล้อม > แมปค่าคีย์ (EDGE) หรือผู้ดูแลระบบ > สภาพแวดล้อม > แมปค่าคีย์ (EDGE ใหม่)

ตัวอย่าง KVM

ดูตัวอย่างการใช้ KVM เพื่อป้อนข้อมูลค่าใน URL ได้ที่ https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html