Снимок

Статья
11/19/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 (ограничено 5 CSV)

Фильтр состояния	Действие
`status` не указан или имеет значение `status=*`	Соответствует моментальным снимкам с любым состоянием
`status=ready`	Соответствует моментальным снимкам с состоянием готовности
`status=ready,archived`	Соответствует моментальным снимкам с готовым или архивным состоянием (не более 5 CSV)

Зарезервированные знаки

*, \, ,

Если зарезервированный знак является частью значения, он должен быть экранирован с помощью \{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

Создать моментальный снимок

parameters

Имя свойства	Обязательное поле	Default value	Проверка
name	yes	Н/Д	Длина максимум: 256
фильтры	yes	Н/Д	Рассчитывать минимум: 1 максимум: 3
filters[<index>].key	yes	Н/Д
tags	no	{}
filters[<index>].label	no	null	Фильтры меток с несколькими совпадениями (например, "*", "запятая", разделенные") не поддерживаются с типом композиции key.
composition_type	no	key
retention_period	no	Уровень "Стандартный" 2592000 (30 дней) Бесплатный уровень 604800 (7 дней)	Уровень "Стандартный" минимум: 3600 (1 час) максимум: 7776000 (90 дней) Бесплатный уровень минимум: 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}

Состояние операции подготовки моментальных снимков можно найти в 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}

Примечание.

Попытка вывести список элементов моментального снимка, который не указан в ready состоянии, archived приведет к пустому ответу списка.

Поля со сведениями о запросах

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

Share via

Снимок

Operations

Необходимые компоненты

Синтаксис

Получение моментального снимка

Получить (условно)

Вывод списка моментальных снимков

Фильтрация

Поддерживаемые фильтры

Поля со сведениями о запросах

Создать моментальный снимок

Создание моментального снимка опроса

Архив (исправление)

Восстановление (исправление)

Архивация и восстановление моментального снимка (условно)

Вывод списка значений ключа моментального снимка

Поля со сведениями о запросах

Дополнительные ресурсы