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

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

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

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

สถานการณ์ KVM

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

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

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

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

KVM มีขอบเขต

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

ตัวอย่างเช่น หากมีพร็อกซี API เพียงรายการเดียวที่ต้องใช้ข้อมูลใน 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

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

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

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

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

จำกัดสูงสุด

ในองค์กรที่เปิดใช้ บริการความคงทนหลัก (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 ได้ด้วยวิธีต่อไปนี้

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

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

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

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

• Management API

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

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

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

• UI การจัดการ

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

การเรียกข้อมูล KVM

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

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

ตัวอย่าง KVM

ดูตัวอย่างการใช้ KVM เพื่อป้อนค่าใน URL ได้ที่ สร้างเทมเพลต URL เป้าหมายด้วย KVM ตามสภาพแวดล้อม