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

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

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

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

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

  1. เปิด UI ของ Apigee ในเบราว์เซอร์
  2. เมื่ออยู่ใน UI แล้ว ให้เลือกองค์กรเดียวกันกับที่ใช้กำหนดค่า Apigee Adapter สำหรับ 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
    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 สำหรับ Envoy ให้จัดการ

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

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

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

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

คำจำกัดความผลิตภัณฑ์ API จะมีผลกับคำขอหากคำขอตรงกับทั้งเป้าหมาย binding (เช่น 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 กับผลิตภัณฑ์ 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 อาจมีลักษณะดังนี้

  • "ไม่อนุญาตให้ใช้กลุ่มเป้าหมายใน 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 Remote Service for Envoy จะส่งสถิติคำขอไปยัง Apigee เพื่อประมวลผลการวิเคราะห์ Apigee จะรายงานคำขอเหล่านี้ภายใต้ชื่อผลิตภัณฑ์ API ที่เชื่อมโยง

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