Hướng dẫn vận hành

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Cách lấy khoá API

Ví dụ sau đây giải thích cách lấy một khoá API mà bạn có thể dùng để xác thực các lệnh gọi API đến một dịch vụ đích được uỷ quyền thông qua Apigee Adapter for Envoy.

1. Đăng nhập vào Apigee

  1. Mở giao diện người dùng Apigee trong trình duyệt.
  2. Sau khi bạn truy cập vào giao diện người dùng, hãy chọn cùng một tổ chức mà bạn đã dùng để định cấu hình Apigee Adapter for Envoy.

2. Tạo nhà phát triển

Bạn có thể sử dụng nhà phát triển hiện có để kiểm thử hoặc tạo một nhà phát triển mới như sau:

  1. Chọn Xuất bản > Nhà phát triển trong trình đơn điều hướng bên.
  2. Nhấp vào + Nhà phát triển.
  3. Điền thông tin vào hộp thoại để tạo một nhà phát triển mới. Bạn có thể sử dụng tên/email nhà phát triển bất kỳ mà bạn muốn.

3. Tạo một Sản phẩm API

Hãy làm theo ví dụ về việc tạo sản phẩm được cung cấp bên dưới. Xem thêm Giới thiệu về cấu hình sản phẩm API.

  1. Chọn Xuất bản > Sản phẩm API trong trình đơn điều hướng bên.
  2. Nhấp vào + API Product (Sản phẩm API).
  3. Điền thông tin vào trang Chi tiết sản phẩm như sau.
    4. Trường Giá trị
    Tên httpbin-product
    Tên hiển thị httpbin product
    Môi trường your_environment

    Đặt giá trị này thành môi trường mà bạn đã sử dụng khi cung cấp Apigee Adapter for Envoy.

    Quyền truy cập Private
    Quota 5 yêu cầu mỗi 1 phút

    Xem thêm Quota.

  4. Trong mục Apigee remote service targets (Mục tiêu dịch vụ từ xa của Apigee), hãy nhấp vào Add an Apigee remote service target (Thêm mục tiêu dịch vụ từ xa của Apigee).
  5. Trong hộp thoại đích dịch vụ từ xa Apigee, hãy thêm các giá trị sau:
    Thuộc tính Giá trị Mô tả
    Tên mục tiêu Nhập tên của dịch vụ mục tiêu. Ví dụ: httpbin.org Điểm cuối mục tiêu được proxy Envoy chuyển tiếp.
    Đường dẫn Nhập đường dẫn tài nguyên trên dịch vụ để so khớp. Ví dụ: /headers. Đường dẫn yêu cầu cần so khớp trên điểm cuối mục tiêu. Các lệnh gọi proxy API đến đường dẫn này sẽ khớp với sản phẩm API này.
  6. Nhấp vào Lưu.

4. Tạo một Ứng dụng dành cho nhà phát triển

  1. Chọn Xuất bản > Ứng dụng trong trình đơn điều hướng bên.
  2. Nhấp vào + App (+ Ứng dụng).
  3. Điền thông tin vào trang Ứng dụng của nhà phát triển như sau. Đừng lưu cho đến khi được hướng dẫn.
    4. Tên httpbin-app
    Tên hiển thị httpbin app
    Nhà phát triển Chọn nhà phát triển mà bạn đã tạo trước đó hoặc chọn nhà phát triển bất kỳ mà bạn muốn trong danh sách.
  4. Tiếp theo, hãy thêm sản phẩm API vào ứng dụng:
    1. Trong phần Thông tin xác thực, hãy nhấp vào + Thêm sản phẩm rồi chọn sản phẩm mà bạn vừa định cấu hình: httpbin-product.
    2. Nhấp vào Tạo.
    3. Trong phần Thông tin xác thực, hãy nhấp vào Hiện bên cạnh Khoá.
    4. Sao chép giá trị của Khoá người dùng. Giá trị này là khoá API mà bạn sẽ dùng để thực hiện các lệnh gọi API đến dịch vụ httpbin.

    Giới thiệu về các sản phẩm API

    Sản phẩm API là điểm kiểm soát chính cho Dịch vụ từ xa của Apigee. Khi tạo một Sản phẩm API và liên kết sản phẩm đó với một dịch vụ đích, bạn sẽ tạo một chính sách được áp dụng cho mọi yêu cầu mà bạn định cấu hình Apigee Adapter for Envoy để xử lý.

    Định nghĩa về sản phẩm API

    Khi xác định một Sản phẩm API trong Apigee, bạn có thể đặt một số tham số sẽ được dùng để đánh giá các yêu cầu:

    • Mục tiêu
    • Đường dẫn yêu cầu
    • Hạn mức
    • Phạm vi OAuth

    Mục tiêu dịch vụ từ xa

    Định nghĩa API Product sẽ áp dụng cho một yêu cầu nếu yêu cầu đó khớp với cả liên kết mục tiêu (ví dụ: httpbin.org) và đường dẫn yêu cầu (ví dụ: /httpbin). Danh sách các mục tiêu tiềm năng được lưu trữ dưới dạng một thuộc tính trên API Product.

    Theo mặc định, Dịch vụ từ xa của Apigee sẽ kiểm tra tiêu đề :authority (host) đặc biệt của Envoy dựa trên danh sách mục tiêu; tuy nhiên, bạn có thể định cấu hình để sử dụng các tiêu đề khác.

    Đường dẫn tài nguyên API

    Đường dẫn bạn nhập sẽ khớp theo các quy tắc sau:

    • Một dấu gạch chéo (/) khớp với mọi đường dẫn.
    • * hợp lệ ở mọi nơi và khớp trong một phân đoạn (giữa các dấu gạch chéo).
    • ** hợp lệ ở cuối và khớp với mọi thứ cho đến cuối dòng.

    Hạn mức

    Hạn mức chỉ định số lượng thông báo yêu cầu mà một ứng dụng được phép gửi đến một API trong khoảng thời gian một giờ, một ngày, một tuần hoặc một tháng. Khi một ứng dụng đạt đến hạn mức, các lệnh gọi API tiếp theo sẽ bị từ chối.

    Các trường hợp sử dụng hạn mức

    Hạn mức cho phép bạn thực thi số lượng yêu cầu mà một ứng dụng có thể gửi đến một dịch vụ trong một khoảng thời gian nhất định. Hạn mức thường được dùng để thực thi các hợp đồng kinh doanh hoặc SLA với nhà phát triển và đối tác, thay vì để quản lý lưu lượng truy cập hoạt động. Ví dụ: bạn có thể sử dụng hạn mức để giới hạn lưu lượng truy cập cho một dịch vụ miễn phí, đồng thời cho phép khách hàng trả phí truy cập đầy đủ.

    Hạn mức được xác định trong một Sản phẩm API

    Các tham số hạn mức được định cấu hình trong Sản phẩm API. Ví dụ: khi tạo một Sản phẩm API, bạn có thể tuỳ ý đặt hạn mức cho phép, đơn vị thời gian và khoảng thời gian.

    Vì khoá API liên kết ngược với Sản phẩm API, nên mỗi khi khoá API được xác minh, bộ đếm hạn mức thích hợp có thể giảm (nếu Hạn mức được xác định trong Sản phẩm được liên kết).

    Không giống như trong thời gian chạy Apigee, Hạn mức được nhập trong định nghĩa Sản phẩm sẽ tự động được Apigee Remote Service thực thi. Nếu yêu cầu được uỷ quyền, thì yêu cầu đó sẽ được tính vào hạn mức cho phép.

    Nơi duy trì hạn mức

    Hạn mức được duy trì và kiểm tra cục bộ bằng quy trình Dịch vụ từ xa và được duy trì không đồng bộ với Thời gian chạy Apigee. Điều này có nghĩa là hạn mức không chính xác và có thể vượt quá nếu bạn có nhiều hơn một Dịch vụ từ xa đang duy trì hạn mức. Nếu kết nối đến Apigee Runtime bị gián đoạn, hạn mức cục bộ sẽ tiếp tục là một hạn mức độc lập cho đến khi có thể kết nối lại với Apigee Runtime.

    Phạm vi OAuth

    Nếu đang sử dụng mã thông báo JWT, bạn có thể hạn chế mã thông báo đối với các tập hợp con của phạm vi OAuth được phép. Các phạm vi được chỉ định cho mã thông báo JWT đã phát hành của bạn sẽ được kiểm tra dựa trên các phạm vi của Sản phẩm API.

    Giới thiệu về ứng dụng dành cho nhà phát triển

    Sau khi định cấu hình Sản phẩm API, bạn sẽ tạo một Ứng dụng được liên kết với một Nhà phát triển. Ứng dụng này cho phép một ứng dụng khách truy cập vào các Sản phẩm API được liên kết bằng Khoá API hoặc Mã thông báo JWT.

    Sử dụng phương thức xác thực dựa trên JWT

    Bạn có thể sử dụng mã thông báo JWT để thực hiện các lệnh gọi được xác thực đến proxy API thay vì sử dụng khoá API. Phần này giải thích cách sử dụng lệnh apigee-remote-service-cli token để tạo, kiểm tra và xoay vòng mã thông báo JWT.

    Tổng quan

    Envoy xử lý quy trình xác minh và xác thực JWT bằng Bộ lọc xác thực JWT.

    Sau khi được xác thực, bộ lọc ext-authz Envoy sẽ gửi tiêu đề yêu cầu và JWT đến apigee-remote-service-envoy. Nó so khớp các khai báo api_product_list và scope của JWT với các Sản phẩm API của Apigee để uỷ quyền cho JWT đối với mục tiêu của yêu cầu.

    Tạo mã thông báo JWT của Apigee

    Bạn có thể tạo mã thông báo JWT của Apigee bằng CLI:

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

    Hoặc bằng cách sử dụng điểm cuối mã thông báo OAuth tiêu chuẩn. Ví dụ về 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"

    Sử dụng mã thông báo JWT

    Sau khi có mã thông báo, bạn chỉ cần truyền mã đó đến Envoy trong tiêu đề Uỷ quyền. Ví dụ:

    curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

    Lỗi mã thông báo JWT

    Envoy rejection

    Nếu Envoy từ chối mã thông báo, bạn có thể thấy một thông báo như:

    Jwks remote fetch is failed

    Nếu có, hãy đảm bảo rằng cấu hình Envoy của bạn chứa một URI hợp lệ trong phần remote_jwks, rằng Envoy có thể truy cập vào URI đó và bạn đã thiết lập đúng các chứng chỉ khi cài đặt proxy Apigee. Bạn có thể gọi trực tiếp URI bằng lệnh gọi GET và nhận được phản hồi JSON hợp lệ.

    Ví dụ:

    curl https://myorg-eval-test.apigee.net/remote-service/certs

    Các thông báo khác từ Envoy có thể trông như sau:

    • "Không được phép sử dụng đối tượng trong Jwt"
    • "Jwt issuer is not configured" (Chưa định cấu hình đơn vị phát hành JWT)

    Đây là những yêu cầu trong cấu hình Envoy mà bạn có thể cần sửa đổi.

    Kiểm tra mã thông báo

    Bạn có thể dùng CLI để kiểm tra mã thông báo. Ví dụ

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

    hoặc 

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

    Gỡ lỗi

    Xem phần Khoá API hợp lệ không hoạt động.

    Ghi nhật ký

    Bạn có thể điều chỉnh cấp độ ghi nhật ký trên dịch vụ $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Tất cả nhật ký đều được gửi đến stdout và stderr.

    Phần tử Bắt buộc Mô tả
    -l, --log-level Các cấp độ hợp lệ: gỡ lỗi, thông tin, cảnh báo, lỗi. Điều chỉnh cấp độ ghi nhật ký. Mặc định: info
    -j, --json-log Phát ra đầu ra nhật ký dưới dạng các bản ghi JSON.

    Envoy cung cấp tính năng ghi nhật ký. Để biết thêm thông tin, hãy xem các đường liên kết sau đến tài liệu về Envoy:

    Sử dụng proxy mạng

    Bạn có thể chèn một proxy HTTP bằng cách sử dụng các biến môi trường HTTP_PROXY và HTTPS_PROXY trong môi trường của tệp nhị phân apigee-remote-service-envoy. Khi sử dụng các biến này, bạn cũng có thể dùng biến môi trường NO_PROXY để loại trừ các máy chủ lưu trữ cụ thể khỏi việc được gửi qua 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

    Hãy nhớ rằng bạn phải truy cập được vào proxy từ apigee-remote-service-envoy.

    Giới thiệu về các chỉ số và số liệu phân tích

    Điểm cuối chỉ số Prometheus có tại :5001/metrics. Bạn có thể định cấu hình số cổng này. Xem Tệp cấu hình.

    Số liệu phân tích của Envoy

    Các đường liên kết sau đây cung cấp thông tin về cách lấy dữ liệu phân tích của proxy Envoy:

    Số liệu phân tích Istio

    Các đường liên kết sau đây cung cấp thông tin về cách lấy dữ liệu phân tích của proxy Envoy:

    Số liệu phân tích của Apigee

    Apigee Remote Service for Envoy gửi số liệu thống kê về yêu cầu đến Apigee để xử lý số liệu phân tích. Apigee báo cáo những yêu cầu này theo tên Sản phẩm API được liên kết.

    Để biết thông tin về số liệu phân tích của Apigee, hãy xem bài viết Tổng quan về dịch vụ phân tích.

    Hỗ trợ môi trường nhiều người thuê

    Giờ đây, bạn có thể bật bộ chuyển đổi để phục vụ nhiều môi trường trong một tổ chức Apigee. Tính năng này cho phép bạn sử dụng một Trình kết nối Apigee cho Envoy được liên kết với một tổ chức Apigee để phục vụ nhiều môi trường. Trước khi có sự thay đổi này, một bộ chuyển đổi luôn được liên kết với một môi trường Apigee.

    Để định cấu hình chế độ hỗ trợ nhiều môi trường, hãy thay đổi giá trị của tenant:env_name thành * trong tệp config.yaml. Ví dụ:

    1. Mở tệp config.yaml trong một trình chỉnh sửa.
    2. Thay đổi giá trị của tenant.env_name thành *. Ví dụ: 
      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. Lưu tệp.
    4. Áp dụng tệp: 
      kubectl apply -f $CLI_HOME/config.yaml

    Khi định cấu hình chế độ nhiều môi trường, bạn cũng phải định cấu hình Envoy để gửi giá trị môi trường thích hợp đến bộ chuyển đổi bằng cách thêm siêu dữ liệu sau vào phần virtual_hosts:routes của tệp envoy-config.yaml. Ví dụ:

    1. Tạo tệp envoy-config.yaml bằng giao diện dòng lệnh. Ví dụ: 
      $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
    2. Mở tệp đã tạo (tệp này có tên là envoy-config.yaml).
    3. Thêm siêu dữ liệu sau vào phần virtual_host hoặc routes của tệp: 
      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

      Ví dụ sau đây minh hoạ cấu hình cho một virtual_host có nhiều tuyến được xác định, trong đó mỗi tuyến gửi lưu lượng truy cập đến một môi trường cụ thể: 

      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. Lặp lại bước cuối cùng để thêm các môi trường khác nếu cần.
    5. Lưu tệp và áp dụng tệp đó.

    Định cấu hình mTLS giữa bộ chuyển đổi và thời gian chạy Apigee

    Bạn có thể cung cấp chứng chỉ TLS phía máy khách trong phần tenant của tệp config.yaml của bộ chuyển đổi để sử dụng mTLS giữa bộ chuyển đổi và thời gian chạy Apigee. Thay đổi này áp dụng cho tất cả các nền tảng Apigee được hỗ trợ. Thao tác này cũng cho phép mTLS cho số liệu phân tích đối với nền tảng Apigee Edge cho Đám mây riêng. Ví dụ: 

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