Làm việc với bản đồ khóa giá trị

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

Đôi khi, bạn muốn lưu trữ dữ liệu để truy xuất trong thời gian chạy – dữ liệu không hết hạn mà không được mã hoá cứng trong logic của proxy API. Bảng khoá-giá trị (KVM) là lựa chọn lý tưởng cho việc này. KVM là một tập hợp tuỳ chỉnh gồm các cặp khoá/giá trị String được mã hoá hoặc không mã hoá. Dưới đây là hai ví dụ:

Để tìm hiểu về các loại tính năng duy trì khác, hãy xem phần Thêm tính năng lưu vào bộ nhớ đệm và duy trì.

Các trường hợp KVM

Sau đây là một số trường hợp mà KVM trở nên hữu ích:

  • Bạn có một proxy API cần gọi một URL mục tiêu (hoặc Lệnh gọi dịch vụ) trong môi trường kiểm thử và một URL mục tiêu khác trong môi trường sản xuất. Thay vì mã hoá cứng các URL trong proxy, bạn có thể để proxy phát hiện môi trường mà proxy đang hoạt động, thực thi chính sách Thao tác với bản đồ khoá-giá trị có liên quan và truy xuất URL mục tiêu chính xác từ một trong các KVM mà bạn đã tạo. Sau đó, nếu một hoặc cả hai mục tiêu của bạn thay đổi, bạn chỉ cần cập nhật KVM bằng các URL mới. Proxy sẽ nhận các giá trị mới và bạn không cần triển khai lại proxy.
  • Bạn muốn lưu trữ thông tin đăng nhập, khoá riêng tư hoặc mã thông báo – chẳng hạn như mã thông báo cho các dịch vụ bên ngoài, thông tin đăng nhập bắt buộc để tạo mã thông báo OAuth hoặc khoá riêng tư được dùng trong Lệnh gọi Java hoặc JavaScript để mã hoá hoặc ký JSON Web Token (JWT). Thay vì truyền thông tin đăng nhập, khoá hoặc mã thông báo trong yêu cầu hoặc mã hoá cứng các thông tin này trong logic proxy, bạn có thể lưu trữ chúng trong KVM (luôn được mã hoá) và truy xuất chúng một cách linh động trong các lệnh gọi đến những mục tiêu yêu cầu các thông tin này.

Bạn sẽ khám phá ra những trường hợp khác mà việc lưu trữ các cặp khoá/giá trị Chuỗi là hữu ích. Nhìn chung, hãy cân nhắc sử dụng KVM khi:

  • Các vị trí cụ thể trong mã của bạn yêu cầu các giá trị khác nhau trong thời gian chạy.
  • Bạn cần truyền dữ liệu nhạy cảm mà không cần mã hoá cứng.
  • Bạn muốn lưu trữ các giá trị không hết hạn như bộ nhớ đệm.

KVM có phạm vi

Phạm vi có nghĩa là "nơi có KVM". Bạn có thể tạo KVM ở các phạm vi sau: organization, environment và apiproxy.

Ví dụ: nếu chỉ có một proxy API yêu cầu dữ liệu trong KVM, bạn có thể tạo KVM ở phạm vi apiproxy, trong đó chỉ proxy API đó mới có thể truy cập vào dữ liệu.

Hoặc bạn có thể muốn tất cả các proxy API trong môi trường kiểm thử đều có quyền truy cập vào một bản đồ khoá giá trị. Trong trường hợp đó, bạn sẽ tạo một bản đồ khoá giá trị ở phạm vi môi trường. Các proxy được triển khai trong môi trường "prod" không thể truy cập vào KVM trong phạm vi môi trường "test". Nếu bạn muốn các khoá KVM tương tự có sẵn trong quá trình phát hành chính thức, hãy tạo một KVM song song có phạm vi là môi trường "prod".

Nếu bạn muốn tất cả các proxy trong mọi môi trường truy cập vào cùng một KVM, hãy tạo KVM ở phạm vi organization.

Giới thiệu về KVM được mã hoá

Các KVM được mã hoá sẽ được mã hoá bằng khoá mật mã AES-128 do Apigee tạo. Khoá dùng để mã hoá KVM được lưu trữ trong phạm vi của KVM. Ví dụ: trong một tổ chức, tất cả các KVM được mã hoá mà bạn tạo ở phạm vi môi trường đều được tạo bằng cùng một khoá có phạm vi môi trường.

Edge xử lý việc hiển thị các giá trị được mã hoá theo những cách sau. (Xem phần Quản lý và sử dụng KVM để biết thông tin về cách tạo KVM được mã hoá.)

Giao diện người dùng Edge

Các giá trị khoá được mã hoá sẽ hiển thị các giá trị được che bằng dấu hoa thị trong giao diện người dùng (*****). Ví dụ:

API Quản lý

Trong API quản lý, các giá trị được mã hoá sẽ được trả về dưới dạng giá trị che giấu. Sau đây là phản hồi mẫu của API quản lý cho lệnh gọi Get encrypted KVM:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Theo dõi và gỡ lỗi

Khi sử dụng chính sách Thao tác trên bản đồ khoá-giá trị để truy xuất các giá trị KVM đã mã hoá, bạn sẽ cung cấp tên của một biến để lưu trữ giá trị. Để nhận được một giá trị được mã hoá, bạn cần thêm tiền tố "private." vào tên biến. Thao tác này sẽ ngăn các khoá/giá trị KVM xuất hiện trong các phiên gỡ lỗi và theo dõi.

Giới hạn

Trong các tổ chức có bật Dịch vụ duy trì cốt lõi (CPS):

  • Tên/mã nhận dạng KVM có phân biệt chữ hoa chữ thường.
  • Kích thước khoá được giới hạn ở 2 KB.
  • Kích thước giá trị được giới hạn ở 10 KB.

Đối với Apigee Edge cho Đám mây riêng tư, mỗi KVM không được vượt quá 15 MB (đây là kích thước kết hợp của các khoá và giá trị). Nếu vượt quá giới hạn này, Apigee Edge cho Đám mây riêng tư sẽ trả về lỗi. Để xác định kích thước của KVM, bạn có thể sử dụng lệnh nodetool cfstats.

KVM lớn hơn có thể làm giảm hiệu suất. Do đó, bạn nên chia các KVM lớn, nguyên khối thành các KVM nhỏ hơn để cải thiện hiệu suất.

Quản lý và sử dụng KVM

Bạn có thể tạo, quản lý và sử dụng KVM theo nhiều cách. Phần này mô tả các lựa chọn khác nhau để tạo, sau đó truy xuất cả KVM được mã hoá và không được mã hoá.

Tạo và cập nhật KVM

Bạn có thể tạo và cập nhật KVM theo những cách sau:

  • Chính sách về các thao tác trên bản đồ khoá-giá trị (không mã hoá)

    Để tạo và cập nhật KVM trong thời gian chạy bằng các proxy API, hãy sử dụng chính sách Thao tác trên bản đồ khoá-giá trị. (Trong chính sách, bạn chỉ định tên của KVM trong thuộc tính mapIdentifier trên phần tử mẹ.)

    Phần tử <InitialEntries> cho phép bạn tạo và điền sẵn một nhóm mục nhập cơ sở trong KVM mới ngay khi bạn lưu chính sách trong giao diện người dùng hoặc triển khai proxy API (nếu bạn đã phát triển proxy này ở chế độ ngoại tuyến). Nếu các giá trị thay đổi trong chính sách, thì các giá trị hiện có sẽ bị ghi đè. Mọi khoá/giá trị mới sẽ được thêm vào KVM hiện có cùng với các khoá/giá trị hiện có.

    Phần tử <Put> sẽ tạo một KVM mới nếu chưa có và tạo một khoá có một hoặc nhiều giá trị. Nếu KVM đã tồn tại, thì các khoá/giá trị sẽ được thêm (hoặc cập nhật nếu khoá đã tồn tại). Bạn có thể dùng nhiều phần tử <Put> trong một chính sách KVM.

  • Management API

    API quản lý dùng để làm việc với KVM với tư cách là quản trị viên thay vì trong thời gian chạy trong các proxy API của bạn. Ví dụ: bạn có thể có một tập lệnh nội bộ sử dụng API quản lý để xoá và tạo lại KVM trong môi trường kiểm thử, hoặc bạn có thể muốn đặt lại giá trị của một khoá trong KVM để tất cả các proxy đều nhận được. (Để thao tác với KVM trong thời gian chạy, hãy sử dụng chính sách Thao tác với bản đồ khoá giá trị trong các proxy của bạn).

    API quản lý Bản đồ khoá/giá trị cho phép bạn tạo, cập nhật và xoá các KVM và khoá/giá trị được mã hoá ở tất cả các phạm vi (tổ chức, môi trường và apiproxy).

    Để tạo KVM được mã hoá bằng API quản lý, hãy thêm "encrypted" : "true" vào gói dữ liệu JSON. Bạn chỉ có thể mã hoá KVM khi tạo chúng. Bạn không thể mã hoá một KVM hiện có.

  • Giao diện người dùng quản lý

    Trong giao diện người dùng quản lý Edge, bạn có thể tạo và cập nhật các KVM theo phạm vi môi trường. Đây là phạm vi duy nhất của KVM xuất hiện trong giao diện người dùng. Giao diện người dùng quản lý là một cách hiệu quả để quản trị dữ liệu KVM theo cách thủ công cho các proxy API trong thời gian chạy. Hãy xem phần Tạo và chỉnh sửa bản đồ giá trị khoá môi trường để biết thêm thông tin.

Truy xuất KVM

Bạn truy xuất các bản đồ khoá-giá trị đã mã hoá và chưa mã hoá theo cùng một cách, chỉ có một chút khác biệt khi truy xuất bằng chính sách Thao tác trên bản đồ khoá-giá trị.

  • Chính sách: Sử dụng phần tử <Get> trong chính sách Thao tác trên bản đồ khoá-giá trị để truy xuất các KVM đã mã hoá và chưa mã hoá. Một điểm khác biệt nhỏ là truy xuất các giá trị đã mã hoá bằng chính sách, trong đó bạn phải thêm tiền tố "private." vào tên của biến sẽ chứa giá trị được truy xuất, như mô tả trong phần Thao tác nhận của chủ đề tham chiếu. Tiền tố đó sẽ ẩn giá trị khỏi các phiên gỡ lỗi và theo dõi trong khi bạn đang gỡ lỗi các proxy API.
  • Management API: Để quản lý hành chính, bạn có thể sử dụng Tạo và chỉnh sửa bản đồ giá trị khoá môi trường để nhận KVM và khoá/giá trị. Ví dụ: nếu bạn muốn sao lưu KVM bằng cách lấy và lưu trữ các định nghĩa JSON, hãy sử dụng API quản lý. Tuy nhiên, hãy lưu ý rằng các giá trị được mã hoá sẽ xuất hiện dưới dạng ***** trong phản hồi API.
  • Giao diện người dùng quản lý: Bạn có thể xem các KVM có phạm vi môi trường trong giao diện người dùng quản lý bằng cách chuyển đến API > Cấu hình môi trường > Key Value Maps (Classic Edge) hoặc Quản trị > Môi trường > Key Value Maps (New Edge).

Ví dụ về KVM

Để xem ví dụ về cách sử dụng KVM để điền các giá trị trong URL, hãy xem Templatize target URL with KVM by environment (Mẫu hoá URL đích bằng KVM theo môi trường).