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

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

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

ตัวอย่างต่อไปนี้อธิบายวิธีรับคีย์ API ที่ใช้ตรวจสอบการเรียก API ไปยังบริการเป้าหมายผ่านพร็อกซี Apigee สำหรับ 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 สำหรับ Envoy

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

    ดูเพิ่มเติมที่โควต้า

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    โควต้า

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

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

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

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

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

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

    บริการ Apigee Remote จะบังคับใช้โควต้าที่ป้อนในคำจำกัดความผลิตภัณฑ์โดยอัตโนมัติ ซึ่งต่างจากรันไทม์ของ 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

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

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

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

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

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

    curl https://org-env.apigee.net/remote-token/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 เพื่อตรวจสอบโทเค็นได้ ตัวอย่าง

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

    หรือ 

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

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

    โปรดดูคีย์ API ที่ถูกต้องล้มเหลว

    Logging

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

    องค์ประกอบ จำเป็น คำอธิบาย
    -l, --ระดับการบันทึก ระดับที่ใช้ได้ เช่น การแก้ไขข้อบกพร่อง ข้อมูล คำเตือน ข้อผิดพลาด ปรับระดับการบันทึก ค่าเริ่มต้น: ข้อมูล
    -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 ได้ที่ภาพรวมบริการ Analytics

    การสนับสนุนสภาพแวดล้อมแบบหลายกลุ่มผู้ใช้

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

    หากต้องการกำหนดค่าการรองรับสภาพแวดล้อมหลายรายการ ให้เปลี่ยนค่าของ tenant:env_name เป็น * ในไฟล์ config.yaml เช่น

    1. เปิดไฟล์ config.yaml ในตัวแก้ไข
    2. เปลี่ยนค่าของ tenant.env_name เป็น * ตัวอย่างเช่น 
      apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://myorg-myenv.apigee.net/remote-service
      org_name: apigee-docs-hybrid-a
      env_name: *
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token
    3. บันทึกไฟล์
    4. ใช้ไฟล์: 
      kubectl apply -f $CLI_HOME/config.yaml

    เมื่อกำหนดค่าโหมดหลายสภาพแวดล้อม คุณต้องกำหนดค่า Envoy ให้ส่งค่าสภาพแวดล้อมที่เหมาะสมไปยังอะแดปเตอร์ด้วยโดยเพิ่มข้อมูลเมตาต่อไปนี้ในส่วน virtual_hosts:routes ของไฟล์ envoy-config.yaml เช่น

    1. สร้างไฟล์ envoy-config.yaml โดยใช้ CLI ตัวอย่างเช่น 
      $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
    2. เปิดไฟล์ที่สร้างขึ้น (ชื่อว่า envoy-config.yaml)
    3. เพิ่มข้อมูลเมตาต่อไปนี้ในส่วน virtual_host หรือ routes ของไฟล์ 
      typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

      ตัวอย่างต่อไปนี้แสดงการกำหนดค่าสำหรับ virtual_host ที่มีการกำหนดเส้นทางไว้หลายเส้นทาง โดยแต่ละเส้นทางจะส่งการจราจรของข้อมูลไปยังสภาพแวดล้อมเฉพาะ 

      filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod
    4. ทําขั้นตอนสุดท้ายซ้ำเพื่อเพิ่มสภาพแวดล้อมเพิ่มเติมตามต้องการ
    5. บันทึกไฟล์และใช้

    การกำหนดค่า mTLS ระหว่างอะแดปเตอร์และรันไทม์ Apigee

    คุณระบุใบรับรอง TLS ฝั่งไคลเอ็นต์ได้ในส่วน tenant ของไฟล์ config.yaml ของอะแดปเตอร์เพื่อใช้ mTLS ระหว่างอะแดปเตอร์และรันไทม์ของ Apigee การเปลี่ยนแปลงนี้มีผลกับแพลตฟอร์ม Apigee ทั้งหมดที่รองรับ และยังเปิดใช้ mTLS สำหรับข้อมูลวิเคราะห์ของ Apigee Edge สำหรับแพลตฟอร์ม Private Cloud อีกด้วย เช่น 

    tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false