Поделиться через

Снимок

  • Статья

Ресурс моментальных снимков недоступен в API версии 1.0.

Моментальный снимок — это ресурс, однозначно определенный по его имени. См. информацию для каждой операции.

Операции

  • Получить
  • Вывод списка из нескольких значений
  • Создание
  • Архив и восстановление
  • Вывод списка пар "ключ-значение"

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

  • Все 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]
}

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

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

Чтобы улучшить кэширование клиента, используйте заголовки запроса 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

Or

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

Or

HTTP/1.1 412 PreconditionFailed

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

Требуется: {name}, {api-version}

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

Примечание.

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

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

Используйте необязательный параметр строки запроса $select и укажите список запрошенных полей, разделенный запятыми. Если параметр $select пропущен, ответ содержит набор по умолчанию.

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