Hướng Dẫn Sử Dụng APISIX Dashboard: Tích hợp và Quản lý API

Hướng dẫn người dùng

Dưới đây là một phần mô tả các thành phần chính của giao diện quản lý APISIX Dashboard.

Bảng điều khiển

Chúng tôi hỗ trợ các trang giám sát bằng cách nhúng thông qua iframe. Truy cập Grafana trước, vui lòng bật tùy chọn allow_embedding=true (mặc định là false). Do chính sách bảo mật, trình duyệt có thể không hiển thị đúng các trang Grafana.

Định tuyến (Routes)

Module Routes cho phép điều khiển định tuyến thông qua giao diện người dùng thay vì gọi API.

Danh sách

Xem danh sách các định tuyến đã được cấu hình.

Tạo mới

Thêm các định tuyến mới vào hệ thống.

Cài đặt

Cấu hình các tùy chọn nâng cao cho định tuyến.

Khôi phục cấu hình từ OpenAPI

Tổng quan

Quy chuẩn OpenAPI (OAS) định nghĩa một giao diện chuẩn độc lập với ngôn ngữ cho RESTful API, cho phép cả người và máy tính khám phá và hiểu chức năng của dịch vụ mà không cần truy cập mã nguồn, tài liệu hoặc kiểm tra lưu lượng mạng.

APISIX Dashboard hỗ trợ nhập tệp OpenAPI 3.0 (gọi tắt là OAS3.0), hỗ trợ cả định dạng json và yaml để tạo một hoặc nhiều định tuyến. Hiện tại chúng tôi hỗ trợ phần lớn quy chuẩn OpenAPI, nhưng vẫn có một số khác biệt về khả năng tương thích và các trường mở rộng.

Trường mở rộng

Một số trường trong APISIX Route là bắt buộc nhưng không có thuộc tính tương ứng trong OAS3.0. Để tiện lợi cho việc mở rộng thực thể định tuyến dựa trên OAS3.0, chúng tôi đã thêm một số trường mở rộng như upstream, plugins, host, v.v. Tất cả các trường mở rộng đều bắt đầu bằng tiền tố x-apisix.

Trường mở rộng	Thuộc tính APISIX Route
x-apisix-plugins	plugins
x-apisix-script	script
x-apisix-upstream	upstream
x-apisix-host	host
x-apisix-hosts	hosts
x-apisix-remote_addr	remote_addr
x-apisix-priority	priority
x-apisix-vars	vars
x-apisix-filter_func	filter_func
x-apisix-labels	labels
x-apisix-enable_websocket	enable_websocket
x-apisix-status	status
x-apisix-service_id	service_id
x-apisix-upstream_id	upstream_id

Lưu ý rằng chúng tôi chỉ mở rộng các trường cấp một, các trường con vẫn giữ nguyên. Ví dụ với x-apisix-upstream:

...
# Chúng tôi thêm x-apisix-upstream làm trường mở rộng trong OAS3.0 để đại diện cho upstream
x-apisix-upstream:
  # Các trường con của x-apisix-upstream vẫn giữ nguyên với các trường của upstream
  type: roundrobin
  nodes:
    - host: 172.16.238.20
      port: 1980
      weight: 1
...

Để biết thêm chi tiết về thuộc tính APISIX Route, vui lòng tham khảo tài liệu chính thức.

Khả năng tương thích OAS3.0

Khi nhập định tuyến từ OAS3.0, một số trường trong OAS3.0 có thể bị bỏ qua do APISIX Route không có trường tương ứng:

Thông tin chung API: Dùng để mô tả thông tin chung về API của bạn. Đôi khi, một tệp OAS3.0 chứa một loạt API thuộc ứng dụng, do đó thông tin này khác với tên và các thông tin cơ bản khác của API.
API server và đường dẫn cơ sở: upstream url + url prefix (tùy chọn)
Tham số đường dẫn (Path params): Các tham số API được mô tả trong đường dẫn.
Tham số truy vấn (Query params): Các tham số API được mô tả trong truy vấn.
Mô tả phản hồi và liên kết (Responses description and links): Định nghĩa phản hồi của thao tác API.

Ví dụ cấu hình OAS3.0 cho các tình huống sử dụng khác nhau

Định tuyến cơ bản

Lưu ý: Định tuyến được nhập mặc định có status là unpublished, không thể truy cập. Để nhập định tuyến published, cần thêm x-apisix-status: 1 vào tệp OAS3.0 của bạn

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: Mô tả thử nghiệm
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: Tiêu đề thử nghiệm
paths:
  /xin_chao: # uri định tuyến
    get: # phương thức định tuyến
      description: Xin chào thế giới. # mô tả định tuyến
      operationId: xin_chao # tên định tuyến
      x-apisix-upstream: # upstream định tuyến
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-status: 1 # định tuyến sẽ được xuất bản sau khi nhập
      responses:
        '200':
          description: phản hồi danh sách
        default:
          description: lỗi không mong đợi

Định tuyến sử dụng plugin

Lưu ý: Hầu hết các plugin đều được hỗ trợ qua trường mở rộng x-apisix-plugins

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: Mô tả thử nghiệm
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: Tiêu đề thử nghiệm
paths:
  /xin_chao:
    get:
      description: Xin chào thế giới.
      operationId: xin_chao
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-plugins:
        limit-count:
          count: 2
          time_window: 60
          rejected_code: 503
          key: remote_addr
          policy: local
      responses:
        '200':
          description: phản hồi danh sách
        default:
          description: lỗi không mong đợi

Định tuyến với xác thực tham số

Lưu ý: Đối với plugin request-validation, chúng tôi sẽ sử dụng parameter serialization cho xác thực tham số header và description request body cho xác thực tham số body trong OAS3.0

openapi: 3.0.0
info:
  version: "1"
  description: |-
    Mô tả thử nghiệm
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    Tiêu đề thử nghiệm
paths:
  /xin_chao:
    post:
      description: |-
        Xin chào thế giới.
      operationId: xin_chao
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      parameters:
        - name: id
          in: header
          description: ID của pet cần sử dụng
          required: true
          schema:
            type: string
          style: simple

      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              properties:
                name:
                  description: Cập nhật tên pet
                  type: string
                status:
                  description: Trạng thái cập nhật của pet
                  type: string
              required:
                - status
      responses:
        200:
          description: phản hồi danh sách
        default:
          description: lỗi không mong đợi

Định tuyến sử dụng plugin xác thực

Lưu ý: Đối với plugin basic-auth, jwt-auth và key-auth, chúng tôi sẽ sử dụng Authentication trong OAS3.0

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
openapi: 3.0.0
info:
  version: "1"
  description: |-
    Mô tả thử nghiệm
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    Tiêu đề thử nghiệm
paths:
  /xin_chao:
    post:
      description: |-
        Xin chào thế giới.
      operationId: xin_chao
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      security:
        - basicAuth: []
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        200:
          description: phản hồi danh sách
        default:
          description: lỗi không mong đợi

Định tuyến sử dụng dịch vụ hoặc upstream đã tồn tại

Lưu ý: Nếu service_id hoặc upstream_id không tồn tại trong APISIX, nhập định tuyến từ tệp cấu hình sẽ gây lỗi

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: Mô tả thử nghiệm
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: Tiêu đề thử nghiệm
paths:
  /xin_chao:
    get:
      description: Xin chào thế giới.
      operationId: xin_chao
      x-apisix-service_id: dich_vu_1
      responses:
        '200':
          description: phản hồi danh sách
        default:
          description: lỗi không mong đợi

Định tuyến đa đường dẫn

info:
  title: RoutesExport
  version: 3.0.0
openapi: 3.0.0
paths:
  /lay:
    delete:
      operationId: api1Xoa
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
    get:
      operationId: api1Lay
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
  /dang:
    post:
      operationId: test_dang
      requestBody: {}
      responses:
        default:
          description: ''
      security: []
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v1
        version: v1
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []

Tài liệu API quản lý

Manager API trực tiếp thao tác với ETCD và cung cấp quản lý dữ liệu cho Apache APISIX, cung cấp API cho giao diện người dùng hoặc các client khác.

Giấy phép: Apache License 2.0

/apisix/admin/migrate/export

GET

Mô tả

Xuất tệp cấu hình để di chuyển

Tham số

Không có.

Trả về

Một tệp để tải xuống.

/apisix/admin/migrate/import

POST

Mô tả

Nhập tệp cấu hình để khôi phục cấu hình

Tham số (FORM)

Tên	Vị trí	Mô tả	Bắt buộc	Schema
mode	body(form)	chế độ nhập (return, skip hoặc overwrite)	Có	string
file	body(form)	tệp để tải lên	Có	string

Trả về

Mã	Mô tả	Schema
0	nhập thành công	ApiError
20001	Mâu thuẫn cấu hình	ApiError

/apisix/admin/check_ssl_cert

POST

Mô tả

Xác thực chứng chỉ và khóa SSL

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
cert	body	chứng chỉ SSL	Có	string
key	body	khóa SSL	Có	string

Trả về

Mã	Mô tả	Schema
0	Xác thực SSL thành công	ApiError
default	lỗi không mong đợi	ApiError

/apisix/admin/check_ssl_exists

POST

Mô tả

Kiểm tra SSL có tồn tại không

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
cert	body	chứng chỉ SSL	Có	string
key	body	khóa SSL	Có	string

Trả về

Mã	Mô tả	Schema
0	SSL tồn tại	ApiError
default	lỗi không mong đợi	ApiError

/apisix/admin/consumers

GET

Mô tả

Trả về danh sách người tiêu dùng dựa trên số trang và kích thước trang, có thể tìm kiếm người tiêu dùng theo tên người dùng.

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
page	query	số trang	Không	integer
page_size	query	kích thước trang	Không	integer
username	query	tên người dùng của người tiêu dùng	Không	string

Trả về

Mã	Mô tả	Schema
0	phản hồi danh sách	[consumer]
default	lỗi không mong đợi	ApiError

/apisix/admin/notexist/routes

GET

Mô tả

Kiểm tra định tuyến có tồn tại hay không qua tên và loại trừ ID

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
name	query	tên định tuyến	Không	string
exclude	query	ID định tuyến loại trừ kiểm tra	Không	string

Trả về

Mã	Mô tả	Schema
0	định tuyến không tồn tại	ApiError
default	lỗi không mong đợi	ApiError

/apisix/admin/routes

GET

Mô tả

Trả về danh sách định tuyến dựa trên số trang và kích thước trang, có thể tìm kiếm định tuyến theo tên và uri

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
page	query	số trang	Không	integer
page_size	query	kích thước trang	Không	integer
name	query	tên định tuyến	Không	string
uri	query	uri định tuyến	Không	string
label	query	nhãn định tuyến	Không	string

Trả về

Mã	Mô tả	Schema
0	phản hồi danh sách	[route]
default	lỗi không mong đợi	ApiError

/apisix/admin/services

GET

Mô tả

Trả về danh sách dịch vụ dựa trên số trang và kích thước trang, có thể tìm kiếm dịch vụ theo tên

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
page	query	số trang	Không	integer
page_size	query	kích thước trang	Không	integer
name	query	tên dịch vụ	Không	string

Trả về

Mã	Mô tả	Schema
0	phản hồi danh sách	[service]
default	lỗi không mong đợi	ApiError

/apisix/admin/ssl

GET

Mô tả

Trả về danh sách SSL dựa trên số trang và kích thước trang, có thể tìm kiếm SSL theo sni

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
page	query	số trang	Không	integer
page_size	query	kích thước trang	Không	integer
sni	query	sni của SSL	Không	string

Trả về

Mã	Mô tả	Schema
0	phản hồi danh sách	[ssl]
default	lỗi không mong đợi	ApiError

/apisix/admin/upstreams

GET

Mô tả

Trả về danh sách upstream dựa trên số trang và kích thước trang, có thể tìm kiếm upstream theo tên

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
page	query	số trang	Không	integer
page_size	query	kích thước trang	Không	integer
name	query	tên upstream	Không	string

Trả về

Mã	Mô tả	Schema
0	phản hồi danh sách	[upstream]
default	lỗi không mong đợi	ApiError

/apisix/admin/user/login

POST

Mô tả

Đăng nhập người dùng

Tham số

Tên	Vị trí	Mô tả	Bắt buộc	Schema
username	body	tên người dùng	Có	string
password	body	mật khẩu	Có	string

Trả về

Mã	Mô tả	Schema
0	đăng nhập thành công	ApiError
default	lỗi không mong đợi	ApiError

Mô hình dữ liệu

ApiError

Tên	Loại	Mô tả	Bắt buộc
code	long	mã phản hồi	Không
message	string	thông điệp phản hồi	Không

BaseInfo

Tên	Loại	Mô tả	Bắt buộc
create_time	long	thời gian tạo	Không
id	object	định danh	Không
update_time	long	thời gian cập nhật	Không

Consumer

Tên	Loại	Mô tả	Bắt buộc
create_time	long	thời gian tạo	Không
desc	string	mô tả	Không
id	object	định danh	Không
labels	object	nhãn	Không
plugins	object	plugin	Không
update_time	long	thời gian cập nhật	Không
username	string	tên người dùng	Không

LoginInput

Tên	Loại	Mô tả	Bắt buộc
password	string	mật khẩu	Không
username	string	tên người dùng	Không

Route

Tên	Loại	Mô tả	Bắt buộc
create_time	long	thời gian tạo	Không
desc	string	mô tả	Không
enable_websocket	boolean	bật websocket	Không
filter_func	string	hàm lọc	Không
host	string	chủ nhà	Không
hosts	[string]	danh sách chủ nhà	Không
id	object	định danh	Không
labels	object	nhãn	Không
methods	[string]	phương thức	Không
name	string	tên	Không
plugins	object	plugin	Không
priority	long	ưu tiên	Không
remote_addr	string	địa chỉ từ xa	Không
remote_addrs	[string]	danh sách địa chỉ từ xa	Không
script	object	script	Không
service_id	object	định danh dịch vụ	Không
service_protocol	string	giao thức dịch vụ	Không
update_time	long	thời gian cập nhật	Không
upstream	UpstreamDef	upstream	Không
upstream_id	object	định danh upstream	Không
uri	string	đường dẫn	Không
uris	[string]	danh sách đường dẫn	Không
vars	object	biến	Không

SSL

Tên	Loại	Mô tả	Bắt buộc
cert	string	chứng chỉ	Không
certs	[string]	danh sách chứng chỉ	Không
create_time	long	thời gian tạo	Không
exptime	long	thời gian hết hạn	Không
id	object	định danh	Không
key	string	khóa	Không
keys	[string]	danh sách khóa	Không
labels	object	nhãn	Không
sni	string	server name indication	Không
snis	[string]	danh sách server name indication	Không
status	long	trạng thái	Không
update_time	long	thời gian cập nhật	Không
validity_end	long	thời gian kết thúc hiệu lực	Không
validity_start	long	thời gian bắt đầu hiệu lực	Không

Service

Tên	Loại	Mô tả	Bắt buộc
create_time	long	thời gian tạo	Không
desc	string	mô tả	Không
enable_websocket	boolean	bật websocket	Không
id	object	định danh	Không
labels	object	nhãn	Không
name	string	tên	Không
plugins	object	plugin	Không
script	string	script	Không
update_time	long	thời gian cập nhật	Không
upstream	UpstreamDef	upstream	Không
upstream_id	object	định danh upstream	Không

Upstream

Tên	Loại	Mô tả	Bắt buộc
checks	object	kiểm tra	Không
create_time	long	thời gian tạo	Không
desc	string	mô tả	Không
hash_on	string	hash trên	Không
id	object	định danh	Không
k8s_deployment_info	object	thông tin triển khai kubernetes	Không
key	string	khóa	Không
labels	object	nhãn	Không
name	string	tên	Không
nodes	object	nút	Không
pass_host	string	chuyển tiếp host	Không
retries	long	số lần thử lại	Không
service_name	string	tên dịch vụ	Không
timeout	object	thời gian chờ	Không
type	string	loại	Không
update_time	long	thời gian cập nhật	Không
upstream_host	string	chủ nhà upstream	Không

UpstreamDef

Tên	Loại	Mô tả	Bắt buộc
checks	object	kiểm tra	Không
desc	string	mô tả	Không
hash_on	string	hash trên	Không
k8s_deployment_info	object	thông tin triển khai kubernetes	Không
key	string	khóa	Không
labels	object	nhãn	Không
name	string	tên	Không
nodes	object	nút	Không
pass_host	string	chuyển tiếp host	Không
retries	long	số lần thử lại	Không
service_name	string	tên dịch vụ	Không
timeout	object	thời gian chờ	Không
type	string	loại	Không
upstream_host	string	chủ nhà upstream	Không

Thẻ: APISIX dashboard OpenAPI API Gateway Route Management

Đăng vào ngày 13 tháng 6 lúc 16:23

Thành phố Cuồng loạn

Hướng Dẫn Sử Dụng APISIX Dashboard: Tích hợp và Quản lý API

Hướng dẫn người dùng

Bảng điều khiển

Định tuyến (Routes)

Danh sách

Tạo mới

Cài đặt

Khôi phục cấu hình từ OpenAPI

Tổng quan

Trường mở rộng

Khả năng tương thích OAS3.0

Ví dụ cấu hình OAS3.0 cho các tình huống sử dụng khác nhau

Định tuyến cơ bản

Định tuyến sử dụng plugin

Định tuyến với xác thực tham số

Định tuyến sử dụng plugin xác thực

Định tuyến sử dụng dịch vụ hoặc upstream đã tồn tại

Định tuyến đa đường dẫn

Tài liệu API quản lý

/apisix/admin/migrate/export

GET

Mô tả

Tham số

Trả về

/apisix/admin/migrate/import

POST

Mô tả

Tham số (FORM)

Trả về

/apisix/admin/check_ssl_cert

POST

Mô tả

Tham số

Trả về

/apisix/admin/check_ssl_exists

POST

Mô tả

Tham số

Trả về

/apisix/admin/consumers

GET

Mô tả

Tham số

Trả về

/apisix/admin/notexist/routes

GET

Mô tả

Tham số

Trả về

/apisix/admin/routes

GET

Mô tả

Tham số

Trả về

/apisix/admin/services

GET

Mô tả

Tham số

Trả về

/apisix/admin/ssl

GET

Mô tả

Tham số

Trả về

/apisix/admin/upstreams

GET

Mô tả

Tham số

Trả về

/apisix/admin/user/login

POST

Mô tả

Tham số

Trả về

Mô hình dữ liệu

ApiError

BaseInfo

Consumer

LoginInput