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

مقالة
08/10/2024

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

العمليات

الحصول على
قائمة متعددة
المجموعة
حذف

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

لابد من مصادقة جميع طلبات HTTP. راجع القسم authentication.
يجب أن توفر جميع طلبات 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

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

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

إذا لم يكن key موجودًا، يتم إرجاع الاستجابة التالية:

HTTP/1.1 404 Not Found

Get (بشكل مشروط)

لتحسين التخزين المؤقت للعميل، استخدم عناوين الطلب If-Match أو If-None-Match. الوسيطة etag هي جزء من تمثيل key. لمزيدٍ من المعلومات، راجع القسمين 14.24 و14.26.

يسترد الطلب التالي قيمة key فقط إذا لم يتطابق التمثيل الحالي مع 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

اختياري: 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

اختياري: tags (إذا لم يتم تحديده، فإنه يعني أي علامات.)

GET /kv?key=Test*&label=*&tags=tag1=value1&tags=tag2=value2&api-version={api-version} HTTP/1.1

الاستجابة:

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

لمزيد من الخيارات، راجع قسم "التصفية" لاحقا في هذه المقالة.

سرد قيم المفاتيح (بشكل مشروط)

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

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

GET /kv?key={key}&label={label}&api-version={api-version} HTTP/1.1
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

الاستجابات:

HTTP/1.1 412 PreconditionFailed

أو

HTTP/1.1 200 OK

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

GET /kv?key={key}&label={label}&api-version={api-version} HTTP/1.1
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

الاستجابات:

HTTP/1.1 304 NotModified

أو

HTTP/1.1 200 OK

فصل الصفحات

يتم ترقيم النتيجة في حال تجاوز عدد العناصر التي تم إرجاعها حد الاستجابة. تتبع عناوين الاستجابة 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. استخدم معلمات سلسلة الاستعلام الاختيارية key وlabel.

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

يتم دعم مجموعة من keyو labelو و tags التصفية. استخدم معلمات سلسلة الاستعلام الاختيارية keylabelو وtags. يمكن توفير عوامل تصفية علامات متعددة كمعلمات سلسلة استعلام بالتنسيق tagName=tagValue . يجب أن تكون عوامل تصفية العلامات مطابقة تماما.

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

عوامل التصفيةِ المدعومة

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

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

عامل تصفية العلامات	التأثير
تم حذف `tags` أو `tags=`	يطابق أي علامة
`tags=group=app1`	يطابق قيم المفاتيح التي تحتوي على علامة تسمى `group` بقيمة `app1`
`tags=group=app1&tags=env=prod`	يطابق قيم المفاتيح التي تحتوي على علامة مسماة `group` بقيمة `app1` وعلامة مسماة `env` بقيمة `prod`(تقتصر على 5 عوامل تصفية علامات)
`tags=tag1=%00`	يطابق قيم المفاتيح التي تحتوي على علامة تسمى `tag1` بقيمة `null`
`tags=tag1=`	يطابق قيم المفاتيح التي تحتوي على علامة تسمى `tag1` بقيمة فارغة

حروف محجوزة

*، ، \,

في حال كان الحرف المحجوز جزءًا من القيمة، فيجب إلغاءه باستخدام \{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

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

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
}

تعيين key (بشكل مشروط)

لمنع حالات التعارض، استخدم If-Match أو If-None-Match اطلب العناوين. الوسيطة etag هي جزء من تمثيل key. إذا تم حذف 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، فإنه يعني قيمة key بدون تسمية.)

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

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

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

أو

HTTP/1.1 204 No Content

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

يشبه هذا القسم "Set key (conditionally)" سابقًا في هذه المقالة.

مشاركة عبر

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

العمليات

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

بناء الجملة

الحصول على قيمة key

Get (بشكل مشروط)

سرد قيم key

سرد قيم المفاتيح (بشكل مشروط)

التصفية

عوامل التصفيةِ المدعومة

طلب حقول خاصة

الوصول استنادًا إلى الوقت

تعيين key

تعيين key (بشكل مشروط)

حذف

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

الملاحظات

الموارد الإضافية