スナップショット

[アーティクル]
07/20/2023

スナップショットは、その名前で一意に識別されるリソースです。各操作の詳細を確認してください。

この記事は、API バージョン 2022-11-01-preview に適用されます。

Operations

取得
複数を一覧表示
作成
アーカイブ/復旧
キー値の一覧表示

前提条件

すべての HTTP 要求が認証される必要があります。認証に関するセクションを参照してください。
すべての 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]
}

スナップショットの取得

必須: {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

取得 (条件付き)

クライアントのキャッシュを向上させるには、 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}

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

名前フィルター	結果
`name` を省略 (または `name=*`)	すべての名前のスナップショットと一致します
`name=abc`	abc という名前のスナップショットと一致します
`name=abc*`	abc で始まるスナップショットと一致します
`name=abc,xyz`	abc または xyz という名前のスナップショットと一致します (CSV の上限は 5 つ)

ステータスフィルター	結果
`status` を省略 (または `status=*`)	すべての状態のスナップショットと一致します
`status=ready`	準備完了状態のスナップショットと一致します
`status=ready,archived`	準備完了またはアーカイブ済みの状態のスナップショットと一致します (CSV の上限は 5 つ)

予約文字

*、\、,

予約文字が値の一部である場合は、\{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 /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

スナップショットの作成

parameters

プロパティ名	必須	既定値	検証
name	はい	該当なし	長さ最大: 256
filters	はい	該当なし	Count 最小: 1 最大: 3
filters[<インデックス>].key	はい	該当なし
tags	no	{}
filters[<インデックス>].label	no	null	複数一致ラベルフィルター (例: "*"、"コンマ区切り") は、'key' コンポジションの種類ではサポートされていません。
composition_type	no	key
retention_period	いいえ	Standard レベル 2592000 (30 日) Free レベル 604800 (7 日間)	Standard レベル最小: 3600 (1 時間) 最大: 7776000 (90 日) Free レベル最小: 3600 (1 時間) 最小: 604800 (7 日間)

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
}

新しく作成されたスナップショットの状態は "プロビジョニング" になります。スナップショットが完全にプロビジョニングされると、状態は "準備完了" に更新されます。クライアントはスナップショットをポーリングして、スナップショットの準備が整うのを待ってから、関連付けられたキー値を一覧表示します。操作に関する追加情報を照会するには、「ポーリングスナップショットの作成」セクションを参照してください。

スナップショットが既に存在する場合は、次の応答を受け取ります。

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}

スナップショットプロビジョニング操作の状態は、Operation-Location に含まれている URI にあります。クライアントは、この状態オブジェクトをポーリングして、スナップショットがプロビジョニングされていることを確認してから、関連付けられているキー値を一覧表示します。

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}

注意

ready または archived 状態ではないスナップショットの項目を一覧表示しようとすると、空のリスト応答が返されます。

特定のフィールドの要求

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

スナップショット

Operations

前提条件

構文

スナップショットの取得

取得 (条件付き)

スナップショットのリスト

改ページ位置の自動修正

フィルター処理

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

特定のフィールドの要求

スナップショットの作成

ポーリング スナップショットの作成

アーカイブ (パッチ)

復旧 (パッチ)

スナップショットのアーカイブ/復旧 (条件付き)

スナップショットのキー値を一覧表示する

特定のフィールドの要求

その他のリソース

ポーリングスナップショットの作成