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

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về 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 proxy API. Bản đồ giá trị khoá (KVM) là lựa chọn lý tưởng trong trường hợp này. KVM là một tập hợp tuỳ chỉnh các cặp Chuỗi khoá/giá trị được mã hoá hoặc chưa mã hoá. Sau đây là hai ví dụ:

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

Các trường hợp KVM

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

  • Bạn có một proxy API cần gọi một URL mục tiêu (hoặc Chú thích dịch vụ) trong môi trường thử nghiệm và một URL mục tiêu khác trong môi trường thực tế. Thay vì các URL mã hoá cứng trong proxy, bạn có thể để proxy phát hiện môi trường đang chứa proxy, thực thi chính sách Hoạt động bản đồ giá trị khoá có liên quan và truy xuất URL mục tiêu chính xác từ một trong các KVM bạn đã tạo. Sau đó, nếu một hoặc cả hai mục tiêu 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à 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 – như mã thông báo cho dịch vụ bên ngoài, thông tin xác thực cần thiết để tạo mã thông báo OAuth hoặc khoá riêng tư được dùng trong Chú thích Java hoặc JavaScript để mã hoá hoặc chữ ký Mã thông báo web JSON (JWT). Thay vì chuyển thông tin xác thực, khoá hoặc mã thông báo trong yêu cầu hay mã hoá cứng chúng trong logic proxy, bạn có thể lưu trữ chúng trong một KVM (luôn được mã hoá) và tự động truy xuất chúng trong các lệnh gọi đến mục tiêu yêu cầu.

Bạn sẽ tìm hiểu các trường hợp khác mà việc lưu trữ cặp chuỗi khoá/giá trị sẽ 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.
  • Dữ liệu nhạy cảm cần được truyền mà không mã hoá cứng dữ liệu đó.
  • 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, environmentapiproxy.

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

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

Nếu bạn muốn tất cả proxy trong mọi môi trường đều 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 đã mã hoá sẽ được mã hoá bằng khoá mật mã AES-128 do Apigee tạo ra. 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ả KVM đã 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á trong 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 bài viết 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

Bản đồ giá trị khoá được mã hoá hiển thị các giá trị được ẩn giấu 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ị đã mã hoá được trả về và che giấu. Sau đây là phản hồi của API quản lý mẫu cho lệnh gọi Nhận KVM được mã hoá:

{
  "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 Hoạt động bản đồ giá trị khoá để truy xuất các giá trị KVM đã mã hoá, bạn cần cung cấp tên của biến để lưu trữ giá trị đó. Để nhận giá trị đã mã hoá, bạn cần thêm tiền tố "private." vào tên biến. Việc này sẽ ngăn khoá/giá trị KVM xuất hiện trong các phiên Theo dõi và gỡ lỗi.

Các giới hạn

Trong những tổ chức đã bật Dịch vụ lưu trữ cố định cốt lõi (CPS):

  • Tên/giá trị 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 dành cho đám mây riêng tư, mỗi KVM không được vượt quá 15 MB (đây là kích thước tổng hợp của các khoá và giá trị). Nếu bạn vượt quá giới hạn này, Apigee Edge for Private Cloud sẽ trả về một lỗi. Để xác định kích thước của KVM, bạn có thể sử dụng lệnh nodetoolcfstats.

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 tuỳ chọn để tạo, sau đó truy xuất cả KVM đã mã hoá và chưa 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ề hoạt động của bản đồ giá trị khoá (không mã hoá)

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

    Phần tử <InitialEntries> cho phép bạn tạo và điền sẵn một nhóm các mục nhập cơ sở trong một 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 ngoại tuyến). Nếu các giá trị trong chính sách thay đổi, 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ó, đồng thời tạo một khoá có ít nhất một giá trị. Nếu KVM đã tồn tại, thì các khoá/giá trị sẽ được thêm (hoặc được cập nhật nếu khoá đã tồn tại). Bạn có thể sử dụng nhiều phần tử <Put> trong một chính sách KVM.

  • API Quản lý

    API quản lý dùng để làm việc với KVM với tư cách quản trị viên thay vì trong thời gian chạy trong proxy API. 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 thử nghiệm, hoặc bạn có thể muốn đặt lại giá trị của một khoá trong KVM cho tất cả proxy để nhận. (Để biết các thao tác trong thời gian chạy của KVM, hãy sử dụng Chính sách về hoạt động của bản đồ giá trị khoá trong 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á KVM đã mã hoá cũng như khoá/giá trị ở tất cả các phạm vi (tổ chức, môi trường và api proxy).

    Để tạo KVM được mã hoá bằng API quản lý, hãy thêm "encrypted" : "true" vào tải trọng JSON. Bạn chỉ có thể mã hoá KVM khi tạo chúng. Bạn không thể mã hoá 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 trong 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 hay để quản lý dữ liệu KVM theo cách thủ công cho các proxy API trong thời gian chạy. Hãy xem bài viết 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 giá trị khoá đã mã hoá và chưa mã hoá sẽ ánh xạ theo cách tương tự, với một biến thể nhỏ khi truy xuất bằng chính sách về Hoạt động bản đồ giá trị khoá.

  • Chính sách: Sử dụng phần tử <Get> trong Chính sách về hoạt động của bản đồ giá trị khoá để truy xuất các KVM đã mã hoá và chưa mã hoá. Một điểm khác biệt nhỏ là việc truy xuất các giá trị đã mã hoá bằng chính sách này, 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ư được mô tả trong phần Nhận thao tác của chủ đề tham chiếu. Tiền tố đó sẽ ẩn giá trị khỏi các phiên Theo dõi và gỡ lỗi trong khi bạn gỡ lỗi proxy API.
  • API Quản lý: Đối với mục đích quản lý quản trị, bạn có thể sử dụng tính năng Tạo và chỉnh sửa bản đồ giá trị khoá môi trường để tải 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ị đã mã hoá sẽ hiển thị dưới dạng ***** trong phản hồi của API.
  • Giao diện người dùng quản lý: Bạn có thể xem các KVM trong 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 > Bản đồ giá trị khoá ( Edge cũ) hoặc Quản trị > Môi trường > Bản đồ giá trị khoá (New Edge).

Ví dụ về KVM

Để xem ví dụ về cách sử dụng KVM để điền các giá trị trong một URL, hãy tham khảo tại https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html.