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

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

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

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

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

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

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

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

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

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

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

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

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

    สิทธิ์เข้าถึง Private
    โควต้า คำขอ 5 รายการทุก 1 นาที

    โปรดดูเพิ่มเติมที่การทำความเข้าใจเกี่ยวกับโควต้า

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    โควต้า

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

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

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

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

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

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

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

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

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

    ขอบเขต 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 ที่มีต่อผลิตภัณฑ์ Apigee API เพื่อให้สิทธิ์กับการกำหนดเป้าหมายของคำขอดังกล่าว

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

    คุณสร้างโทเค็น Apigee JWT ได้โดยใช้ 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 เข้าถึง URI ได้ และคุณตั้งค่าใบรับรองอย่างถูกต้องเมื่อติดตั้งพร็อกซี Apigee คุณควรเรียกใช้ URI ได้โดยตรงด้วยการเรียก GET และได้รับการตอบสนอง JSON ที่ถูกต้อง

    ตัวอย่าง

    curl 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 ปรับระดับการบันทึก ค่าเริ่มต้น: ข้อมูล
    -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 ได้ที่ภาพรวมบริการข้อมูลวิเคราะห์