خط مشی KeyValueMapOperations

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید .
اطلاعات

نماد عملیات نقشه ارزش کلیدی از رابط کاربری Edge

چی

دسترسی مبتنی بر خط مشی به فروشگاه نقشه ارزش کلیدی (KVM) موجود در Apigee Edge را فراهم می کند. جفت‌های کلید/مقدار را می‌توان با پیکربندی خط‌مشی‌های KeyValueMapOperations که عملیات‌های PUT، GET یا DELETE را مشخص می‌کنند، ذخیره، بازیابی و از نقشه‌های موجود نام‌گذاری‌شده حذف کرد. (حداقل یکی از این عملیات باید توسط خط مشی انجام شود.)

ویدیوها

برای آشنایی بیشتر با KVM ویدیوهای زیر را تماشا کنید.

ویدیو توضیحات
چرا نقشه‌های ارزش کلیدی؟ بیاموزید که چرا به KVM ها نیاز دارید و چگونه کار می کنند.
KVM را با استفاده از UI ایجاد کنید و KVM را در زمان اجرا بازیابی کنید یک KVM ایجاد کنید، مقدار آن را با استفاده از یک خط مشی KVM بازیابی کنید، و مقدار را با استفاده از متغیرهای جریان به درخواست API تزریق کنید.
ایجاد و به روز رسانی KVM در زمان اجرا API با استفاده از یک خط مشی KVM در زمان اجرای API یک KVM ایجاد کنید.
حافظه پنهان KVM برای افزایش عملکرد بهبود عملکرد سیاست KVM با ذخیره داده ها.
KVM رمزگذاری شده را ذخیره کنید اطلاعات حساس را در KVM در قالب رمزگذاری شده ذخیره کنید و مقدار را در زمان اجرا با استفاده از خط مشی KVM و متغیرهای خصوصی بازیابی کنید.
مدیریت دسترسی با استفاده از دامنه KVM KVM را با استفاده از ویژگی محدوده خط مشی KVM به سازمان، محیط، پراکسی API یا ویرایش پروکسی API محدود کنید.
ورودی های KVM را در زمان اجرا API حذف کنید با استفاده از عملیات DELETE خط مشی KVM، ورودی های KVM را در زمان اجرا API حذف کنید.

نمونه ها

KVM را با یک کلمه واقعی قرار دهید

هنگامی که خط مشی زیر اجرا می شود، یک KVM رمزگذاری شده به نام FooKVM ایجاد می کند، سپس کلیدی به نام FooKey_1 با دو مقدار تنظیم شده با رشته های واقعی foo و bar (با مقادیر استخراج شده از متغیرها تنظیم نمی شود) ایجاد می کند. وقتی کلید را در مثال بعدی GET ، یک عدد شاخص برای بازیابی مقدار مورد نظر خود تعیین می کنید.

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

توجه داشته باشید که دامنه "محیط" است. این بدان معناست که می‌توانید KVM را در رابط کاربری مدیریت در زیر APIs > Environment Configuration > Key Value Maps ببینید. KVM های نشان داده شده در آن صفحه، همگی در محیط انتخاب شده قرار دارند.

KVM را از یک Literal دریافت کنید

این خط مشی به نقشه FooKVM از مثال قبلی نگاه می کند، مقدار دوم (index="2") را از کلید FooKey_1 دریافت می کند و آن را در متغیری به نام foo_variable ذخیره می کند.

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

KVM را با یک متغیر قرار دهید

یک مثال ساده از یک نقشه ارزش کلیدی مفید، یک سرویس کوتاه کردن URL است. نقشه مقدار کلید را می توان برای ذخیره URL های کوتاه شده همراه با URL های کامل مربوطه پیکربندی کرد.

این نمونه خط مشی یک نقشه ارزش کلیدی ایجاد می کند. خط مشی یک کلید با دو مقدار مرتبط را در یک نقشه کلید/مقدار به نام "urlMapper" قرار می دهد.

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

کلید در این مثال، urlencoding.requesturl.hashed ، نمونه ای از یک متغیر سفارشی است. URL درخواست هش شده توسط کد (مثلاً جاوا اسکریپت یا جاوا) ایجاد می شود و سپس در این متغیر ذخیره می شود، جایی که خط مشی KeyValueMapOperations می تواند به آن دسترسی داشته باشد.

برای هر کلید، requesturl.hashed ، دو مقدار ذخیره می شود:

  • محتویات متغیر سفارشی با نام urlencoding.longurl.encoded
  • محتویات متغیر از پیش تعریف شده request.queryparam.url

به عنوان مثال، زمانی که سیاست در زمان اجرا اجرا می شود، مقادیر متغیرها ممکن است به صورت زیر باشد:

  • urlencoding.requesturl.hashed: ed24e12820f2f900ae383b7cc4f2b31c402db1be
  • urlencoding.longurl.encoded: http://tinyurl.com/38lwmlr
  • request.queryparam.url: http://apigee.com

نقشه و ورودی کلید/مقدار زیر در ذخیره‌سازی کلید/مقدار Edge ایجاد می‌شود و به پراکسی API که این خط‌مشی به آن پیوست شده است، قرار می‌گیرد:

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

ورودی تا زمانی که حذف نشود باقی خواهد ماند. ورودی‌های ذخیره کلید/مقدار در بین نمونه‌هایی از Edge که در حال اجرای ابر هستند، توزیع می‌شوند.

KVM را از یک متغیر دریافت کنید

یک مثال ساده از یک نقشه ارزش کلیدی مفید، سرویس «کوتاه کردن» URL است. نقشه مقدار کلید را می توان برای ذخیره URL های کوتاه شده همراه با URL های کامل مربوطه پیکربندی کرد.

برای بازیابی مقدار ورودی نقشه کلید/مقدار، مانند آنچه در برگه KeyValueMapOperations PUT پوشش داده شده است، یک خط مشی را برای دریافت نقشه مقدار کلید پیکربندی کنید:

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

وقتی این خط‌مشی اجرا می‌شود، اگر مقدار متغیر urlencoding.requesturl.hashed ed24e12820f2f900ae383b7cc4f2b31c402db1be باشد، متغیر سفارشی با نام urlencoding.shorturl با مقدار http://tinyurl.com/38lwmlr تنظیم می‌شود.

اکنون که داده ها بازیابی شده اند، سایر سیاست ها و کدها می توانند با استخراج مقدار از آن متغیرها به آن دسترسی داشته باشند.

مقدار رمزگذاری شده را از KVM دریافت کنید

اگر نقشه مقدار کلید رمزگذاری شده است، مقادیر را با استفاده از پیشوند " private. " در مقدار مشخصه assignTo بازیابی کنید. در این مثال، متغیر private.encryptedVar مقدار رمزگشایی شده کلید foo map مقدار کلید را نگه می‌دارد. برای اطلاعات در مورد ایجاد نقشه‌های ارزش کلید رمزگذاری‌شده، به موضوعات «ایجاد» API مدیریت نقشه‌های کلید/ارزش مراجعه کنید.

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

اکنون که داده ها بازیابی شده اند، سایر سیاست ها و کدها می توانند با استخراج مقدار از آن متغیر به آن دسترسی داشته باشند.


مرجع عنصر

مرجع عنصر عناصر و ویژگی های خط مشی 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>

ویژگی های <KeyValueMapOperations>

مثال زیر ویژگی های برچسب <KeyValueMapOperations> را نشان می دهد:

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

جدول زیر ویژگی های خاص تگ <KeyValueMapOperations> را شرح می دهد:

صفت توضیحات پیش فرض حضور
شناسه نقشه

شناسه ای را مشخص می کند که هنگام دسترسی به نقشه ایجاد شده توسط این خط مشی یا در رابط کاربری مدیریت استفاده شود.

نام KVM با Apigee Edge for Public Cloud حساس است. به عنوان مثال، foobar با FooBar متفاوت است.

اگر این ویژگی را حذف کنید، یک KVM به نام kvmap استفاده می شود.

در محدوده سازمان/محیط/apiproxy، می‌توانید از ویژگی mapIdentifier برای تعیین نام نقشه خود استفاده کنید.

N/A اختیاری

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

صفت توضیحات پیش فرض حضور
name

نام داخلی سیاست. مقدار مشخصه name می تواند شامل حروف، اعداد، فاصله، خط تیره، زیرخط و نقطه باشد. این مقدار نمی تواند بیش از 255 کاراکتر باشد.

در صورت تمایل، از عنصر <DisplayName> برای برچسب گذاری خط مشی در ویرایشگر پروکسی UI مدیریت با نامی به زبان طبیعی دیگر استفاده کنید.

N/A مورد نیاز
continueOnError

برای بازگرداندن خطا در صورت شکست خط مشی، روی false تنظیم کنید. این رفتار مورد انتظار برای اکثر سیاست ها است.

روی true تنظیم کنید تا اجرای جریان حتی پس از شکست خط مشی ادامه یابد.

نادرست اختیاری
enabled

برای اجرای خط مشی روی true تنظیم کنید.

برای خاموش کردن خط مشی، روی false تنظیم کنید. این سیاست حتی اگر به یک جریان وابسته باشد اجرا نخواهد شد.

درست است اختیاری
async

این ویژگی منسوخ شده است.

نادرست منسوخ شده است

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>
پیش فرض

N/A

اگر این عنصر را حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود.

حضور اختیاری
تایپ کنید رشته

عنصر <حذف>

جفت کلید/مقدار مشخص شده را حذف می کند. حداقل یکی از <Get> ، <Put> یا <Delete> باید استفاده شود.

حتماً نام KVM را با ویژگی mapIdentifier در عنصر والد مشخص کنید. به عنوان مثال:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>
پیش فرض N/A
حضور در صورت عدم وجود <Get> یا <Put> الزامی است.
تایپ کنید N/A

عنصر <Entry>

مقادیر اولیه برای نقشه‌های ارزش کلیدی، که در نقشه مقدار کلیدی پس از مقداردهی اولیه پر می‌شوند.

برای Edge for Public Cloud، اندازه کلید به 2 کیلوبایت محدود شده است. به عنوان مثال:

<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>
پیش فرض N/A
حضور اختیاری
تایپ کنید N/A

عنصر <ExclusiveCache>

منسوخ شده است. به جای آن از عنصر <Scope> استفاده کنید.

عنصر <ExpiryTimeInSecs>

مدت زمانی را بر حسب ثانیه مشخص می کند که پس از آن Edge مقدار کش شده خود را از KVM مشخص شده تازه می کند.

مقدار 0 یا 1- یا بدون احتساب این عنصر، به معنای استفاده از مقدار پیش فرض 300 ثانیه است. به عنوان مثال:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>
پیش فرض 300 (5 دقیقه)
حضور اختیاری
تایپ کنید عدد صحیح

KVM یک مکانیسم پایداری طولانی مدت است که کلیدها و مقادیر را در پایگاه داده NoSQL ذخیره می کند. به همین دلیل، خواندن از یک KVM در زمان اجرا می تواند عملکرد پروکسی را کاهش دهد. برای بهبود عملکرد، Edge دارای مکانیزم داخلی برای کش کردن کلیدها/مقدارهای KVM در حافظه در طول زمان اجرا است. این خط مشی عملیات KVM همیشه از حافظه پنهان برای عملیات GET خوانده می شود.

عنصر <ExpiryTimeInSecs> به شما امکان می دهد کنترل کنید که کلیدها/مقدارهای استفاده شده در خط مشی چه مدت در حافظه پنهان ذخیره می شوند، قبل از اینکه دوباره از KVM به روز شوند. با این حال، تفاوت هایی بین نحوه تأثیر عملیات GET و PUT بر انقضای حافظه پنهان وجود دارد.

GET - اولین باری که یک عملیات KVM GET اجرا می شود، کلیدها/مقدارهای درخواستی از KVM (که نام آنها در ویژگی اصلی mapIdentifier خط مشی مشخص شده است) در حافظه پنهان بارگذاری می شوند، جایی که برای عملیات های بعدی GET باقی می مانند تا زمانی که یکی از موارد زیر رخ دهد. :

  • تعداد ثانیه های مشخص شده در <ExpiryTimeInSecs> منقضی می شود.
    یا
  • یک عملیات PUT در یک خط مشی KVM مقادیر موجود را بازنویسی می کند (توضیح بعدی).

PUT - یک عملیات PUT کلیدها / مقادیر را در KVM مشخص شده می نویسد. اگر PUT روی کلیدی بنویسد که از قبل در حافظه پنهان وجود دارد، آن حافظه پنهان بلافاصله تازه می شود و اکنون مقدار جدید را برای تعداد ثانیه های مشخص شده در عنصر <ExpiryTimeInSecs> خط مشی نگه می دارد.

مثال - ذخیره یک KVM

  1. یک عملیات GET مقدار "رتبه" را بازیابی می کند، که مقدار "10" را به حافظه پنهان اضافه می کند. <ExpiryTimeInSecs> روی خط مشی 60 است.
  2. 30 ثانیه بعد، سیاست GET دوباره اجرا می شود و "10" را از حافظه پنهان بازیابی می کند.
  3. 5 ثانیه بعد، یک خط مشی PUT مقدار "رتبه بندی" را به "8" به روز می کند، و <ExpiryTimeInSecs> در خط مشی PUT برابر 20 است. حافظه پنهان بلافاصله با مقدار جدید به روز می شود، که اکنون تنظیم شده است تا در حافظه نهان باقی بماند. 20 ثانیه. (اگر PUT اتفاق نمی افتاد، حافظه پنهانی که در ابتدا توسط اولین GET پر شده بود همچنان برای 30 ثانیه دیگر باقی می ماند که از 60 ثانیه اولیه باقی مانده بود.)
  4. 15 ثانیه بعد، یک GET دیگر مقدار "8" را اجرا و بازیابی می کند.

عنصر <Get>

مقدار کلید مشخص شده را بازیابی می کند. حداقل یکی از <Get> ، <Put> یا <Delete> باید استفاده شود.

حتماً نام KVM را با ویژگی mapIdentifier در عنصر والد مشخص کنید.

برای بازیابی چندین مورد از یک KVM می‌توانید چندین بلوک Get در خط‌مشی قرار دهید.

پیش فرض N/A
حضور اگر <Put> یا <Delete> موجود نباشد، الزامی است.
تایپ کنید N/A

یک مورد واحد را از KVM دریافت کنید

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

چندین مورد را از یک KVM دریافت کنید

در مثال زیر، KVM را با کلیدها و مقادیر زیر فرض کنید. KVM علاوه بر ذخیره‌سازی فهرستی از محبوب‌ترین فیلم‌های تاریخ، نام کارگردان را برای همه فیلم‌های اصلی ذخیره می‌کند.

کلید ارزش
top_movies عروس پرنسس، پدرخوانده، شهروند کین
شهروند کین اورسن ولز
عروس پرنسس راب رینر
پدرخوانده فرانسیس فورد کاپولا

در اینجا یک پیکربندی خط‌مشی KVM وجود دارد که می‌توانیم از آن برای بازیابی محبوب‌ترین فیلم فعلی و نام کارگردان آن استفاده کنیم:

<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 فراخوانی می شود، Edge متغیرهای زیر را ایجاد می کند که می توانید در جریان پروکسی API از آنها استفاده کنید:

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

صفات

جدول زیر ویژگی های عنصر <Get> را شرح می دهد:

صفت توضیحات پیش فرض حضور
اختصاص به

متغیری که مقدار بازیابی شده باید به آن اختصاص داده شود.

اگر نقشه مقدار کلید رمزگذاری شده است، نام assignTo را با " private. " شروع کنید. به عنوان مثال:

<Get assignTo="private.myvar">

اگر بخواهید یک نقشه مقدار کلید رمزگذاری شده را بدون استفاده از پیشوند بازیابی کنید، خط مشی خطایی ایجاد می کند. پیشوندی که برای اهداف امنیتی اولیه در حین اشکال‌زدایی لازم است، مقادیر رمزگذاری‌شده را از ردیابی پراکسی API و جلسات اشکال‌زدایی پنهان می‌کند.

برای کسب اطلاعات در مورد ایجاد نقشه‌های ارزش کلید رمزگذاری‌شده، به عناوین «ایجاد» API مدیریت نقشه‌های کلید/ارزش و ایجاد و ویرایش نقشه‌های ارزش کلید محیطی مراجعه کنید.

N/A مورد نیاز
شاخص

شماره فهرست (در یک فهرست مبتنی بر 1) مورد برای واکشی از یک کلید چند ارزشی. به عنوان مثال، تعیین index=1 اولین مقدار را برمی گرداند و آن را به متغیر assignTo اختصاص می دهد. اگر مقدار شاخص مشخص نشده باشد، تمام مقادیر آن ورودی به عنوان java.util.List به متغیر اختصاص داده می شود.

برای مثال، به برگه «دریافت مقدار رمزگذاری شده از KVM» در Samples مراجعه کنید.

N/A اختیاری

عنصر <InitialEntries>

مقادیر اولیه برای نقشه‌های ارزش کلیدی، که در نقشه مقدار کلیدی پس از مقداردهی اولیه پر می‌شوند. حتماً نام KVM را با ویژگی mapIdentifier در عنصر والد مشخص کنید. به عنوان مثال:

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

هنگام استفاده از این عنصر، هنگامی که خط‌مشی را در رابط کاربری مدیریت در یک نسخه مستقر از پراکسی ذخیره می‌کنید، یا بسته پروکسی API حاوی خط‌مشی را با این عنصر مستقر می‌کنید، کلید(های) به طور خودکار در KVM ایجاد می‌شوند (به‌عنوان رمزگذاری نشده) . اگر مقادیر موجود در خط مشی با مقادیر موجود در KVM متفاوت باشد، هنگام استقرار پراکسی، مقادیر موجود در KVM بازنویسی می شوند. هر کلید/مقدار جدید در کنار کلیدها/مقدارهای موجود به KVM موجود اضافه می شود.

کلیدها و مقادیر پر شده توسط این عنصر باید تحت اللفظی باشند. برای مثال، <Parameter ref="request.queryparam.key"> در این عنصر پشتیبانی نمی شود.

اندازه کلید به 2 کیلوبایت برای Edge برای Public Cloud و Edge برای Private Could محدود شده است. مقدار KVM به 2 کیلوبایت محدود شده است.

برای ایجاد KVM رمزگذاری شده، از API مدیریت Key/Value Maps استفاده کنید.

پیش فرض N/A
حضور اختیاری
تایپ کنید N/A

عنصر <Key>

کلید را در ورودی نقشه کلید/مقدار مشخص می کند. یک کلید می تواند ترکیبی باشد، به این معنی که بیش از یک پارامتر می تواند برای ایجاد کلید اضافه شود. برای مثال، userID و role ممکن است برای ایجاد یک key ترکیب شوند. به عنوان مثال:

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

برای اطلاع از نحوه تنظیم نام کلید، حتما عنصر <Parameter> را ببینید.

با Edge for Public Cloud، اندازه کلید به 2 کیلوبایت محدود شده است. برای اطلاعات بیشتر به تفاوت بین Edge for Public Cloud API و Private Cloud API مراجعه کنید.

پیش فرض N/A
حضور اختیاری
تایپ کنید N/A

عنصر <Parameter>

کلید را در یک جفت کلید/مقدار مشخص می کند. این عنصر هنگام ایجاد، قرار دادن، بازیابی یا حذف جفت کلید/مقدار نام را مشخص می کند.

با استفاده از موارد زیر می توانید نام را مشخص کنید:

  • یک رشته تحت اللفظی

    <Key>
      <Parameter>literal</Parameter>
    </Key>
    
  • متغیری که در زمان اجرا با استفاده از ویژگی ref بازیابی می شود

    <Key>
      <Parameter ref="variable_name"/>
    </Key>
    
  • ترکیبی از منابع تحت اللفظی و منابع متغیر

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

زمانی که عنصر کلیدی شامل چندین عنصر پارامتر باشد، رشته کلید موثر الحاق مقادیر هر پارامتر است که با یک زیرخط دوتایی به هم وصل شده است. به عنوان مثال، در مثال بالا، اگر متغیر apiproxy.name دارای مقدار "abc1" باشد، کلید موثر targeturl__abc1__weight خواهد بود.

چه در حال دریافت، به‌روزرسانی یا حذف یک ورودی کلید/مقدار هستید، نام کلید باید با نام کلید در نقشه مقدار کلید مطابقت داشته باشد. برای دستورالعمل ها به تعیین و بازیابی نام های کلیدی مراجعه کنید.

پیش فرض N/A
حضور مورد نیاز
تایپ کنید رشته

صفات

جدول زیر ویژگی های عنصر <Parameter> را شرح می دهد:

صفت توضیحات پیش فرض حضور
رجوع کنید نام متغیری را مشخص می کند که مقدار آن حاوی نام دقیق کلیدی است که می خواهید ایجاد، دریافت یا حذف کنید. N/A اگر مقدار تحت اللفظی بین تگ های باز و بسته داده نشود، الزامی است. اگر مقدار تحت اللفظی داده شود ممنوع است.

عنصر <Put>

یک جفت کلید/مقدار را بر روی نقشه مقدار کلید می نویسد، خواه نقشه ارزش کلید رمزگذاری شده باشد یا بدون رمز. اگر نقشه مقدار کلید مشخص شده در ویژگی mapIdentifier در عنصر والد وجود نداشته باشد، نقشه به طور خودکار ایجاد می شود (به صورت رمزگذاری نشده). اگر نقشه ارزش کلید از قبل وجود داشته باشد، کلید/مقدار به آن اضافه می شود.

برای ایجاد یک نقشه ارزش کلید رمزگذاری شده، از API مدیریت Key/Value Maps استفاده کنید. یا ایجاد و ویرایش نقشه‌های ارزش کلیدی محیط برای ایجاد KVM‌های محیطی رمزگذاری‌شده در UI را ببینید.

<Put override="false">         
   <Key>             
      <Parameter ref="mykeyvar"/>         
   </Key>         
   <Value ref="myvalvar1"/>     
</Put>
پیش فرض N/A
حضور اگر <Get> یا <Delete> وجود نداشته باشد، الزامی است.
تایپ کنید N/A

صفات

جدول زیر ویژگی های عنصر <Put> را شرح می دهد:

صفت توضیحات پیش فرض حضور
لغو کردن

اگر روی true تنظیم شود، مقدار یک کلید را لغو می کند.

false اختیاری

عنصر <Scope>

مرز دسترسی را برای نقشه های ارزش کلیدی تعریف می کند. محدوده پیش‌فرض environment است، به این معنی که به‌طور پیش‌فرض، ورودی‌های نقشه‌ها توسط همه پراکسی‌های API که در یک محیط اجرا می‌شوند به اشتراک گذاشته می‌شوند (مثلاً تست یا پرود). اگر دامنه را روی apiproxy تنظیم کنید، ورودی‌های نقشه مقدار کلید فقط توسط پراکسی API که مقادیر را روی نقشه می‌نویسد قابل دسترسی است.

توجه داشته باشید که هنگام دسترسی به نقشه یا ورودی نقشه، باید همان مقدار محدوده ای را که هنگام ایجاد نقشه استفاده می کردید، مشخص کنید. به عنوان مثال، اگر نقشه با محدوده apiproxy ایجاد شده است، هنگام بازیابی مقادیر آن، اعمال تغییرات یا حذف ورودی ها باید از محدوده apiproxy استفاده کنید.

<Scope>environment</Scope>
پیش فرض environment
حضور اختیاری
تایپ کنید رشته
مقادیر معتبر:
  • organization
  • environment
  • apiproxy
  • policy (بازبینی پروکسی API)

عنصر <Value>

مقدار یک کلید را مشخص می کند. شما می توانید مقدار را به عنوان یک رشته تحت اللفظی یا با استفاده از ویژگی ref به عنوان متغیری که در زمان اجرا بازیابی می شود، مشخص کنید:

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

یا:

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

همچنین می توانید چندین عنصر <Value> را برای تعیین مقدار چند قسمتی اضافه کنید. مقادیر در زمان اجرا ترکیب می شوند.

در مثال زیر دو کلید به KVM اضافه شده است:

  • کلید k1 با مقادیر v1,v2
  • کلید k2 با مقادیر 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>

در مثال زیر یک کلید با دو مقدار ایجاد می شود. فرض کنید نام سازمان foo_org است، نام پراکسی API bar و محیط test است:

  • کلید foo_org با bar,test
<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>
پیش فرض N/A
حضور مورد نیاز
تایپ کنید رشته

صفات

جدول زیر ویژگی های عنصر <Value> را شرح می دهد:

صفت توضیحات پیش فرض حضور
رجوع کنید نام متغیری را مشخص می کند که مقدار آن حاوی مقدار(های) کلیدی است که می خواهید تنظیم کنید. N/A اگر مقدار تحت اللفظی بین تگ های باز و بسته داده نشود، الزامی است. اگر مقدار تحت اللفظی داده شود ممنوع است.

مرجع خطا

خطاهایی که از خط‌مشی‌های Edge برگردانده می‌شوند از یک قالب ثابت پیروی می‌کنند که در مرجع کد خطا توضیح داده شده است.

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

کد خطا وضعیت HTTP علت ثابت
steps.keyvaluemapoperations.SetVariableFailed 500

اگر بخواهید مقداری را از نقشه مقدار کلید رمزگذاری شده بازیابی کنید و مقدار آن را روی متغیری تنظیم کنید که نام آن پیشوند private ندارد، این خطا رخ می دهد. پیشوندی که برای اهداف امنیتی اولیه در حین اشکال‌زدایی لازم است، مقادیر رمزگذاری‌شده را از ردیابی پراکسی API و جلسات اشکال‌زدایی پنهان می‌کند.

steps.keyvaluemapoperations.UnsupportedOperationException 500

اگر مشخصه mapIdentifier روی رشته خالی در خط مشی عملیات Map Value Key تنظیم شده باشد، این خطا رخ می دهد.

خطاهای استقرار

این خطاها ممکن است زمانی رخ دهند که یک پروکسی حاوی این خط مشی را مستقر می کنید.

نام خطا علت ثابت
InvalidIndex اگر ویژگی index مشخص شده در عنصر <Get> خط مشی عملیات نقشه ارزش کلیدی صفر یا یک عدد منفی باشد، در این صورت استقرار پراکسی API با شکست مواجه می شود. شاخص از 1 شروع می شود، بنابراین یک شاخص صفر یا منفی به عنوان نامعتبر در نظر گرفته می شود.
KeyIsMissing این خطا در صورتی رخ می دهد که عنصر <Key> به طور کامل گم شده باشد یا عنصر <Parameter> در عنصر <Key> در زیر <Entry> عنصر <InitialEntries> خط مشی Key Value Map Operations وجود نداشته باشد.
ValueIsMissing این خطا در صورتی رخ می دهد که عنصر <Value> در زیر عنصر <Entry> عنصر <InitialEntries> خط مشی Key Value Map Operations وجود نداشته باشد.

طرحواره ها

نکات استفاده

برای نمای کلی از نقشه‌های ارزش کلیدی، به کار با نقشه‌های ارزش کلیدی مراجعه کنید.

یک ذخیره‌سازی نقشه ارزش کلیدی، مکانیسم پایداری سبکی را برای داده‌هایی که به صورت جفت کلید/مقدار قالب‌بندی شده‌اند، فراهم می‌کند. شما می توانید در زمان اجرا از طریق خط مشی ها یا کد به این موارد دسترسی داشته باشید. یک نقشه حاوی هرگونه داده دلخواه در قالب key=value .

به عنوان مثال localhost=127.0.0.1 ، zip_code=94110 ، یا first_name=felix . در مثال اول، localhost یک کلید است و 127.0.0.1 یک مقدار است. هر جفت کلید/مقدار به عنوان ورودی در نقشه مقدار کلید ذخیره می شود. یک نقشه ارزش کلیدی می تواند ورودی های زیادی را ذخیره کند.

در اینجا نمونه ای از استفاده از نقشه های ارزش کلیدی آورده شده است. فرض کنید باید لیستی از آدرس های IP مرتبط با محیط های مختلف باطن را ذخیره کنید. می توانید یک نقشه ارزش کلیدی به نام ipAddresses ایجاد کنید که حاوی لیستی از جفت های کلید/مقدار به عنوان ورودی است. به عنوان مثال، این JSON می تواند چنین نقشه ای را نشان دهد:

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

می‌توانید از این ساختار برای ایجاد ذخیره‌ای از آدرس‌های IP استفاده کنید که می‌تواند توسط خط‌مشی‌ها در زمان اجرا برای اعمال فهرست مجاز IP یا فهرست نشدن، برای انتخاب پویا یک آدرس هدف باطن و غیره استفاده شود. به طور معمول، خط مشی KeyValueMapOperations برای ذخیره یا بازیابی اطلاعات طولانی مدتی که نیاز به استفاده مجدد در چندین تراکنش درخواست/پاسخ دارند، استفاده می شود.

نقشه های کلید/مقدار را می توان از طریق خط مشی KeyValueMapOperations یا مستقیماً از طریق API مدیریت Apigee Edge دستکاری کرد. برای جزئیات بیشتر در مورد API نقشه های کلید/مقدار سازمان، به مرجع API مدیریت مراجعه کنید. برای مثال، می‌توانید از API برای آپلود مجموعه داده‌های بزرگ در فروشگاه کلید/مقدار یا ایجاد اسکریپت‌هایی برای مدیریت ورودی‌های نقشه کلید/مقدار استفاده کنید. قبل از دسترسی به آن با خط مشی KeyValueMapOperations، باید یک نقشه کلید/مقدار با API ایجاد کنید.

تعیین و بازیابی نام کلید

با عناصر <Parameter> و <Value> می‌توانید یک مقدار تحت اللفظی (جایی که مقدار بین تگ‌های باز و بسته است) تعیین کنید یا از ویژگی ref برای تعیین نام متغیری استفاده کنید که مقدار آن باید در زمان اجرا استفاده شود.

عنصر Parameter شایسته ذکر ویژه است، زیرا نام کلید ایجاد شده و همچنین نام کلیدی را که می خواهید بازیابی یا حذف کنید، تعیین می کند. در زیر دو نمونه آورده شده است. اولی یک نام کلید را به معنای واقعی کلمه مشخص می کند و دومی یک نام کلید را با استفاده از یک متغیر مشخص می کند. فرض کنید موارد زیر برای ایجاد کلیدها در KVM استفاده می شود:

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

در وهله اول، مقدار تحت اللفظی "key_name_literal" به عنوان نام کلید در KVM ذخیره می شود. در مورد دوم، هر مقداری که در key.name.variable باشد به نام کلید در KVM تبدیل می شود. برای مثال، اگر key.name.variable حاوی مقدار foo باشد، نام کلید "foo" خواهد بود.

هنگامی که می خواهید کلید و مقدار کلید را با عملیات GET بازیابی کنید (یا با عملیات DELETE حذف کنید)، تنظیم <Parameter> باید با نام کلید در KVM مطابقت داشته باشد. به عنوان مثال، اگر نام کلید در KVM "foo" است، می توانید مقدار تحت اللفظی را با <Parameter>foo</Parameter> تعیین کنید یا متغیری را مشخص کنید که حاوی مقدار دقیق "foo" باشد، مانند این: <Parameter ref="variable.containing.foo"/> .

موضوعات مرتبط