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

คุณกำลังดูเอกสารประกอบของ 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 https://myorg-eval-test.apigee.net/remote-service/certs

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

  • "Audiences in Jwt are not allowed"
  • "Jwt issuer is not configured"

ข้อความเหล่านี้มาจากข้อกำหนดในการกำหนดค่า 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 ได้ที่ ภาพรวมของบริการข้อมูลวิเคราะห์