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

Cho phép truy cập vào cửa hàng trên Bản đồ giá trị khoá (KVM) dựa trên chính sách 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. (Ít nhất một trong số những thao tác này phải được chính sách thực hiện).

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ử

Tham chiếu phần tử mô tả các phần tử và thuộc tính của KeyValueMapOperations chính sách của Google:

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

<KeyValueMapOperations> thuộc tính

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 cụ thể của 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:

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

<Delete> phần tử

Xoá cặp khoá/giá trị được chỉ định. Ít nhất một trong số <Get>, Bạn phải sử dụng <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>

<Entry> phần tử

Giá trị gốc cho bản đồ khoá-giá trị, được điền sẵn vào bản đồ khoá-giá trị khi đã khởi chạy.

Đối với Edge dành cho Đám mây công cộng, kích thước khoá bị 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>

<ExclusiveCache> phần tử

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

<ExpiryTimeInSecs> phần tử

Chỉ định khoảng thời gian 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 loại trừ phần tử này có nghĩa là giá trị mặc định của 300 giây là đã sử dụng. Ví dụ:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM là một cơ chế cố định dài hạn giúp 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 của proxy. Để cải thiện Edge có cơ chế tích hợp để lưu khoá/giá trị KVM vào bộ nhớ đệm trong thời gian chạy. Chính sách Hoạt động KVM này luôn đọc từ bộ nhớ đệm đối với các thao tác GET.

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

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

PUT – Thao tác PUT sẽ 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, bộ nhớ đệm đó sẽ được làm mới ngay lập tức và giữ lại giá trị mới cho số giây được chỉ định trong chính sách Phần tử <ExpiryTimeInSecs>.

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

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

<Get> phần tử

Truy xuất giá trị cho khoá được chỉ định. Ít nhất một trong số <Get>, Bạn phải sử dụng <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ặt hàng qua KVM

Trong ví dụ sau, giả sử một KVM có các khoá và giá trị sau. Ngoài ra để lưu trữ một danh sách đang chạy các bộ phim phổ biến nhất mọi thời đại, KVM lưu trữ tên đạo diễn của 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 ta có thể sử dụng để truy xuất phim phổ biến nhất hiện tại và tên giám đốc:

<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 những nội dung sau các biến mà bạn có thể sử dụng trong luồng 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">

<InitialEntries> phần tử

Giá trị gốc cho bản đồ khoá-giá trị, được điền sẵn vào bản đồ khoá-giá trị khi khởi tạo. Hãy nhớ chỉ định tên của KVM có thuộc tính mapIdentifier bật 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 nhau so với các giá trị trong KVM, thì các giá trị trong KVM sẽ bị ghi đè khi proxy được triển khai. Bất kỳ hạng nào các khoá/giá trị mới đượ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ụ: phần tử này không hỗ trợ <Parameter ref="request.queryparam.key">.

Khoá có kích thước giới hạn ở mức 2 KB cho cả Edge của Public Cloud và Edge dành cho chế độ Riêng tư. Giá trị KVM được giới hạn trong 2 KB.

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

<Key> phần tử

Chỉ định khoá trong một mục ánh xạ khoá/giá trị. Một khoá có thể là khoá kết hợp, tức là nhiều hơn một tham số có thể được nối để 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á.

Với Edge dành cho Cloud Public, kích thước khoá bị giới hạn ở mức 2 KB. Xem bài viết Sự khác biệt giữa Edge for Public Cloud API và Private Cloud API để biết thêm thông tin.

<Parameter> phần tử

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

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

• Chuỗi ký tự

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

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

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

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

  <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ử Thông số, chuỗi khoá có hiệu lực là nối các giá trị của mỗi thông số, kết hợp bằng dấu gạch dưới đôi. Ví dụ: trong ví dụ ở trên, nếu biến apiproxy.name có giá trị "abc1", thì khoá có hiệu lực sẽ là targeturl__abc1__weight.

Cho dù bạn đang tải, cập nhật hoặc xoá mục nhập khoá/giá trị, tên khoá phải khớp với tên của khoá trong sơ đồ liên kết khoá-giá trị. 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>:

<Put> phần tử

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

Để tạo sơ đồ liên kết giá trị khoá đã mã hoá, hãy sử dụng API quản lý Bản đồ giá trị/khoá; hoặc xem bài viết Tạo và chỉnh sửa bản đồ giá trị khoá của môi trường để tạo KVM ở 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>:

<Scope> phần tử

Xác định ranh giới khả năng tiếp cận cho các bản đồ khoá-giá trị. Phạm vi mặc định là environment, nghĩa là theo mặc định, tất cả proxy API sẽ dùng chung các mục nhập bản đồ chạy trong một môi trường (ví dụ: thử nghiệm hoặc sản phẩm). Nếu bạn đặt phạm vi thành apiproxy, thì chỉ proxy API có thể truy cập vào các mục nhập trong sơ đồ khoá-giá trị ghi các giá trị vào bản đồ.

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 đã sử dụng khi bản đồ được tạo. 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 nó, đặt thay đổi hoặc xoá mục nhập.

<Scope>environment</Scope>

<Value> phần tử

Chỉ định giá trị của một khoá. Bạn có thể chỉ định giá trị ở dạng chuỗi cố định hoặc sử dụng thuộc tính ref, dưới dạng một biế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ể thêm nhiều phần tử <Value> để chỉ định một phần giá trị. Các giá trị được kết hợp trong thời gian chạy.

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

• Khoá k1 với các giá trị v1,v2
• Khoá k2 với cá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ổ chức tên là foo_org, tên proxy API là bar và môi trường là test:

• Khoá foo_org với cá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 do chính sách của Edge trả về sẽ có 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ề sơ đồ liên kết khoá-giá trị, hãy xem bài viết Làm việc với sơ đồ liên kết khoá-giá trị.

Kho lưu trữ bản đồ khoá-giá trị cung cấp cơ chế bền vững gọn nhẹ cho dữ liệu được định dạng cặp khoá/giá trị. Bạn có thể truy cập vào các báo cáo này trong thời gian chạy thông qua các chính sách hoặc mã. Một bản đồ chứa bất kỳ 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 nhập trong một khoá bản đồ giá trị. Sơ đồ khoá-giá trị có thể lưu trữ nhiều mục nhập.

Dưới đây là ví dụ về cách sử dụng bản đồ khoá-giá trị. Giả sử bạn cần lưu trữ một danh sách địa chỉ IP được liên kết với nhiều phần phụ trợ môi trường xung quanh. Bạn có thể tạo một bản đồ khoá-giá trị có tên là ipAddresses chứa danh sách 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 đị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 IP được cho phép hoặc danh sách từ chối IP, để tự động chọn một đích phụ trợ và 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 đồ khoá/giá trị có thể được thao tác 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 để, cho 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ý khoá/giá trị mục nhập bản đồ. Bạn cần tạo bản đồ khoá/giá trị bằng API trước khi truy cập bản đồ đó bằng Chính sách KeyValueMapOperations.

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

Với 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 các thẻ mở và đóng) hoặc sử dụng thuộc tính ref để chỉ định tên của một biến có giá trị phải được sử dụng tại thời gian chạy.

Phần tử Thông số cần được đề cập đặc biệt vì nó xác định tên của khoá mà sẽ được tạo, cũng như tên khoá bạn muốn truy xuất hoặc xoá. Sau đây là hai ví dụ. Trường đầu tiên chỉ định tên khoá theo đúng nghĩa đen và trường thứ hai chỉ định tên khoá bằng cách sử dụng một biến. Hãy giả sử các ví dụ 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 khoá . Trong phiên bản thứ hai, bất kỳ giá trị nào trong key.name.variable sẽ trở thành giá trị tên của khoá trong KVM. Ví dụ: nếu key.name.variable chứa có giá trị foo, thì khoá sẽ được đặt 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), <Tham số> cần phải khớp với tên khoá trong KVM. Cho 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 chính xác giá trị "foo", như sau: <Parameter ref="variable.containing.foo"/>.

Chủ đề có liên quan

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