キー値

[アーティクル]
08/10/2024

キー値は、key + label の一意の組み合わせによって識別されるリソースです。 label はオプションです。ラベルがないキー値を明示的に参照する場合は、"\0" (URL エンコード: %00) を使用してください。各操作の詳細を確認してください。

操作

取得
複数を一覧表示
オン
削除

前提条件

すべての 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

省略可能: 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フィルター処理の組み合わせがサポートされています。省略可能な key、 label、およびクエリ文字列パラメーター tags 使用します。 tagName=tagValue形式のクエリ文字列パラメーターとして、複数のタグフィルターを指定できます。タグフィルターは完全に一致する必要があります。

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

サポートされているフィルター

キーフィルター	結果
`key` を省略 (または `key=*`)	すべてのキーに一致します
`key=abc`	abc という名前のキーに一致します
`key=abc*`	abc で始まるキー名に一致します
`key=abc,xyz`	キー名 abc または xyz に一致します (CSV の上限は 5 つ)

ラベルフィルター	結果
`label` を省略 (または `label=*`)	すべてのラベルに一致します
`label=%00`	ラベルのないキー値と一致します
`label=prod`	prod というラベルに一致します
`label=prod*`	prod で始まるラベルに一致します
`label=prod,test`	prod または test というラベルに一致します (CSV の上限は 5 つ)

タグフィルター	結果
`tags` を省略 (または `tags=`)	any タグと一致します
`tags=group=app1`	`group`という名前のタグを持つキー値と値が一致します`app1`
`tags=group=app1&tags=env=prod`	値が`app1group`という名前のタグと、`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
}

使用例

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

応答: 削除されたキー値を返すか、キー値が存在しない場合は none を返します。

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

HTTP/1.1 204 No Content

キーの削除 (条件付き)

これは、この記事の前述の「キーの設定 (条件付き)」セクションに似ています。

次の方法で共有

キー値

操作

前提条件

構文

キー値の取得

取得 (条件付き)

キー値の一覧表示

キー値の一覧表示 (条件付き)

フィルター処理

サポートされているフィルター

特定のフィールドの要求

時間ベースのアクセス

キーの設定

キーの設定 (条件付き)

削除

キーの削除 (条件付き)

フィードバック

その他のリソース