القيم الأساسية

مقالة
04/21/2022
قراءة خلال 4 دقائق

القيمة الرئيسية هي مورد يتم تحديده بواسطة مزيج فريد من key + label. label اختياري. للإشارة صراحة إلى قيمة مفتاح بدون تصنيف، استخدم "\0" (عنوان URL مشفر ك %00). انظر التفاصيل الخاصة بكل عملية.

تنطبق هذه المقالة على الإصدار 1.0 من واجهة برمجة التطبيقات.

العمليات

Get
قائمة متعددة
تعيين
حذف

المتطلبات الأساسية

يجب مصادقة جميع طلبات HTTP. راجع قسم المصادقة .
يجب أن توفر جميع طلبات HTTP صريحا api-version. راجع قسم تعيين الإصدارات .

بناء الجملة

{
  "etag": [string],
  "key": [string],
  "label": [string, optional],
  "content_type": [string, optional],
  "value": [string],
  "last_modified": [datetime ISO 8601],
  "locked": [boolean],
  "tags": [object with string properties, optional]
}

الحصول على القيمة الرئيسية

المطلوب: {key}, {api-version}
اختياري: label (إذا تم حذفه، فإنه يعني قيمة مفتاح بدون تسمية.)

GET /kv/{key}?label={label}&api-version={api-version}

الاستجابات:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8;
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": null,
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26+00:00",
  "locked": "false",
  "tags": {
    "t1": "value1",
    "t2": "value2"
  }
}

في حالة عدم وجود المفتاح، يتم إرجاع الاستجابة التالية:

HTTP/1.1 404 Not Found

الحصول على (مشروط)

لتحسين التخزين المؤقت للعميل، استخدم If-Match رؤوس الطلبات أو If-None-Match طلبها. etag الحجة هي جزء من التمثيل الرئيسي. لمزيد من المعلومات، راجع القسمين 14-24 و 14-26.

يسترد الطلب التالي قيمة المفتاح فقط إذا كان التمثيل الحالي لا يتطابق مع المحدد etag:

GET /kv/{key}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "{etag}"

الاستجابات:

HTTP/1.1 304 NotModified

أو

HTTP/1.1 200 OK

قائمة القيم الرئيسية

اختياري: key (إذا لم يتم تحديده، فإنه يعني أي مفتاح.) اختياري: label (إذا لم يتم تحديده، فإنه ينطوي على أي تسمية.)

GET /kv?label=*&api-version={api-version} HTTP/1.1

استجابه:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json; charset=utf-8

للحصول على خيارات إضافية، راجع قسم "التصفية" لاحقا في هذه المقالة.

ترقيم الصفحات

يتم ترقيم النتيجة في صفحة إذا تجاوز عدد العناصر التي تم إرجاعها حد الاستجابة. اتبع رؤوس الاستجابة الاختيارية Link ، واستخدمها rel="next" للتنقل. بدلا من ذلك ، يوفر المحتوى رابطا تاليا في شكل @nextLink مكان الإقامة. يتضمن عنوان URI المرتبط الوسيطة api-version .

GET /kv?api-version={api-version} HTTP/1.1

استجابه:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvs+json; charset=utf-8
Link: <{relative uri}>; rel="next"

{
    "items": [
        ...
    ],
    "@nextLink": "{relative uri}"
}

التصفية

يتم دعم مزيج من key والتصفية label . استخدم معلمات سلسلة الاستعلام والاختيارية keylabel .

GET /kv?key={key}&label={label}&api-version={api-version}

الفلاتر المدعومة

مرشح المفتاح	التأثير
`key` تم حذفه أو `key=*`	يطابق أي مفتاح
`key=abc`	يطابق مفتاحا باسم abc
`key=abc*`	يطابق أسماء المفاتيح التي تبدأ ب abc
`key=abc,xyz`	يطابق أسماء المفاتيح abc أو xyz (يقتصر على 5 CSV)

فلتر الملصقات	التأثير
`label` تم حذفه أو `label=*`	يطابق أي تصنيف
`label=%00`	يطابق KV بدون تسمية
`label=prod`	يطابق الحث على التسمية
`label=prod*`	يطابق التصنيفات التي تبدأ بالحث
`label=prod,test`	يطابق المحفزات أو الاختبارات الخاصة بالتصنيفات (تقتصر على 5 CSV)

الأحرف المحجوزة

*, \, ,

إذا كان الحرف المحجوز جزءا من القيمة ، فيجب الهروب منه باستخدام \{Reserved Character}. يمكن أيضا الهروب من الأحرف غير المحجوزة.

التحقق من صحة الفلتر

في حالة حدوث خطأ في التحقق من صحة عامل التصفية ، تكون الاستجابة هي HTTP 400 مع تفاصيل الخطأ:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Invalid request parameter '{filter}'",
  "name": "{filter}",
  "detail": "{filter}(2): Invalid character",
  "status": 400
}

أمثلة

الكل
```
GET /kv?api-version={api-version}
```
يبدأ اسم المفتاح ب abc ويتضمن جميع التسميات
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
يبدأ اسم المفتاح ب abc والتسمية تساوي v1 أو v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

طلب حقول محددة

استخدم معلمة سلسلة الاستعلام الاختيارية وقم بتوفير قائمة مفصولة بفواصل من الحقول $select المطلوبة. إذا تم حذف المعلمة، فستحتوي الاستجابة على المجموعة الافتراضية $select .

GET /kv?$select=key,value&api-version={api-version} HTTP/1.1

الوصول القائم على الوقت

الحصول على تمثيل للنتيجة كما كانت في وقت سابق. لمزيد من المعلومات، راجع القسم 2.1.1. لا يزال ترقيم الصفحات معتمدا كما هو محدد سابقا في هذه المقالة.

GET /kv?api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 12 May 2018 02:10:00 GMT

استجابه:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json"
Memento-Datetime: Sat, 12 May 2018 02:10:00 GMT
Link: <{relative uri}>; rel="original"

{
    "items": [
        ....
    ]
}

تعيين المفتاح

مطلوب: {key}
اختياري: label (إذا لم يكن محددا، أو label=٪00، فإنه يعني قيمة مفتاح بدون تسمية.)

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json

{
  "value": "example value",         // optional
  "content_type": "user defined",   // optional
  "tags": {                         // optional
    "tag1": "value1",
    "tag2": "value2",
  }
}

الاستجابات:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": "user defined",
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26.4874615+00:00",
  "tags": {
    "tag1": "value1",
    "tag2": "value2",
  }
}

إذا كان العنصر مقفلا، فستتلقى الرد التالي:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"

{
    "type": "https://azconfig.io/errors/key-locked",
    "title": "Modifing key '{key}' is not allowed",
    "name": "{key}",
    "detail": "The key is read-only. To allow modification unlock it first.",
    "status": "409"
}

تعيين المفتاح (بشكل مشروط)

لمنع ظروف السباق، استخدم If-Match رؤوس الرؤوس أو If-None-Match طلبها. etag الحجة هي جزء من التمثيل الرئيسي. إذا If-Match تم حذفها أو If-None-Match حذفها ، فإن العملية غير مشروطة.

تقوم الاستجابة التالية بتحديث القيمة فقط إذا كان التمثيل الحالي يتطابق مع المحدد etag:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

تقوم الاستجابة التالية بتحديث القيمة فقط إذا كان التمثيل الحالي لا يتطابق مع المحدد etag:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

يضيف الطلب التالي القيمة فقط في حالة وجود تمثيل بالفعل:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-Match: "*"

يضيف الطلب التالي القيمة فقط إذا كان التمثيل غير موجود بالفعل:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-None-Match: "*"

الاستجابات

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

أو

HTTP/1.1 412 PreconditionFailed

حذف

المطلوب: {key}, {api-version}
اختياري: {label} (إذا لم يكن محددا، أو label=٪00، فإنه يعني قيمة مفتاح بدون تسمية.)

DELETE /kv/{key}?label={label}&api-version={api-version} HTTP/1.1

استجابه: إرجاع قيمة المفتاح المحذوفة، أو لا شيء إذا لم تكن قيمة المفتاح موجودة.

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

أو

HTTP/1.1 204 No Content

حذف المفتاح (بشكل مشروط)

هذا مشابه لقسم "تعيين المفتاح (مشروط)" السابق في هذه المقالة.

القيم الأساسية

هل هذه الصفحة مفيدة؟

العمليات

المتطلبات الأساسية

بناء الجملة

الحصول على القيمة الرئيسية

الحصول على (مشروط)

قائمة القيم الرئيسية

ترقيم الصفحات

التصفية

الفلاتر المدعومة

طلب حقول محددة

الوصول القائم على الوقت

تعيين المفتاح

تعيين المفتاح (بشكل مشروط)

حذف

حذف المفتاح (بشكل مشروط)