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

คุณกำลังดูเอกสารประกอบของ 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

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

    ดูQuotaด้วย

  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 เมื่อสร้างผลิตภัณฑ์ 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 ดังนี้

    $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 ที่ถูกต้องใช้งานไม่ได้

    การบันทึก

    คุณปรับระดับการบันทึกในบริการ $REMOTE_SERVICE_HOME/apigee-remote-service-envoy ได้ ระบบจะส่งการบันทึกทั้งหมดไปยัง stdout และ 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 ได้ที่ภาพรวมบริการข้อมูลวิเคราะห์

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

    ตอนนี้คุณสามารถเปิดใช้อะแดปเตอร์เพื่อให้บริการสภาพแวดล้อมหลายรายการในองค์กร Apigee ได้แล้ว ฟีเจอร์นี้ช่วยให้คุณใช้ Apigee Adapter for 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