Kunci-nilai

Kunci-nilai adalah sumber daya yang diidentifikasi oleh kombinasi unik key + label. label bersifat opsional. Untuk secara eksplisit mereferensikan kunci-nilai tanpa label, gunakan "\0" (URL yang dikodekan sebagai %00). Lihat detail untuk setiap operasi.

Operasional

• Dapatkan
• Cantumkan beberapa
• Set
• Hapus

Prasyarat

• Semua permintaan HTTP harus diautentikasi. Lihat bagian autentikasi.
• Semua permintaan HTTP harus menyediakan eksplisit api-version. Lihat bagian penerapan versi.

Sintaks

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

Dapatkan kunci-nilai

Wajib diisi: {key}, {api-version}
Opsional: label (Jika dihilangkan, ini menunjukkan nilai kunci tanpa label.)

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

Respons:

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

Jika kunci tidak ada, akan ditampilkan respons berikut:

HTTP/1.1 404 Not Found

Dapatkan (secara bersyarat)

Untuk meningkatkan cache klien, gunakan header permintaan If-Match atau If-None-Match. Argumen etag adalah bagian dari representasi kunci. Untuk informasi selengkapnya, lihat bagian 14.24 dan 14.26.

Permintaan berikut mengambil kunci-nilai hanya jika representasi saat ini tidak cocok dengan etag yang ditentukan:

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

Respons:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Daftar kunci-nilai

Opsional: key (Jika tidak ditentukan, ini menyiratkan kunci apa saja.)

Opsional: label (Jika tidak ditentukan, ini menyiratkan label apa pun.)

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

Respons:

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

Opsional: tags (Jika tidak ditentukan, ini menyiratkan tag apa pun.)

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

Respons:

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

Untuk opsi lainnya, lihat bagian "Pemfilteran" nanti di artikel ini.

Mencantumkan nilai kunci (secara kondisional)

Untuk meningkatkan cache klien, gunakan header permintaan If-Match atau If-None-Match. Argumen etag adalah bagian dari daftar isi dan header respons nilai kunci. Jika If-Match atau If-None-Match dihilangkan, operasi bersifat tidak bersyarat.

Respons berikut mendapatkan nilai kunci hanya jika representasi saat ini cocok dengan yang ditentukan etag:

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

Respons:

HTTP/1.1 412 PreconditionFailed

or

HTTP/1.1 200 OK

Respons berikut mendapatkan nilai kunci hanya jika representasi saat ini tidak cocok dengan yang ditentukan etag:

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

Respons:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Penentuan halaman

hasilnya akan ditentukan halaman jika jumlah item yang dikembalikan melebihi batas respons. Ikuti Link header respons opsional dan gunakan rel="next" untuk navigasi. Atau, konten menyediakan tautan berikutnya dalam bentuk properti @nextLink. URI yang ditautkan menyertakan argumen api-version.

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

Respons:

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

Filter

Kombinasi pemfilteran key dan label didukung. Gunakan parameter string kueri key dan label opsional.

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

Kombinasi pemfilteran key, label, dan tags didukung. Gunakan parameter string kueri , , labeldan tags opsionalkey. Beberapa filter tag dapat disediakan sebagai parameter string kueri dalam tagName=tagValue format . Filter tag harus sama persis.

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

Filter yang didukung

Karakter khusus

*, , \,

Jika karakter khusus adalah bagian dari nilai, karakter harus lolos menggunakan \{Reserved Character}. Karakter tidak khusus juga dapat hilang.

Validasi filter

Jika validasi filter gagal, responsnya adalah HTTP 400 dengan detail kesalahan:

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
}

Contoh

• Semua

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

• Nama kunci dimulai dengan abc dan menyertakan semua label

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

• Nama kunci dimulai dengan abc dan label sama dengan v1 atau v2

  GET /kv?key=abc*&label=v1,v2&api-version={api-version}
  

Bidang khusus permintaan

Gunakan parameter string kueri opsional $select dan berikan daftar bidang yang diminta yang dipisahkan koma. Jika parameter $select dihilangkan, respons berisi set default.

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

Akses berbasis waktu

Dapatkan representasi hasil seperti pada waktu yang lalu. Untuk informasi selengkapnya, lihat bagian 2.1.1. Penentuan halaman tetap didukung sebagaimana ditentukan sebelumnya dalam artikel ini.

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

Respons:

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": [
        ....
    ]
}

Atur kunci

• Wajib diisi: {key}
• Opsional: label (Jika tidak ditentukan, atau label=%00, ini menyiratkan kunci-nilai tanpa label.)

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

Respons:

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

Jika item dikunci, respons berikut dikembalikan:

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
}

Atur kunci (bersyarat)

Untuk mencegah kondisi persaingan, gunakan header permintaan If-Match atau If-None-Match. Argumen etag adalah bagian dari representasi kunci. Jika If-Match atau If-None-Match dihilangkan, operasi bersifat tidak bersyarat.

Respons berikut memperbarui nilai hanya jika representasi saat ini cocok dengan etag yang ditentukan:

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

Respons berikut memperbarui nilai hanya jika representasi saat ini tidak cocok dengan etag yang ditentukan:

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

Permintaan berikut menambahkan nilai hanya jika representasi sudah ada:

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

Permintaan berikut menambahkan nilai hanya jika representasi belum ada:

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

Responses to

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

or

HTTP/1.1 412 PreconditionFailed

Hapus

• Wajib diisi: {key}, {api-version}
• Opsional: {label} (Jika tidak ditentukan, atau label=%00, ini menyiratkan kunci-nilai tanpa label.)

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

Respons: Tampilkan kunci-nilai yang dihapus, atau tidak ada jika tidak ada nilai kunci.

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

or

HTTP/1.1 204 No Content

Hapus kunci (bersyarat)

Ini sama seperti bagian "Atur kunci (bersyarat)" sebelumnya di artikel ini.