اللقطة

مورد اللقطة غير متوفر في إصدار واجهة برمجة التطبيقات 1.0.

اللقطة هي مورد تم تعريفه بشكل فريد باسمه. راجع تفاصيل كل عملية.

العمليات

• الحصول على
• قائمة متعددة
• إنشاء
• الأرشفة/الاسترداد
• سرد قيم key

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

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

بناء الجملة

Snapshot

{
    "etag": [string],
    "name": [string],
    "status": [string, enum("provisioning", "ready", "archived", "failed")],
    "filters": [array<SnapshotFilter>],
    "composition_type": [string, enum("key", "key_label")],
    "created": [datetime ISO 8601],
    "size": [number, bytes],
    "items_count": [number],
    "tags": [object with string properties],
    "retention_period": [number, timespan in seconds],
    "expires": [datetime ISO 8601]
}

SnapshotFilter

{
  "key": [string],
  "label": [string]
}

{
  "key": [string],
  "label": [string],
  "tags": [array<string>]
}

الحصول على لقطة

مطلوب: {name}، {api-version}

GET /snapshots/{name}?api-version={api-version}

الاستجابات:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Mon, 03 Mar 2023 9:00:03 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Link: </kv?snapshot=prod-2023-03-20&api-version={api-version}>; rel="items"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "prod-2023-03-20",
  "status": "ready",
  "filters": [
      {
          "key": "*",
          "label": null
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 7776000
}

إذا لم تكن هناك لقطة بالاسم المقدم، يتم إرجاع الاستجابة التالية:

HTTP/1.1 404 Not Found

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

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

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

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

الاستجابات:

HTTP/1.1 304 NotModified

أو

HTTP/1.1 200 OK

سرد اللقطات

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

GET /snapshots?name=prod-*&api-version={api-version} HTTP/1.1

الاستجابة:

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

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

فصل الصفحات

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

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

الاستجابة:

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

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

التصفية

يتم دعم مزيج من عامل التصفية name وstatus. استخدم معلمات سلسلة الاستعلام الاختيارية name وstatus.

GET /snapshots?name={name}&status={status}&api-version={api-version}

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

حروف محجوزة

*، ، \,

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

• يبدأ اسم اللقطة ب abc

  GET /snapshot?name=abc*&api-version={api-version}
  

• يبدأ اسم اللقطة ب abc والحالة تساوي جاهزة أو مؤرشفة

  GET /snapshot?name=abc*&status=ready,archived&api-version={api-version}
  

طلب حقول خاصة

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

GET /snapshot?$select=name,status&api-version={api-version} HTTP/1.1

إنشاء لقطة

البارامترات

PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "filters": [                        // required
    {
      "key": "app1/*",                // required
      "label": "prod"                 // optional
    }
  ],
  "tags": {                           // optional
    "tag1": "value1",
    "tag2": "value2",
  },
  "composition_type": "key",          // optional
  "retention_period": 2592000         // optional
}

الاستجابات:

HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "{name}",
  "status": "provisioning",
  "filters": [
      {
          "key": "app1/*",
          "label": "prod"
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 2592000
}

PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "filters": [                                // required
    {
      "key": "app1/*",                        // required
      "label": "prod",                        // optional
      "tags": ["group=g1", "default=true"]    // optional
    }
  ],
  "tags": {                                   // optional
    "tag1": "value1",
    "tag2": "value2",
  },
  "composition_type": "key",                  // optional
  "retention_period": 2592000                 // optional
}

الاستجابات:

HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "{name}",
  "status": "provisioning",
  "filters": [
      {
          "key": "app1/*",
          "label": "prod",
          "tags": ["group=g1", "default=true"]
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 2592000
}

حالة اللقطة التي تم إنشاؤها حديثا هي provisioning. بمجرد توفير اللقطة بالكامل، يتم تحديث الحالة إلى ready. يمكن للعملاء استقصاء اللقطة لانتظار أن تكون اللقطة جاهزة قبل سرد قيم المفاتيح المقترنة بها. للاستعلام عن معلومات إضافية حول العملية، راجع قسم إنشاء لقطة الاستقصاء.

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

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

{
    "type": "https://azconfig.io/errors/already-exists",
    "title": "The resource already exists.",
    "status": 409,
    "detail": ""
}

إنشاء لقطة الاستقصاء

ترجع استجابة طلب إنشاء لقطة عنوانا Operation-Location .

الاستجابات:

HTTP/1.1 201 Created
...
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

يمكن العثور على حالة عملية توفير اللقطة في URI المضمن في Operation-Location. يمكن للعملاء استقصاء كائن الحالة هذا للتأكد من توفير لقطة قبل سرد قيم المفاتيح المقترنة به.

GET {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

الاستجابة:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "{id}",
    "status": "Succeeded",
    "error": null
}

إذا حدث أي خطأ أثناء توفير اللقطة، error تحتوي الخاصية على تفاصيل تصف الخطأ.

{
    "id": "{name}",
    "status": "Failed",
    "error": {
      "code": "QuotaExceeded",
      "message": "The allotted quota for snapshot creation has been surpassed."
    }
}

أرشيف (تصحيح)

يمكن أرشفة لقطة في ready الحالة. يتم تعيين تاريخ انتهاء صلاحية للقطة المؤرشفة، استنادا إلى فترة الاستبقاء التي تم إنشاؤها في وقت إنشائها. بعد مرور تاريخ انتهاء الصلاحية، سيتم حذف اللقطة نهائيا. في أي وقت قبل تاريخ انتهاء الصلاحية، لا يزال من الممكن سرد عناصر اللقطة.

لا تؤثر أرشفة لقطة بالفعل archived على اللقطة.

• مطلوب: {name}، ، {status}{api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "archived"
}

الاستجابة: إرجاع اللقطة المؤرشفة

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

{
  "etag": "33a0c9cdb43a4c2cb5fc4c1feede1c68",
  "name": "{name}",
  "status": "archived",
  ...
  "expires": "2023-08-11T21:00:03+00:00"
}

أرشفة لقطة موجودة حاليا في provisioning الحالة أو failed عملية غير صالحة.

الاستجابة:

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

{
    "type": "https://azconfig.io/errors/invalid-state",
    "title": "Target resource state invalid.",
    "detail": "The target resource is not in a valid state to perform the requested operation.",
    "status": 409
}

استرداد (تصحيح)

يمكن استرداد لقطة في archived الحالة. بعد استرداد اللقطة، تتم إزالة تاريخ انتهاء صلاحية اللقطة.

لا يؤثر استرداد لقطة بالفعل ready على اللقطة.

• مطلوب: {name}، ، {status}{api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "ready"
}

الاستجابة: إرجاع اللقطة المستردة

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

{
  "etag": "90dd86e2885440f3af9398ca392095b9",
  "name": "{name}",
  "status": "ready",
  ...
}

يعد استرداد لقطة موجودة حاليا في provisioning الحالة أو failed عملية غير صالحة.

الاستجابة:

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

{
    "type": "https://azconfig.io/errors/invalid-state",
    "title": "Target resource state invalid.",
    "detail": "The target resource is not in a valid state to perform the requested operation.",
    "status": 409
}

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

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

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

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

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

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

الاستجابات

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

أو

HTTP/1.1 412 PreconditionFailed

سرد قيم مفتاح اللقطة

مطلوب: {name}، {api-version}

GET /kv?snapshot={name}&api-version={api-version}

طلب حقول خاصة

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

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