Chính sách KeyValueMapOperations

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

Nội dung

Cung cấp quyền truy cập dựa trên chính sách vào một kho lưu trữ Key Value Map (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 các bản đồ hiện có đượ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 các thao tác này.)

Video

Hãy xem các video sau đây để 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>

Tài liệu tham khảo về phần tử

Tài liệu tham khảo về 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>

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ả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

&lt;DisplayName&gt; phần tử

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

<DisplayName>Policy Display Name</DisplayName>

Phần tử <Delete>

Xoá cặp khoá/giá trị đã chỉ định. Bạn phải sử dụng ít nhất một trong các giá trị <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ẹ. Ví dụ:

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

Phần tử <Entry>

Giá trị ban đầu cho các bản đồ khoá-giá trị. Các giá trị này được điền sẵn trong bản đồ khoá-giá trị khi bản đồ được khởi tạo.

Đối với Edge cho Đám mây công cộng, kích thước khoá được giới hạn ở 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 dùng phần tử <Scope>.

Phần tử <ExpiryTimeInSecs>

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

Giá trị 0 hoặc -1, hoặc loại trừ phần tử này, có nghĩa là giá trị mặc định là 300 giây sẽ được sử dụng. Ví dụ:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM là một cơ chế duy trì lâu dài, 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 giảm hiệu suất của 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 KVM Operations này luôn đọc từ bộ nhớ đệm cho các thao tác 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ị được dùng trong chính sách trong bộ nhớ đệm trước khi chúng được 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 gian hết hạn của bộ nhớ đệm.

GET – Lần đầu tiên một thao tác GET KVM thực thi, các khoá/giá trị được yêu cầu từ KVM (có tên được chỉ định trong thuộc tính gốc mapIdentifier của chính sách) sẽ được tải vào bộ nhớ đệm, nơi chúng vẫn còn cho các thao tác GET tiếp theo cho đến khi một trong những điều kiện 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 ở phần tiếp theo).

PUT – Thao tác PUT ghi các khoá/giá trị vào KVM đã chỉ định. Nếu PUT ghi vào một khoá đã có 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 trong số giây được chỉ định trong phần tử <ExpiryTimeInSecs> của chính sách.

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

1. Thao tác GET truy xuất giá trị của "rating", 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, một chính sách PUT sẽ cập nhật giá trị của "rating" thành "8" và <ExpiryTimeInSecs> trên 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 đặt để duy trì trong bộ nhớ đệm trong 20 giây. (Nếu PUT chưa xảy ra, bộ nhớ đệm ban đầu được điền sẵn bởi GET đầu tiên vẫn sẽ tồn tại thêm 30 giây nữa, tức là thời gian còn lại trong 60 giây ban đầu.)
4. 15 giây sau, một lệnh GET khác sẽ thực thi và truy xuất giá trị "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 giá trị <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 để truy xuất nhiều mục từ KVM.

Nhận một mục duy nhất 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ử KVM có các khoá và giá trị sau. Ngoài việc lưu trữ danh sách các bộ phim nổi tiếng nhất mọi thời đại, KVM còn lưu trữ tên đạo diễn của tất cả các bộ phim lớn.

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

<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 API proxy được gọi, Edge sẽ tạo các biến sau đây mà bạn có thể sử dụng trong luồng API proxy:

• 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>

Giá trị ban đầu cho các bản đồ khoá-giá trị. Các giá trị này sẽ được điền sẵn trong bản đồ khoá-giá trị khi bản đồ được 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 một phiên bản đã triển khai của proxy hoặc triển khai gói proxy API chứa chính sách có phần tử này, (các) khoá sẽ tự động được tạo trong KVM (dưới dạng chưa mã hoá). Nếu các giá trị trong chính sách khác với các 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 sẽ đượ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ị do phần tử này điền phải là các 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á được giới hạn ở 2 KB cho cả Edge cho Đám mây công cộng và Edge cho Đám mây riêng tư. Giá trị KVM bị giới hạn ở 2 KB.

Để tạo KVM được mã hoá, hãy sử dụng API quản lý Key/Value Maps.

Phần tử <Key>

Chỉ định khoá trong một mục nhập khoá/giá trị. Khoá có thể là khoá kết hợp, tức là bạn có thể thêm nhiều tham số để tạo khoá. Ví dụ: userID và role có thể được kết hợp để tạo thành 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á.

Với Edge cho Đám mây công cộng, kích thước khoá được giới hạn ở 2 KB. Hãy xem bài viết Sự khác biệt giữa API Edge cho Đám mây công khai và API Đám mây riêng tư để 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 ký tự

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

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

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

• Sự kết hợp giữa các giá trị cố định và 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à phép nối các giá trị của từng tham số, được kết hợp với 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 nhận, 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 đồ khoá giá trị. Hãy xem phần Chỉ định và truy xuất tên khoá để biết các 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 một bản đồ khoá giá trị, cho dù bản đồ khoá giá trị đó được mã hoá hay không mã hoá. Nếu bản đồ khoá-giá trị đượ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ẽ được tạo tự động (dưới dạng chưa mã hoá). Nếu bản đồ giá trị khoá đã tồn tại, thì khoá/giá trị sẽ được thêm vào bản đồ đó.

Để tạo một sơ đồ khoá-giá trị được mã hoá, hãy sử dụng API quản lý Sơ đồ khoá/giá trị; hoặc xem phần Tạo và chỉnh sửa sơ đồ khoá-giá trị môi trường để tạo KVM được mã hoá theo phạm vi môi trường 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 các bản đồ khoá-giá trị. Phạm vi mặc định là environment, tức là theo mặc định, các mục trong bản đồ 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 xuất). Nếu bạn đặt phạm vi thành apiproxy, thì chỉ có proxy API ghi các giá trị vào bản đồ mới có thể truy cập vào các mục trong bản đồ khoá giá trị.

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

<Scope>environment</Scope>

Phần tử <Value>

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

<!-- 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ể thêm nhiều phần tử <Value> để chỉ định một giá trị gồm nhiều phần. Các giá trị được kết hợp tại thời gian chạy.

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

• Khoá k1 có giá trị v1,v2
• Khoá k2 có 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 bằng 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 có 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

Các lỗi được trả về từ chính sách Edge tuân theo một định dạng nhất quán như mô tả trong phần Tài liệu tham khảo về 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ế duy trì đơn giản cho dữ liệu được định dạng dưới dạng các cặp khoá/giá trị. Bạn có thể truy cập vào các đối tượng 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 đồ giá trị khoá. Bản đồ khoá-giá trị có thể lưu trữ nhiều mục.

Sau đây là 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 được liên kết với nhiều môi trường phụ trợ. Bạn có thể tạo một bản đồ giá trị khoá có tên là ipAddresses chứa danh sách các cặp khoá/giá trị dưới dạng các mục. 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ể sử dụng cấu trúc này để tạo một kho địa chỉ IP mà các chính sách có thể sử dụng trong thời gian chạy để thực thi danh sách cho phép hoặc danh sách chặn IP, để chọn độ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 tồn tại lâu dài cần được dùng lại trong nhiều giao dịch yêu cầu/phản hồi.

Bạn có thể thao tác với các bản đồ 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. 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. Bạn có thể sử dụng API này để, ví dụ: 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 trong bản đồ khoá/giá trị. Bạn sẽ cần tạo một bản đồ khoá/giá trị bằng API trước khi truy cập 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 mà giá trị của biến đó sẽ được dùng trong thời gian chạy.

Phần tử Tham số đáng được đề cập đặc biệt, vì phần tử này xác định tên của khoá sẽ đượ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ụ. Cách đầu tiên chỉ định tên khoá theo nghĩa đen, còn cách thứ hai chỉ định tên khoá bằng cách sử dụng một biến. Giả sử bạn dùng các thông tin sau để 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 đều 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 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ị theo nghĩa đen 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