KeyValueMapOperations politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. bilgi

Ne?

Apigee Edge'de bulunan bir Anahtar/Değer Eşlemesi (KVM) deposuna politikaya dayalı erişim sağlar. Anahtar/değer çiftleri, PUT, GET veya DELETE işlemlerini belirten KeyValueMapOperations politikaları yapılandırılarak adlandırılmış mevcut haritalarda depolanabilir, alınabilir ve silinebilir. (Bu işlemlerden en az biri politika tarafından gerçekleştirilmelidir.)

Videolar

KVM'ler hakkında daha fazla bilgi edinmek için aşağıdaki videoları izleyin.

Örnekler

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

Öğe referansı

Öğe referansı, KeyValueMapOperations politikasının öğelerini ve özelliklerini açıklar:

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

Aşağıdaki örnekte <KeyValueMapOperations> etiketindeki özellikler gösterilmektedir:

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

Aşağıdaki tabloda, <KeyValueMapOperations> etiketiyle ilgili özellikler açıklanmaktadır:

Aşağıdaki tabloda tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:

&lt;DisplayName&gt; öğe

Politikayı name özelliğine ek olarak farklı bir doğal dil adına sahip yönetim arayüzü proxy düzenleyicisi.

<DisplayName>Policy Display Name</DisplayName>

<Delete> öğesi

Belirtilen anahtar/değer çiftini siler. <Get>, <Put> veya <Delete> değerlerinden en az biri kullanılmalıdır.

Üst öğede mapIdentifier özelliğiyle KVM'nin adını belirttiğinizden emin olun. Örneğin:

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

<Entry> öğesi

Anahtar/değer çifti haritaları için başlangıç değerleri. Bu değerler, anahtar/değer çifti haritası başlatıldığında doldurulur.

Herkese Açık Bulut için Edge'de anahtar boyutu 2 KB ile sınırlıdır. Örneğin:

<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> öğesi

Kullanımdan kaldırıldı. Bunun yerine <Scope> öğesini kullanın.

<ExpiryTimeInSecs> öğesi

Edge'in, belirtilen KVM'den önbelleğe alınmış değerini yenileyeceği süreyi saniye cinsinden belirtir.

0 veya -1 değeri ya da bu öğenin hariç tutulması, 300 saniye olan varsayılan değerin kullanılacağı anlamına gelir. Örneğin:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM, anahtarları ve değerleri NoSQL veritabanında depolayan uzun vadeli bir kalıcılık mekanizmasıdır. Bu nedenle, çalışma zamanında bir KVM'den okuma işlemi, proxy performansını yavaşlatabilir. Performansı artırmak için Edge'de, çalışma zamanında KVM anahtarlarını/değerlerini bellekte önbelleğe almak için yerleşik bir mekanizma bulunur. Bu KVM İşlemleri politikası, GET işlemleri için her zaman önbellekten okur.

<ExpiryTimeInSecs> öğesi, politikada kullanılan anahtarların/değerlerin KVM'den tekrar yenilenmeden önce önbellekte ne kadar süreyle saklanacağını kontrol etmenizi sağlar. Ancak, GET ve PUT işlemlerinin önbellek geçerliliğini etkileme şekli arasında bazı farklar vardır.

GET: Bir KVM GET işlemi ilk kez yürütüldüğünde, KVM'den (adı politikanın kök mapIdentifier özelliğinde belirtilir) istenen anahtarlar/değerler önbelleğe yüklenir. Bu anahtarlar/değerler, aşağıdaki durumlardan biri gerçekleşene kadar sonraki GET işlemleri için önbellekte kalır:

• <ExpiryTimeInSecs> içinde belirtilen saniye sayısı sona erer.
  veya
• Bir KVM politikasındaki PUT işlemi, mevcut değerlerin üzerine yazar (bir sonraki bölümde açıklanmıştır).

PUT: Bir PUT işlemi, belirtilen KVM'ye anahtarlar/değerler yazar. PUT isteği, önbellekte zaten mevcut olan bir anahtara yazarsa bu önbellek hemen yenilenir ve artık politikanın <ExpiryTimeInSecs> öğesinde belirtilen saniye sayısı boyunca yeni değeri tutar.

Örnek: KVM'yi önbelleğe alma

1. GET işlemi,"rating" değerini alır ve bu değer önbelleğe "10" değerini ekler. Politikadaki <ExpiryTimeInSecs> sayısı 60'tır.
2. 30 saniye sonra GET politikası tekrar yürütülür ve önbellekten "10" değeri alınır.
3. 5 saniye sonra, bir PUT politikası "rating" değerini "8" olarak günceller ve PUT politikasındaki <ExpiryTimeInSecs> değeri 20 olur. Önbellek, yeni değerle hemen yenilenir. Yeni değer, 20 saniye boyunca önbellekte kalacak şekilde ayarlanır. (PUT işlemi gerçekleşmeseydi ilk GET tarafından doldurulan önbellek, orijinal 60 saniyeden kalan 30 saniye boyunca varlığını sürdürecekti.)
4. 15 saniye sonra başka bir GET işlemi yürütülür ve "8" değeri alınır.

<Get> öğesi

Belirtilen anahtarın değerini alır. <Get>, <Put> veya <Delete> değerlerinden en az biri kullanılmalıdır.

Üst öğede mapIdentifier özelliğiyle KVM'nin adını belirttiğinizden emin olun.

Bir KVM'den birden fazla öğe almak için politikaya birden fazla Get bloğu ekleyebilirsiniz.

KVM'den tek bir öğe alma

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

KVM'den birden fazla öğe alma

Aşağıdaki örnekte, aşağıdaki anahtarlara ve değerlere sahip bir KVM olduğunu varsayalım. KVM, tüm zamanların en popüler filmlerinin sürekli güncellenen bir listesini saklamanın yanı sıra tüm büyük filmlerin yönetmen adını da saklar.

Şu anda en popüler olan filmi ve yönetmeninin adını almak için kullanabileceğimiz bir KVM politika yapılandırması aşağıda verilmiştir:

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

API proxy'si çağrıldığında Edge, API proxy akışında kullanabileceğiniz aşağıdaki değişkenleri oluşturur:

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

Özellikler

Aşağıdaki tabloda <Get> öğesinin özellikleri açıklanmaktadır:

<Get assignTo="private.myvar">

<InitialEntries> öğesi

Anahtar/değer çifti eşlemeleri için başlangıç değerleri. Bu değerler, anahtar/değer çifti eşlemesi başlatıldığında doldurulur. Üst öğede mapIdentifier özelliğiyle KVM'nin adını belirttiğinizden emin olun. Örneğin:

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

Bu öğeyi kullanırken, politikayı dağıtılmış bir proxy sürümündeki yönetim kullanıcı arayüzüne kaydettiğinizde veya politikayı bu öğeyi içeren API proxy paketini dağıttığınızda anahtarlar KVM'de otomatik olarak oluşturulur (şifrelenmemiş olarak). Politikadaki değerler KVM'deki değerlerden farklıysa proxy dağıtıldığında KVM'deki değerlerin üzerine yazılır. Yeni anahtarlar/değerler, mevcut anahtarlar/değerlerle birlikte mevcut KVM'ye eklenir.

Bu öğeyle doldurulan anahtarlar ve değerler değişmez değer olmalıdır. Örneğin, <Parameter ref="request.queryparam.key"> bu öğede desteklenmez.

Anahtar boyutu hem Edge for the Public Cloud hem de Edge for the Private Cloud için 2 KB ile sınırlıdır. KVM değeri 2 KB ile sınırlıdır.

Şifrelenmiş bir KVM oluşturmak için Key/Value Maps Management API'yi kullanın.

<Key> öğesi

Anahtar/değer eşlemesi girişindeki anahtarı belirtir. Bir anahtar bileşik olabilir. Bu, anahtarı oluşturmak için birden fazla parametrenin eklenebileceği anlamına gelir. Örneğin, userID ve role birleştirilerek key oluşturulabilir. Örneğin:

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

Anahtar adının nasıl ayarlanacağıyla ilgili ayrıntılar için <Parameter> öğesine bakın.

Public Cloud için Edge'de anahtar boyutu 2 KB ile sınırlıdır. Daha fazla bilgi için Edge for Public Cloud API ile Private Cloud API arasındaki farklar başlıklı makaleyi inceleyin.

<Parameter> öğesi

Anahtar/değer çiftindeki anahtarı belirtir. Bu öğe, anahtar/değer çifti oluşturulurken, yerleştirilirken, alınırken veya silinirken adı belirtir.

Adı belirtmek için şunları kullanabilirsiniz:

• Değişken içermeyen dize

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

• ref özelliği kullanılarak çalışma zamanında alınacak bir değişken

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

• Değişmez değerler ve değişken referanslarının bir kombinasyonu

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

Anahtar öğesi birden fazla parametre öğesi içerdiğinde, geçerli anahtar dizesi, her parametrenin değerlerinin çift alt çizgiyle birleştirilmiş halidir. Örneğin, yukarıdaki örnekte apiproxy.name değişkeninin değeri "abc1" ise etkin anahtar targeturl__abc1__weight olur.

Bir anahtar/değer girişi alıyor, güncelliyor veya siliyor olmanızdan bağımsız olarak anahtar adı, anahtar/değer haritasındaki anahtarın adıyla eşleşmelidir. Kurallar için Anahtar adlarını belirtme ve alma başlıklı makaleyi inceleyin.

Özellikler

Aşağıdaki tabloda <Parameter> öğesinin özellikleri açıklanmaktadır:

<Put> öğesi

Anahtar/değer eşlemesi şifrelenmiş veya şifrelenmemiş olsun, anahtar/değer eşlemesine bir anahtar/değer çifti yazar. Üst öğedeki mapIdentifier özelliğinde belirtilen anahtar/değer eşlemesi yoksa eşleme otomatik olarak oluşturulur (şifrelenmemiş olarak). Anahtar değeri haritası zaten varsa anahtar/değer buna eklenir.

Şifrelenmiş bir anahtar/değer eşlemesi oluşturmak için Key/Value Maps Management API'yi kullanın veya kullanıcı arayüzünde şifrelenmiş ortam kapsamlı KVM'ler oluşturmak için Ortam anahtar/değer eşlemeleri oluşturma ve düzenleme başlıklı makaleyi inceleyin.

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

Özellikler

Aşağıdaki tabloda <Put> öğesinin özellikleri açıklanmaktadır:

<Scope> öğesi

Önemli değer haritaları için erişilebilirlik sınırını tanımlar. Varsayılan kapsam environment'dır. Bu, varsayılan olarak harita girişlerinin bir ortamda (ör. test veya prod) çalışan tüm API proxy'leri tarafından paylaşıldığı anlamına gelir. Kapsamı apiproxy olarak ayarlarsanız anahtar-değer haritasındaki girişlere yalnızca değerleri haritaya yazan API proxy'si tarafından erişilebilir.

Bir haritaya veya harita girişine erişirken, harita oluşturulurken kullandığınız kapsam değerini belirtmeniz gerektiğini unutmayın. Örneğin, harita apiproxy kapsamıyla oluşturulduysa değerlerini alırken, değişiklik yaparken veya girişleri silerken apiproxy kapsamını kullanmanız gerekir.

<Scope>environment</Scope>

<Value> öğesi

Bir anahtarın değerini belirtir. Değeri, değişmez dize olarak veya ref özelliğini kullanarak çalışma zamanında alınacak bir değişken olarak belirtebilirsiniz:

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

veya:

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

Çok parçalı bir değer belirtmek için birden fazla <Value> öğesi de ekleyebilirsiniz. Değerler çalışma zamanında birleştirilir.

Aşağıdaki örnekte, KVM'ye iki anahtar eklenir:

• Değerleri v1,v2 olan anahtar k1
• Değerleri v3,v4 olan anahtar k2

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

Aşağıdaki örnekte, iki değerle bir anahtar oluşturulur. Kuruluş adının foo_org, API proxy adının bar ve ortamın test olduğunu varsayalım:

• Değerleri bar,test olan anahtar foo_org

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

Özellikler

Aşağıdaki tabloda <Value> öğesinin özellikleri açıklanmaktadır:

Hata referansı

Edge politikalarından döndürülen hatalar, Hata kodu referansı'nda açıklandığı gibi tutarlı bir biçime sahiptir.

Bu bölümde, bu politika bir hatayı tetiklediğinde Edge tarafından ayarlanan hata kodları ile hata mesajları ve döndürülen hata mesajları ile Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiyi, hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.

Çalışma zamanı hataları

Politika yürütüldüğünde bu hatalar ortaya çıkabilir.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Şemalar

Kullanım notları

Anahtar/değer eşlemelerine genel bakış için Anahtar/değer eşlemeleriyle çalışma başlıklı makaleyi inceleyin.

Anahtar/değer çifti deposu, anahtar/değer çifti olarak biçimlendirilmiş veriler için basit bir kalıcılık mekanizması sağlar. Bunlara çalışma zamanında politikalar veya kod aracılığıyla erişebilirsiniz. Bir harita, key=value biçiminde herhangi bir rastgele veri içerir.

Örneğin localhost=127.0.0.1, zip_code=94110 veya first_name=felix. İlk örnekte localhost bir anahtar, 127.0.0.1 ise bir değerdir. Her anahtar/değer çifti, anahtar/değer eşlemesinde bir giriş olarak depolanır. Anahtar/değer eşlemesi birçok girişi saklayabilir.

Anahtar değer eşlemelerini kullanma örneğini aşağıda bulabilirsiniz. Çeşitli arka uç ortamlarıyla ilişkili IP adreslerinin bir listesini saklamanız gerektiğini varsayalım. Giriş olarak anahtar/değer çiftlerinin listesini içeren ipAddresses adlı bir anahtar/değer çifti haritası oluşturabilirsiniz. Örneğin, bu JSON aşağıdaki gibi bir haritayı temsil edebilir:

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

Bu yapıyı, IP izin verme veya IP engelleme işlemlerini zorunlu kılmak, arka uç hedef adresini dinamik olarak seçmek gibi işlemler için politikalar tarafından çalışma zamanında kullanılabilecek bir IP adresi deposu oluşturmak amacıyla kullanabilirsiniz. KeyValueMapOperations politikası genellikle birden fazla istek/yanıt işleminde yeniden kullanılması gereken uzun süreli bilgileri depolamak veya almak için kullanılır.

Anahtar/değer haritaları, KeyValueMapOperations politikası aracılığıyla veya doğrudan Apigee Edge Management API aracılığıyla değiştirilebilir. Organization key/value maps API API ile ilgili ayrıntılar için Management API referansına bakın. API'yi kullanarak örneğin anahtar/değer deposuna büyük veri kümeleri yükleyebilir veya anahtar/değer eşleme girişlerini yönetmek için komut dosyaları oluşturabilirsiniz. KeyValueMapOperations politikasıyla erişmeden önce API ile bir anahtar/değer eşlemesi oluşturmanız gerekir.

Anahtar adlarını belirtme ve alma

<Parameter> ve <Value> öğeleriyle, değişmez bir değer (değer, açılış ve kapanış etiketleri arasında yer alır) belirtebilir veya çalışma zamanında değeri kullanılacak bir değişkenin adını belirtmek için ref özelliğini kullanabilirsiniz.

Oluşturulan anahtarın adını ve almak ya da silmek istediğiniz anahtarın adını belirlediği için Parameter öğesi özellikle belirtilmelidir. Aşağıda iki örnek verilmiştir. Birincisi anahtar adını tam olarak belirtir, ikincisi ise değişken kullanarak anahtar adını belirtir. Bir Kernel Tabanlı Sanal Makine'de anahtar oluşturmak için aşağıdakilerin kullanıldığını varsayalım:

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

İlk durumda, "key_name_literal" değerinin değişmez değeri, anahtar adı olarak KVM'de saklanır. İkinci örnekte, key.name.variable içindeki değer, KVM'deki anahtarın adı olur. Örneğin, key.name.variable değeri foo içeriyorsa anahtarın adı "foo" olur.

GET işlemiyle anahtarı ve anahtar değerini almak (veya DELETE işlemiyle silmek) istediğinizde <Parameter> ayarının KVM'deki anahtar adıyla eşleşmesi gerekir. Örneğin , KVM'deki anahtar adı "foo" ise <Parameter>foo</Parameter> ile değişmez değeri belirtebilir veya tam olarak "foo" değerini içeren bir değişken belirtebilirsiniz <Parameter ref="variable.containing.foo"/>.

İlgili konular

• Organization key/value maps API