Snapshot

Artykuł
08/10/2024

Zasób migawki nie jest dostępny w interfejsie API w wersji 1.0.

Migawka to zasób identyfikowany unikatowo według jego nazwy. Zobacz szczegóły każdej operacji.

Operacje

Get
Lista wielu
Utworzenie
Archiwizowanie/odzyskiwanie
Wyświetlanie listy par klucz-wartości

Wymagania wstępne

Wszystkie żądania HTTP muszą być uwierzytelnione. Zobacz sekcję uwierzytelniania .
Wszystkie żądania HTTP muszą podać jawne api-version. Zobacz sekcję przechowywanie wersji.

Składnia

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

Pobieranie migawki

Wymagane: {name}, {api-version}

GET /snapshots/{name}?api-version={api-version}

Odpowiedzi:

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
}

Jeśli migawka o podanej nazwie nie istnieje, zostanie zwrócona następująca odpowiedź:

HTTP/1.1 404 Not Found

Pobieranie (warunkowo)

Aby ulepszyć buforowanie klienta, użyj If-Match nagłówków lub If-None-Match żądań. Argument etag jest częścią reprezentacji migawki. Aby uzyskać więcej informacji, zobacz sekcje 14.24 i 14.26.

Następujące żądanie pobiera migawkę tylko wtedy, gdy bieżąca reprezentacja nie jest zgodna z określoną wartością etag:

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

Odpowiedzi:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Wyświetlanie listy migawek

Opcjonalnie: name (Jeśli nie zostanie określony, oznacza to dowolną nazwę). Opcjonalnie: status (Jeśli nie zostanie określony, oznacza to jakikolwiek stan).

GET /snapshots?name=prod-*&api-version={api-version} HTTP/1.1

Odpowiedź:

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

Aby uzyskać więcej opcji, zobacz sekcję "Filtrowanie" w dalszej części tego artykułu.

Podział na strony

Wynik jest podzielony na strony, jeśli liczba zwracanych elementów przekracza limit odpowiedzi. Postępuj zgodnie z opcjonalnymi Link nagłówkami odpowiedzi i użyj ich rel="next" do nawigacji. Alternatywnie zawartość udostępnia następny link w postaci @nextLink właściwości. Połączony identyfikator URI zawiera api-version argument .

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

Odpowiedź:

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

Filtrowanie

Obsługiwana jest kombinacja name i status filtrowanie. Użyj opcjonalnych name parametrów ciągu zapytania i status .

GET /snapshots?name={name}&status={status}&api-version={api-version}

Obsługiwane filtry

Filtr nazw	Efekt
Element `name` jest pomijany lub `name=*`	Pasuje do migawek z dowolną nazwą
`name=abc`	Pasuje do migawki o nazwie abc
`name=abc*`	Dopasuje migawki z nazwami rozpoczynającymi się od abc
`name=abc,xyz`	Pasuje do migawek z nazwami abc lub xyz (ograniczony do 5 CSV)

Filtr stanu	Efekt
Element `status` jest pomijany lub `status=*`	Pasuje do migawek z dowolnym stanem
`status=ready`	Pasuje do migawek ze stanem gotowości
`status=ready,archived`	Pasuje do migawek z gotowym lub zarchiwizowanym stanem (ograniczony do 5 CSV)

Zastrzeżone znaki

*, , \,

Jeśli zastrzeżony znak jest częścią wartości, należy go uniknić za pomocą polecenia \{Reserved Character}. Znaki bez zastrzeżeń można również uniknić.

Walidacja filtru

Jeśli sprawdzanie poprawności filtru zakończy się niepowodzeniem, odpowiedź to HTTP 400 ze szczegółami błędu:

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
}

Przykłady

wszystkie

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

Nazwa migawki zaczyna się od abc

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

Nazwa migawki zaczyna się od abc i stan jest równy gotowe lub zarchiwizowane

GET /snapshot?name=abc*&status=ready,archived&api-version={api-version}

Żądanie określonych pól

Użyj opcjonalnego $select parametru ciągu zapytania i podaj rozdzielaną przecinkami listę żądanych pól. $select Jeśli parametr zostanie pominięty, odpowiedź zawiera zestaw domyślny.

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

Utwórz migawkę

parameters

Nazwa właściwości	Wymagania	Domyślna wartość	Walidacja
name	tak	nie dotyczy	Długość Maksimum: 256
filtry	tak	nie dotyczy	Hrabia Minimum: 1 Maksimum: 3
filters[<index>].key	tak	nie dotyczy
filters[<index>].label	nie	null	Filtry etykiet z wieloma dopasowaniami (na przykład: "*", "przecinek,rozdzielone") nie są obsługiwane w przypadku typu kompozycji "klucz".
tags	nie	{}
composition_type	nie	key
retention_period	nie	Warstwa Standardowa 2592000 (30 dni) Warstwa Bezpłatna 604800 (siedem dni)	Warstwa Standardowa Minimum: 3600 (jedna godzina) Maksimum: 7776000 (90 dni) Warstwa Bezpłatna Minimum: 3600 (jedna godzina) Maksimum: 604800 (siedem dni)

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
}

Odpowiedzi:

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
}

Nazwa właściwości	Wymagania	Domyślna wartość	Walidacja
name	tak	nie dotyczy	Długość Maksimum: 256
filtry	tak	nie dotyczy	Hrabia Minimum: 1 Maksimum: 3
filters[<index>].key	tak	nie dotyczy
filters[<index>].label	nie	null	Filtry etykiet z wieloma dopasowaniami (na przykład: "*", "przecinek,rozdzielone") nie są obsługiwane w przypadku typu kompozycji "klucz".
filters[<index>].tags	nie	null	Hrabia Minimum: 0 Maksimum: 5
tags	nie	{}
composition_type	nie	key
retention_period	nie	Warstwa Standardowa 2592000 (30 dni) Warstwa Bezpłatna 604800 (7 dni)	Warstwa Standardowa Minimum: 3600 (1 godzina) Maksimum: 7776000 (90 dni) Warstwa Bezpłatna Minimum: 3600 (1 godzina) Maksimum: 604800 (7 dni)

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
}

Odpowiedzi:

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
}

Stan nowo utworzonej migawki to provisioning. Gdy migawka zostanie w pełni aprowizowana, stan zostanie zaktualizowany do readyelementu . Klienci mogą sondować migawkę, aby poczekać na gotowość migawki przed wyświetleniem skojarzonej z nią wartości klucza. Aby wykonać zapytanie o dodatkowe informacje o operacji, zapoznaj się z sekcją tworzenia migawki sondowania.

Jeśli migawka już istnieje, zostanie zwrócona następująca odpowiedź:

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

Tworzenie migawek sondowania

Odpowiedź żądania utworzenia migawki zwraca Operation-Location nagłówek.

Odpowiedzi:

HTTP/1.1 201 Created
...
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

Stan operacji aprowizacji migawki można znaleźć w identyfikatorze URI znajdującym się w pliku Operation-Location. Klienci mogą sondować ten obiekt stanu, aby upewnić się, że migawka jest aprowizowana przed wyświetleniem skojarzonego z nim klucza wartości.

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

Odpowiedź:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "{id}",
    "status": "Succeeded",
    "error": null
}

Jeśli podczas aprowizacji migawki wystąpi jakikolwiek błąd, error właściwość zawiera szczegółowe informacje opisujące błąd.

{
    "id": "{name}",
    "status": "Failed",
    "error": {
      "code": "QuotaExceeded",
      "message": "The allotted quota for snapshot creation has been surpassed."
    }
}

Archiwum (poprawka)

Migawkę ready w stanie można zarchiwizować. Zarchiwizowana migawka ma przypisaną datę wygaśnięcia na podstawie okresu przechowywania ustalonego w momencie jego utworzenia. Po upływie daty wygaśnięcia migawka zostanie trwale usunięta. W dowolnym momencie przed datą wygaśnięcia elementy migawki nadal mogą być wyświetlane.

Archiwizowanie migawki, która archived już nie ma wpływu na migawkę.

Wymagane: {name}, , {status}{api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "archived"
}

Odpowiedź: Zwraca zarchiwizowana migawka

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

Archiwizowanie migawki, która jest obecnie w provisioning stanie lub failed , jest nieprawidłową operacją.

Odpowiedź:

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
}

Odzyskiwanie (poprawka)

Migawkę w archived stanie można odzyskać. Po odzyskaniu migawki data wygaśnięcia migawki zostanie usunięta.

Odzyskiwanie migawki, która ready już nie ma wpływu na migawkę.

Wymagane: {name}, , {status}{api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "ready"
}

Odpowiedź: Zwróć odzyskaną migawkę

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

{
  "etag": "90dd86e2885440f3af9398ca392095b9",
  "name": "{name}",
  "status": "ready",
  ...
}

Odzyskiwanie migawki, która jest obecnie w provisioning stanie lub failed , jest nieprawidłową operacją.

Odpowiedź:

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
}

Archiwizowanie/odzyskiwanie migawki (warunkowo)

Aby zapobiec warunkom wyścigu, użyj If-Match nagłówków lub If-None-Match zażądaj. Argument etag jest częścią reprezentacji migawki. Jeśli If-Match operacja zostanie pominięta, If-None-Match operacja jest bezwarunkowa.

Następująca odpowiedź aktualizuje zasób tylko wtedy, gdy bieżąca reprezentacja jest zgodna z określoną wartością etag:

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

Następująca odpowiedź aktualizuje zasób tylko wtedy, gdy bieżąca reprezentacja nie jest zgodna z określoną wartością etag:

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

Odpowiedzi

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

HTTP/1.1 412 PreconditionFailed

Wyświetlanie listy wartości klucza migawki

Wymagane: {name}, {api-version}

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

Uwaga

Próba wyświetlenia listy elementów migawki, które nie znajdują się w ready stanie lub archived spowoduje pustą odpowiedź na listę.

Żądanie określonych pól

Użyj opcjonalnego $select parametru ciągu zapytania i podaj rozdzielaną przecinkami listę żądanych pól. $select Jeśli parametr zostanie pominięty, odpowiedź zawiera zestaw domyślny.

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

Udostępnij za pośrednictwem

Snapshot

Operacje

Wymagania wstępne

Składnia

Pobieranie migawki

Pobieranie (warunkowo)

Wyświetlanie listy migawek

Filtrowanie

Obsługiwane filtry

Żądanie określonych pól

Utwórz migawkę

Tworzenie migawek sondowania

Archiwum (poprawka)

Odzyskiwanie (poprawka)

Archiwizowanie/odzyskiwanie migawki (warunkowo)

Wyświetlanie listy wartości klucza migawki

Żądanie określonych pól

Opinia

Dodatkowe zasoby