คู่มือการใช้งาน

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

วิธีรับคีย์ API

ตัวอย่างต่อไปนี้อธิบายวิธีรับคีย์ API ที่คุณใช้เพื่อตรวจสอบ การเรียก API ไปยังบริการเป้าหมายที่พร็อกซีผ่าน Apigee Adapter for Envoy ได้

1. เข้าสู่ระบบ Apigee

  1. เปิด UI ของ Apigee ในเบราว์เซอร์
  2. เมื่ออยู่ใน UI แล้ว ให้เลือกองค์กรเดียวกับที่ใช้กำหนดค่า Apigee Adapter for Envoy

2. สร้างนักพัฒนาซอฟต์แวร์

คุณสามารถใช้นักพัฒนาซอฟต์แวร์ที่มีอยู่เพื่อทำการทดสอบ หรือสร้างนักพัฒนาซอฟต์แวร์ใหม่โดยทำดังนี้

  1. เลือกเผยแพร่ > นักพัฒนาซอฟต์แวร์ ในเมนูการนำทางด้านข้าง
  2. คลิก + นักพัฒนาซอฟต์แวร์
  3. กรอกข้อมูลในกล่องโต้ตอบเพื่อสร้างนักพัฒนาซอฟต์แวร์ใหม่ คุณสามารถใช้ชื่อ/อีเมลของนักพัฒนาซอฟต์แวร์ที่ต้องการได้

3. สร้างผลิตภัณฑ์ API

ทำตามตัวอย่างการสร้างผลิตภัณฑ์ที่ให้ไว้ด้านล่าง ดูเพิ่มเติมเกี่ยวกับ ข้อมูลการกำหนดค่าผลิตภัณฑ์ API

  1. เลือกเผยแพร่ > ผลิตภัณฑ์ API ในเมนูการนำทางด้านข้าง
  2. คลิก + ผลิตภัณฑ์ API.
  3. กรอกข้อมูลในหน้ารายละเอียดผลิตภัณฑ์ดังนี้ อย่าคลิกบันทึก จนกว่าจะได้รับคำแนะนำให้ทำ
    4. ช่อง ค่า
    ชื่อ httpbin-product
    ชื่อที่แสดง httpbin product
    สภาพแวดล้อม your_environment

    ตั้งค่านี้เป็นสภาพแวดล้อมที่คุณใช้เมื่อจัดเตรียม Apigee Adapter for Envoy ด้วย apigee-remote-service-cli

    สิทธิ์เข้าถึง Private
    Quota 5 คำขอทุก 1 นาที

    ดูเพิ่มเติมเกี่ยวกับ ข้อมูลโควต้า

  4. ในส่วนเป้าหมายของบริการระยะไกลของ Apigee ให้คลิกเพิ่มเป้าหมายของบริการระยะไกลของ Apigee
  5. ในกล่องโต้ตอบเป้าหมายของบริการระยะไกลของ Apigee ให้เพิ่มค่าต่อไปนี้
    แอตทริบิวต์ ค่า คำอธิบาย
    ชื่อเป้าหมาย ป้อนชื่อบริการเป้าหมาย เช่น httpbin.org ปลายทางเป้าหมายที่พร็อกซี Envoy อยู่ด้านหน้า
    พร็อกซี API remote-service พร็อกซี remote-service ที่มีการจัดเตรียมใน Apigee ระหว่างการติดตั้ง Envoy Adapter
    เส้นทาง ป้อน /resource_path เพื่อให้ตรงกับเส้นทางที่เฉพาะเจาะจง เช่น ตัวอย่าง: /httpbin เส้นทางคำขอที่จะจับคู่กับปลายทางเป้าหมาย การเรียกพร็อกซี API ไปยังเส้นทางนี้ จะตรงกับผลิตภัณฑ์ API นี้

    Edge Public หรือ Private Cloud: ภาพหน้าจอต่อไปนี้แสดงการตั้งค่ากล่องโต้ตอบที่กำหนดค่าอย่างถูกต้องสำหรับเป้าหมาย httpbin.org ซึ่งเป็นการกำหนดค่าที่เหมาะสมสำหรับ Apigee Edge Public หรือ Private Cloud

  6. คลิกบันทึก

4. สร้างแอปนักพัฒนาซอฟต์แวร์

  1. เลือกเผยแพร่ > แอป ในเมนูการนำทางด้านข้าง
  2. คลิก + แอป
  3. กรอกข้อมูลในหน้าแอปนักพัฒนาซอฟต์แวร์ดังนี้ อย่าบันทึกจนกว่าจะได้รับคำแนะนำให้ทำ
    4. ชื่อ httpbin-app
    ชื่อที่แสดง httpbin app
    นักพัฒนาซอฟต์แวร์ เลือกนักพัฒนาซอฟต์แวร์ที่คุณสร้างไว้ก่อนหน้านี้ หรือเลือกนักพัฒนาซอฟต์แวร์ที่ต้องการจากรายการ
  4. จากนั้นเพิ่มผลิตภัณฑ์ 2 รายการลงในแอป โดยทำดังนี้
    1. ขั้นแรก ในส่วนข้อมูลเข้าสู่ระบบ ให้คลิก + เพิ่มผลิตภัณฑ์ แล้วเลือกผลิตภัณฑ์ที่คุณ เพิ่งกำหนดค่า: httpbin-product
    2. จากนั้นเพิ่มผลิตภัณฑ์ remote-service ระบบจะสร้างผลิตภัณฑ์นี้โดยอัตโนมัติเมื่อคุณจัดเตรียม Apigee
  5. คลิกสร้าง
  6. ในส่วนข้อมูลเข้าสู่ระบบ ให้คลิกแสดง ข้างคีย์
  7. คัดลอกค่าคีย์ผู้ใช้บริการ ค่านี้คือคีย์ API ที่คุณจะใช้เพื่อเรียก API ไปยังบริการ httpbin

เกี่ยวกับผลิตภัณฑ์ API

ผลิตภัณฑ์ API เป็นจุดควบคุมหลัก สำหรับบริการระยะไกลของ Apigee เมื่อสร้างผลิตภัณฑ์ API และผูกผลิตภัณฑ์กับบริการเป้าหมาย คุณกำลังสร้างนโยบายที่จะมีผลกับคำขอใดก็ตามที่คุณกำหนดค่า Apigee Adapter for Envoy ให้จัดการ

คำจำกัดความของผลิตภัณฑ์ API

เมื่อกำหนดผลิตภัณฑ์ API ใน Apigee คุณสามารถตั้งค่าพารามิเตอร์จำนวนหนึ่งที่ จะใช้ในการประเมินคำขอได้ ดังนี้

  • เป้าหมาย
  • เส้นทางคำขอ
  • Quota
  • ขอบเขต OAuth

เป้าหมายของบริการระยะไกล

คำจำกัดความของผลิตภัณฑ์ API จะมีผลกับคำขอหากคำขอตรงกับการผูกเป้าหมาย (เช่น httpbin.org) และเส้นทางคำขอ (เช่น /httpbin) ระบบจะจัดเก็บรายการเป้าหมายที่เป็นไปได้เป็นแอตทริบิวต์ในผลิตภัณฑ์ API

โดยค่าเริ่มต้น บริการระยะไกลของ Apigee จะตรวจสอบส่วนหัว :authority (host) พิเศษของ Envoy กับ รายการเป้าหมาย แต่คุณสามารถกำหนดค่าให้ใช้ส่วนหัวอื่นๆ ได้

เส้นทางทรัพยากร API

เส้นทางที่ป้อนจะตรงกันตามกฎต่อไปนี้

  • เครื่องหมายทับเดี่ยว (/) จะตรงกับเส้นทางใดก็ได้
  • * ใช้ได้ทุกที่และจะตรงกับภายในส่วน (ระหว่างเครื่องหมายทับ)
  • ** ใช้ได้ที่ส่วนท้ายและจะตรงกับทุกอย่างจนถึงท้ายบรรทัด

Quota

โควต้าจะระบุจำนวนข้อความคำขอที่แอปได้รับอนุญาตให้ส่งไปยัง API ในช่วงเวลา 1 ชั่วโมง 1 วัน 1 สัปดาห์ หรือ 1 เดือน เมื่อแอปถึงขีดจำกัดโควต้า ระบบจะปฏิเสธการเรียก API ครั้งต่อๆ ไป

กรณีการใช้งานโควต้า

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

โควต้ากำหนดไว้ในผลิตภัณฑ์ API

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

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

บริการระยะไกลของ Apigee จะบังคับใช้โควต้าที่ป้อนในคำจำกัดความของผลิตภัณฑ์โดยอัตโนมัติ ซึ่งต่างจากการบังคับใช้โควต้าภายในรันไทม์ของ Apigee หากคำขอได้รับอนุญาต ระบบจะนับคำขอเทียบกับโควต้าที่อนุญาต

ตำแหน่งที่เก็บรักษาโควต้า

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

ขอบเขต OAuth

หากใช้โทเค็น JWT คุณสามารถจำกัดโทเค็นให้เป็นชุดย่อยของขอบเขต OAuth ที่อนุญาตได้ ระบบจะตรวจสอบขอบเขตที่กำหนดให้กับโทเค็น JWT ที่ออกเทียบกับขอบเขตของผลิตภัณฑ์ API

เกี่ยวกับแอปนักพัฒนาซอฟต์แวร์

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

การใช้การตรวจสอบสิทธิ์ตาม JWT

คุณสามารถใช้โทเค็น JWT เพื่อเรียกพร็อกซี API ที่มีการตรวจสอบสิทธิ์แทนการใช้คีย์ API ได้ ส่วนนี้จะอธิบายวิธีใช้คำสั่ง apigee-remote-service-cli token เพื่อสร้าง ตรวจสอบ และหมุนเวียนโทเค็น JWT

ภาพรวม

Envoy จะจัดการการตรวจสอบและการตรวจสอบสิทธิ์ JWT โดยใช้ตัวกรองการตรวจสอบสิทธิ์ JWT

เมื่อตรวจสอบสิทธิ์แล้ว ตัวกรอง ext-authz ของ Envoy จะส่งส่วนหัวคำขอและ JWT ไปยัง apigee-remote-service-envoy โดยจะจับคู่การอ้างสิทธิ์ api_product_list และ scope ของ JWT กับผลิตภัณฑ์ API ของ Apigee เพื่อให้สิทธิ์เข้าถึงเป้าหมายของคำขอ

การสร้างโทเค็น JWT ของ Apigee

คุณสร้างโทเค็น JWT ของ Apigee ได้โดยใช้ CLI ดังนี้

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

หรือโดยใช้ปลายทางโทเค็น OAuth มาตรฐาน ตัวอย่าง curl

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

การใช้โทเค็น JWT

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

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

โทเค็น JWT ไม่ทำงาน

Envoy ปฏิเสธ

หาก Envoy ปฏิเสธโทเค็น คุณอาจเห็นข้อความต่อไปนี้

Jwks remote fetch is failed

หากเป็นเช่นนั้น ให้ตรวจสอบว่าการกำหนดค่า Envoy มี URI ที่ถูกต้องในส่วน remote_jwks ซึ่ง Envoy เข้าถึงได้ และคุณได้ตั้งค่าใบรับรองอย่างถูกต้องเมื่อติดตั้งพร็อกซี Apigee คุณควรจะเรียก URI ได้โดยตรงด้วยการเรียก GET และได้รับการตอบกลับ JSON ที่ถูกต้อง

ตัวอย่าง

curl --http1.1 https://myorg-eval-test.apigee.net/remote-service/certs

ข้อความอื่นๆ จาก Envoy อาจมีลักษณะดังนี้

  • "ไม่อนุญาตให้ใช้กลุ่มเป้าหมายใน JWT"
  • "ไม่ได้กำหนดค่าผู้ออก JWT"

ข้อความเหล่านี้มาจากข้อกำหนดในการกำหนดค่า Envoy ที่คุณอาจต้องแก้ไข

ตรวจสอบโทเค็น

คุณสามารถใช้ CLI เพื่อตรวจสอบโทเค็นได้ ตัวอย่าง

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

หรือ 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

การแก้ไขข้อบกพร่อง

ดูคีย์ API ที่ถูกต้องไม่ทำงาน

การบันทึก

คุณสามารถปรับระดับการบันทึกในบริการ $REMOTE_SERVICE_HOME/apigee-remote-service-envoy ได้ ระบบจะส่งการบันทึกทั้งหมดไปยัง stderr

องค์ประกอบ ต้องระบุ คำอธิบาย
-l, --log_level ระดับที่ใช้ได้คือ debug, info, warn, error ปรับระดับการบันทึก ค่าเริ่มต้น: info
-j, --json_log แสดงเอาต์พุตบันทึกเป็นระเบียน JSON

Envoy มีฟีเจอร์การบันทึก ดูข้อมูลเพิ่มเติมได้จากลิงก์เอกสารประกอบของ Envoy ต่อไปนี้

การใช้พร็อกซีเครือข่าย

คุณสามารถแทรกพร็อกซี HTTP ได้โดยใช้ตัวแปรสภาพแวดล้อม HTTP_PROXY และ HTTPS_PROXY ในสภาพแวดล้อมของไบนารี apigee-remote-service-envoy เมื่อใช้ตัวแปรเหล่านี้ คุณยังใช้ตัวแปรสภาพแวดล้อม NO_PROXY เพื่อยกเว้นโฮสต์ที่เฉพาะเจาะจงไม่ให้ส่งผ่านพร็อกซีได้ด้วย

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

โปรดทราบว่า apigee-remote-service-envoy ต้องเข้าถึงพร็อกซีได้

เกี่ยวกับเมตริกและข้อมูลวิเคราะห์

ปลายทางเมตริกของ Prometheus พร้อมใช้งานที่ :5001/metrics คุณสามารถกำหนดค่าหมายเลขพอร์ตนี้ได้ ดูไฟล์การกำหนดค่า

ข้อมูลวิเคราะห์ของ Envoy

ลิงก์ต่อไปนี้มีข้อมูลเกี่ยวกับการรับข้อมูลวิเคราะห์ของพร็อกซี Envoy

ข้อมูลวิเคราะห์ของ Istio

ลิงก์ต่อไปนี้มีข้อมูลเกี่ยวกับการรับข้อมูลวิเคราะห์ของพร็อกซี Envoy

ข้อมูลวิเคราะห์ของ Apigee

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

ดูข้อมูลเกี่ยวกับข้อมูลวิเคราะห์ของ Apigee ได้ที่ ภาพรวมของบริการข้อมูลวิเคราะห์