Chính sách KeyValueMapOperations

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Nội dung

Cung cấp quyền truy cập dựa trên chính sách vào một cửa hàng Lưu trữ giá trị khoá (KVM) có trong Apigee Edge. Bạn có thể lưu trữ, truy xuất và xoá các cặp khoá/giá trị khỏi bản đồ hiện có đã đặt tên bằng cách định cấu hình các chính sách KeyValueMapOperations chỉ định các thao tác PUT, GET hoặc DELETE. (Chính sách phải thực hiện ít nhất một trong những thao tác này.)

Video

Hãy xem các video sau để tìm hiểu thêm về KVM.

Mẫu

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

{
    "entry" :[ 
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/> 
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter> 
      </Key>
   </Get>
</KeyValueMapOperations>

Tham chiếu phần tử

Tài liệu tham chiếu phần tử mô tả các phần tử và thuộc tính của chính sách KeyValueMapOperations:

<KeyValueMapOperations async="false" continueOnError="false" 
    enabled="true" name="Key-Value-Map-Operations-1" 
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

Các thuộc tính <KeyValueMapOperations>

Ví dụ sau đây cho thấy các thuộc tính trên thẻ <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

Bảng sau đây mô tả các thuộc tính dành riêng cho thẻ <KeyValueMapOperations>:

Bảng sau đây mô tả các thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Phần tử <DisplayName>

Sử dụng cùng với thuộc tính name để gắn nhãn cho chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên khác theo ngôn ngữ tự nhiên.

<DisplayName>Policy Display Name</DisplayName>

<Xoá> phần tử

Xoá cặp khoá/giá trị được chỉ định. Bạn phải sử dụng ít nhất một trong các thuộc tính <Get>, <Put> hoặc <Delete>.

Hãy nhớ chỉ định tên của KVM bằng thuộc tính mapIdentifier của phần tử mẹ. Ví dụ:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

Phần tử <Entry>

Các giá trị gốc cho bản đồ khoá-giá trị, được điền sẵn trong bản đồ khoá-giá trị khi khởi động.

Đối với Edge for Public Cloud, kích thước khoá tối đa là 2 KB. Ví dụ:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Phần tử <ExclusiveCache>

Không dùng nữa. Thay vào đó, hãy sử dụng phần tử <Scope>.

Phần tử <ExpiryTimeInSecs>

Chỉ định thời lượng tính bằng giây mà sau đó Edge làm mới giá trị đã lưu vào bộ nhớ đệm từ KVM được chỉ định.

Giá trị 0 hoặc -1 hoặc không bao gồm phần tử này có nghĩa là sử dụng giá trị mặc định là 300 giây. Ví dụ:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM là một cơ chế lưu trữ dài hạn, lưu trữ các khoá và giá trị trong cơ sở dữ liệu NoSQL. Do đó, việc đọc từ KVM trong thời gian chạy có thể làm chậm hiệu suất proxy. Để cải thiện hiệu suất, Edge có một cơ chế tích hợp để lưu các khoá/giá trị KVM vào bộ nhớ đệm trong bộ nhớ trong thời gian chạy. Chính sách Hoạt động KVM này luôn đọc từ bộ nhớ đệm cho các hoạt động GET.

Phần tử <ExpiryTimeInSecs> cho phép bạn kiểm soát thời gian lưu trữ các khoá/giá trị dùng trong chính sách trong bộ nhớ đệm trước khi làm mới lại từ KVM. Tuy nhiên, có một số điểm khác biệt giữa cách các thao tác GET và PUT ảnh hưởng đến thời hạn của bộ nhớ đệm.

GET – Lần đầu tiên thực thi thao tác GET của KVM, các khoá/giá trị yêu cầu từ KVM (có tên được chỉ định trong thuộc tính mapIdentifier gốc của chính sách) sẽ được tải vào bộ nhớ đệm, tại đây các khoá/giá trị này vẫn sẽ được dùng để thực hiện các thao tác GET tiếp theo cho đến khi một trong các trường hợp sau xảy ra:

• Số giây được chỉ định trong <ExpiryTimeInSecs> sẽ hết hạn.
  hoặc
• Thao tác PUT trong chính sách KVM sẽ ghi đè các giá trị hiện có (sẽ được giải thích trong phần tiếp theo).

PUT – Thao tác PUT ghi các khoá/giá trị vào KVM được chỉ định. Nếu PUT ghi vào một khoá đã tồn tại trong bộ nhớ đệm, thì bộ nhớ đệm đó sẽ được làm mới ngay lập tức và hiện giữ giá trị mới là số giây được chỉ định trong phần tử <ExpiryTimeInSecs> của chính sách.

Ví dụ: Lưu KVM vào bộ nhớ đệm

1. Thao tác GET sẽ truy xuất giá trị "xếp hạng", thao tác này sẽ thêm giá trị "10" vào bộ nhớ đệm. <ExpiryTimeInSecs> của chính sách này là 60.
2. 30 giây sau, chính sách GET sẽ thực thi lại và truy xuất "10" từ bộ nhớ đệm.
3. 5 giây sau, chính sách PUT cập nhật giá trị "xếp hạng" thành "8" và <ExpiryTimeInSecs> trong chính sách PUT là 20. Bộ nhớ đệm sẽ được làm mới ngay lập tức bằng giá trị mới. Giá trị này hiện được thiết lập để duy trì trong bộ nhớ đệm trong 20 giây. (Nếu thao tác PUT không xảy ra, thì bộ nhớ đệm ban đầu được điền bằng lệnh GET đầu tiên sẽ vẫn tồn tại thêm 30 giây nữa, còn lại so với 60 giây ban đầu.)
4. 15 giây sau, một GET khác sẽ thực thi và truy xuất giá trị là "8".

Phần tử <Get>

Truy xuất giá trị cho khoá đã chỉ định. Bạn phải sử dụng ít nhất một trong các thuộc tính <Get>, <Put> hoặc <Delete>.

Hãy nhớ chỉ định tên của KVM bằng thuộc tính mapIdentifier trên phần tử mẹ.

Bạn có thể đưa nhiều khối Get vào chính sách này để truy xuất nhiều mục từ một KVM.

Nhận một mặt hàng từ KVM

<Get assignTo="myvar" index="1">         
   <Key>             
      <Parameter>key_name_literal</Parameter>         
   </Key>     
</Get>

Nhận nhiều mục từ KVM

Trong ví dụ sau, giả sử một KVM có các khoá và giá trị sau. Ngoài việc lưu trữ danh sách đang chạy gồm các bộ phim phổ biến nhất mọi thời đại, KVM còn lưu trữ tên đạo diễn cho tất cả các bộ phim lớn.

Dưới đây là cấu hình chính sách KVM mà chúng tôi có thể sử dụng để truy xuất bộ phim phổ biến nhất hiện nay cùng tên đạo diễn của bộ phim đó:

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

Khi proxy API được gọi, Edge sẽ tạo các biến sau đây mà bạn có thể sử dụng trong quy trình proxy API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

Thuộc tính

Bảng sau đây mô tả các thuộc tính của phần tử <Get>:

<Get assignTo="private.myvar">

Phần tử <InitialEntries>

Các giá trị gốc cho bản đồ khoá giá trị, được điền sẵn trong bản đồ khoá-giá trị khi khởi tạo. Hãy nhớ chỉ định tên của KVM bằng thuộc tính mapIdentifier trên phần tử mẹ, ví dụ:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Khi sử dụng phần tử này, khi bạn lưu chính sách trong giao diện người dùng quản lý trên phiên bản proxy đã triển khai hoặc triển khai gói proxy API chứa chính sách bằng phần tử này, (các) khoá sẽ được tạo tự động trong KVM (dưới dạng không mã hoá). Nếu giá trị trong chính sách khác với giá trị trong KVM, thì các giá trị trong KVM sẽ bị ghi đè khi triển khai proxy. Mọi khoá/giá trị mới đều được thêm vào KVM hiện có cùng với các khoá/giá trị hiện có.

Khoá và giá trị được điền bởi phần tử này phải là giá trị cố định. Ví dụ: <Parameter ref="request.queryparam.key"> không được hỗ trợ trong phần tử này.

Kích thước khoá tối đa giới hạn ở 2 KB đối với cả Edge cho Đám mây công cộng và Edge cho Lưu trữ riêng tư. Giá trị KVM được giới hạn ở 2 KB.

Để tạo KVM đã mã hoá, hãy sử dụng API Quản lý bản đồ khoá/giá trị.

Phần tử <Key>

Chỉ định khoá trong một mục ánh xạ khoá/giá trị. Một khoá có thể là khoá kết hợp, nghĩa là bạn có thể thêm nhiều thông số để tạo khoá. Ví dụ: userID và role có thể được kết hợp để tạo ra một key. Ví dụ:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

Hãy nhớ xem phần tử <Parameter> để biết thông tin cụ thể về cách đặt tên khoá.

Đối với Edge for Public Cloud, kích thước khoá được giới hạn ở 2 KB. Hãy xem bài viết Điểm khác biệt giữa Edge for Public Cloud API và Private Cloud API để biết thêm thông tin.

Phần tử <Parameter>

Chỉ định khoá trong một cặp khoá/giá trị. Phần tử này chỉ định tên khi tạo, đặt, truy xuất hoặc xoá cặp khoá/giá trị.

Bạn có thể chỉ định tên bằng cách sử dụng:

• Một chuỗi giá trị cố định

  <Key>
    <Parameter>literal</Parameter>
  </Key>
  

• Một biến được truy xuất trong thời gian chạy, bằng cách sử dụng thuộc tính ref

  <Key>
    <Parameter ref="variable_name"/>
  </Key>
  

• Kết hợp giá trị cố định và tệp tham chiếu biến

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>
  

Khi Phần tử khoá bao gồm nhiều phần tử Tham số, chuỗi khoá hiệu quả là chuỗi nối các giá trị của mỗi tham số, kết hợp bằng dấu gạch dưới kép. Ví dụ: trong ví dụ trên, nếu biến apiproxy.name có giá trị "abc1", thì khoá hiệu quả sẽ là targeturl__abc1__weight.

Cho dù bạn đang lấy, cập nhật hay xoá một mục nhập khoá/giá trị, tên khoá phải khớp với tên của khoá trong bản đồ giá trị khoá. Hãy xem phần Chỉ định và truy xuất tên khoá để biết nguyên tắc.

Thuộc tính

Bảng sau đây mô tả các thuộc tính của phần tử <Parameter>:

Phần tử <Put>

Ghi một cặp khoá/giá trị vào bản đồ khoá-giá trị, cho dù bản đồ khoá-giá trị đã được mã hoá hay chưa được mã hoá. Nếu bản đồ giá trị khoá được chỉ định trong thuộc tính mapIdentifier trên phần tử mẹ không tồn tại, thì bản đồ sẽ tự động được tạo (dưới dạng không mã hoá). Nếu bản đồ khoá-giá trị đã tồn tại, thì khoá/giá trị sẽ được thêm vào.

Để tạo bản đồ khoá giá trị đã mã hoá, hãy sử dụng API Quản lý bản đồ khoá/giá trị; hoặc xem bài viết Tạo và chỉnh sửa bản đồ giá trị khoá môi trường để tạo KVM trong phạm vi môi trường đã mã hoá trong giao diện người dùng.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>

Thuộc tính

Bảng sau đây mô tả các thuộc tính của phần tử <Put>:

Phần tử <Scope>

Xác định ranh giới hỗ trợ tiếp cận cho bản đồ khoá-giá trị. Phạm vi mặc định là environment, nghĩa là theo mặc định, các mục ánh xạ sẽ được chia sẻ bởi tất cả các proxy API đang chạy trong một môi trường (ví dụ: kiểm thử hoặc sản phẩm). Nếu bạn đặt phạm vi thành apiproxy, thì các mục trong bản đồ khoá-giá trị chỉ truy cập được bằng proxy API ghi giá trị vào bản đồ.

Xin lưu ý rằng khi truy cập vào một mục trong bản đồ hoặc bản đồ, bạn phải chỉ định cùng một giá trị phạm vi mà bạn đã sử dụng khi tạo bản đồ. Ví dụ: nếu bản đồ được tạo với phạm vi apiproxy, bạn phải sử dụng phạm vi apiproxy khi truy xuất các giá trị của phạm vi đó, thay đổi hoặc xoá các mục nhập.

<Scope>environment</Scope>

Phần tử <Giá trị>

Chỉ định giá trị của khoá. Bạn có thể chỉ định giá trị dưới dạng một chuỗi giá trị cố định hoặc sử dụng thuộc tính ref làm biến cần được truy xuất trong thời gian chạy:

<!-- Specify a literal value -->
<Value>literal<Value>

hoặc:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

Bạn cũng có thể bao gồm nhiều phần tử <Value> để chỉ định một giá trị nhiều phần. Các giá trị được kết hợp trong thời gian chạy.

Trong ví dụ sau, hai khoá được thêm vào KVM:

• Khoá k1 với giá trị v1,v2
• Khoá k2 với giá trị v3,v4

<InitialEntries>         
   <Entry>             
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>     
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Trong ví dụ sau, một khoá được tạo với hai giá trị. Giả sử tên tổ chức là foo_org, tên proxy API là bar và môi trường là test:

• Khoá foo_org với giá trị bar,test

<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>

Thuộc tính

Bảng sau đây mô tả các thuộc tính của phần tử <Value>:

Tham chiếu lỗi

Lỗi được trả về từ chính sách Edge theo một định dạng nhất quán như mô tả trong Tài liệu tham khảo mã lỗi.

Phần này mô tả các mã lỗi và thông báo lỗi được trả về, cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách này.

Giản đồ

Lưu ý về cách sử dụng

Để biết thông tin tổng quan về bản đồ khoá-giá trị, hãy xem bài viết Làm việc với bản đồ khoá-giá trị.

Kho lưu trữ bản đồ giá trị khoá cung cấp một cơ chế lưu trữ gọn nhẹ cho dữ liệu được định dạng dưới dạng cặp khoá/giá trị. Bạn có thể truy cập các tập hợp này trong thời gian chạy thông qua chính sách hoặc mã. Bản đồ chứa mọi dữ liệu tuỳ ý ở định dạng key=value.

Ví dụ: localhost=127.0.0.1, zip_code=94110 hoặc first_name=felix. Trong ví dụ đầu tiên, localhost là một khoá và 127.0.0.1 là một giá trị. Mỗi cặp khoá/giá trị được lưu trữ dưới dạng một mục trong bản đồ khoá-giá trị. Bản đồ khoá-giá trị có thể lưu trữ nhiều mục nhập.

Sau đây là một ví dụ về cách sử dụng bản đồ khoá-giá trị. Giả sử bạn cần lưu trữ danh sách địa chỉ IP liên kết với nhiều môi trường phụ trợ. Bạn có thể tạo bản đồ khoá giá trị có tên ipAddresses chứa danh sách các cặp khoá/giá trị dưới dạng mục nhập. Ví dụ: JSON này có thể biểu thị một bản đồ như vậy:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Bạn có thể dùng cấu trúc này để tạo một kho lưu trữ địa chỉ IP mà các chính sách có thể sử dụng trong thời gian chạy để thực thi việc đưa IP vào danh sách cho phép hoặc từ chối, để chọn linh động một địa chỉ đích phụ trợ, v.v. Thông thường, chính sách KeyValueMapOperations được dùng để lưu trữ hoặc truy xuất thông tin dài hạn cần được sử dụng lại trong nhiều giao dịch yêu cầu/phản hồi.

Bạn có thể điều khiển sơ đồ khoá/giá trị thông qua chính sách KeyValueMapOperations hoặc trực tiếp thông qua API quản lý Apigee Edge. Hãy tham khảo tài liệu tham khảo API quản lý để biết thông tin chi tiết về API API bản đồ khoá/giá trị của tổ chức. Ví dụ: bạn có thể sử dụng API để tải các tập dữ liệu lớn lên kho khoá/giá trị hoặc tạo tập lệnh để quản lý các mục ánh xạ khoá/giá trị. Bạn sẽ cần tạo bản đồ khoá/giá trị bằng API trước khi truy cập vào API đó bằng chính sách KeyValueMapOperations.

Chỉ định và truy xuất tên khoá

Với các phần tử <Parameter> và <Value>, bạn có thể chỉ định một giá trị cố định (trong đó giá trị nằm giữa thẻ mở và thẻ đóng) hoặc sử dụng thuộc tính ref để chỉ định tên của một biến có giá trị nên được sử dụng trong thời gian chạy.

Phần tử Tham số xứng đáng được đề cập đặc biệt, vì phần tử này xác định tên của khoá được tạo, cũng như tên khoá mà bạn muốn truy xuất hoặc xoá. Sau đây là hai ví dụ. Phương thức đầu tiên chỉ định tên khoá theo nghĩa đen và phương thức thứ hai chỉ định tên khoá bằng một biến. Giả sử những phương thức sau đây được dùng để tạo khoá trong KVM:

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

Trong trường hợp đầu tiên, giá trị cố định của "key_name_literal" được lưu trữ trong KVM dưới dạng tên khoá. Trong trường hợp thứ hai, bất kỳ giá trị nào trong key.name.variable sẽ trở thành tên của khoá trong KVM. Ví dụ: nếu key.name.variable chứa giá trị foo, thì khoá sẽ có tên là "foo".

Khi bạn muốn truy xuất khoá và giá trị khoá bằng thao tác GET (hoặc xoá bằng thao tác DELETE), chế độ cài đặt <Parameter> cần phải khớp với tên khoá trong KVM. Ví dụ: nếu tên khoá trong KVM là "foo", bạn có thể chỉ định giá trị cố định bằng <Parameter>foo</Parameter> hoặc chỉ định một biến chứa giá trị chính xác "foo", như sau: <Parameter ref="variable.containing.foo"/>.

Chủ đề có liên quan

• API bản đồ khoá/giá trị của tổ chức