Snapshot

La risorsa snapshot non è disponibile nell'API versione 1.0.

Uno snapshot è una risorsa identificata in modo univoco dal nome. Vedere i dettagli per ogni operazione.

Operazioni

• Recupero
• Elencare più
• Creazione
• Archivio/Ripristino
• Elencare i valori chiave

Prerequisiti

• Tutte le richieste HTTP devono essere autenticate. Vedere la sezione relativa all'autenticazione.
• Tutte le richieste HTTP devono fornire esplicitamente api-version. Vedere la sezione relativa al controllo delle versioni.

Sintassi

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

Ottenere uno snapshot

Obbligatorio: {name}, {api-version}

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

Risposte:

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
}

Se non esiste uno snapshot con il nome specificato, viene restituita la risposta seguente:

HTTP/1.1 404 Not Found

Get (in modo condizionale)

Per migliorare la memorizzazione nella cache del client, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione dello snapshot. Per altre informazioni, vedere le sezioni 14.24 e 14.26.

La richiesta seguente recupera lo snapshot solo se la rappresentazione corrente non corrisponde all'oggetto specificato etag:

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

Risposte:

HTTP/1.1 304 NotModified

O

HTTP/1.1 200 OK

Elencare gli snapshot

Facoltativo: name se non specificato, implica qualsiasi nome. Facoltativo: status se non specificato, implica qualsiasi stato.

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

Risposta:

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

Per altre opzioni, vedere la sezione "Filtro" più avanti in questo articolo.

Impaginazione

Il risultato viene impaginato se il numero di elementi restituiti supera il limite di risposta. Seguire le intestazioni di risposta facoltative Link e usare rel="next" per la navigazione. In alternativa, il contenuto fornisce un collegamento successivo sotto forma di @nextLink proprietà . L'URI collegato include l'argomento api-version .

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

Risposta:

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

Filtri

È supportata una combinazione di name filtri e status . Usare i parametri facoltativi name e status della stringa di query.

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

Filtri supportati

Caratteri riservati

*, \, ,

Se un carattere riservato fa parte del valore , deve essere preceduto da un carattere di escape tramite \{Reserved Character}. È anche possibile eseguire l'escape dei caratteri non validi.

Convalida dei filtri

Se la convalida del filtro non riesce, la risposta è HTTP 400 con i dettagli dell'errore:

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
}

Esempi

• Tutte le date

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

• Il nome dello snapshot inizia con abc

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

• Il nome dello snapshot inizia con abc e lo stato è pronto o archiviato

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

Richiedi campi specifici

Usare il parametro facoltativo $select della stringa di query e specificare un elenco delimitato da virgole di campi richiesti. Se il $select parametro viene omesso, la risposta contiene il set predefinito.

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

Crea snapshot

parameters

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
}

Risposte:

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
}

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
}

Risposte:

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
}

Lo stato dello snapshot appena creato è provisioning. Dopo il provisioning completo dello snapshot, lo stato viene aggiornato a ready. I client possono eseguire il polling dello snapshot per attendere che lo snapshot sia pronto prima di elencare i relativi valori di chiave associati. Per eseguire query su informazioni aggiuntive sull'operazione, fare riferimento alla sezione relativa alla creazione di snapshot di polling.

Se lo snapshot esiste già, viene restituita la risposta seguente:

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

Creazione di snapshot di polling

La risposta di una richiesta di creazione snapshot restituisce un'intestazione Operation-Location .

Risposte:

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

Lo stato dell'operazione di provisioning dello snapshot è disponibile nell'URI contenuto in Operation-Location. I client possono eseguire il polling di questo oggetto di stato per assicurarsi che venga effettuato il provisioning di uno snapshot prima di elencare i valori chiave associati.

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

Risposta:

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

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

Se si verifica un errore durante il provisioning dello snapshot, la error proprietà contiene dettagli che descrivono l'errore.

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

Archivio (patch)

È possibile archiviare uno snapshot nello ready stato . A uno snapshot archiviato viene assegnata una data di scadenza, in base al periodo di conservazione stabilito al momento della creazione. Al termine della data di scadenza, lo snapshot verrà eliminato definitivamente. In qualsiasi momento prima della data di scadenza, gli elementi dello snapshot possono comunque essere elencati.

L'archiviazione di uno snapshot già archived non influisce sullo snapshot.

• Obbligatorio: {name}, {status}, {api-version}

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

{
  "status": "archived"
}

Risposta: Restituire lo snapshot archiviato

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

L'archiviazione di uno snapshot attualmente nello provisioning stato o failed è un'operazione non valida.

Risposta:

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
}

Ripristino (patch)

È possibile recuperare uno snapshot nello archived stato . Dopo il ripristino dello snapshot, la data di scadenza dello snapshot viene rimossa.

Il ripristino di uno snapshot già ready non influisce sullo snapshot.

• Obbligatorio: {name}, {status}, {api-version}

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

{
  "status": "ready"
}

Risposta: Restituire lo snapshot ripristinato

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

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

Il ripristino di uno snapshot attualmente nello provisioning stato o failed è un'operazione non valida.

Risposta:

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
}

Archivio/ripristino dello snapshot (in modo condizionale)

Per evitare race condition, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione dello snapshot. Se If-Match o If-None-Match vengono omessi, l'operazione è incondizionato.

La risposta seguente aggiorna la risorsa solo se la rappresentazione corrente corrisponde all'oggetto specificato etag:

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

La risposta seguente aggiorna la risorsa solo se la rappresentazione corrente non corrisponde all'oggetto specificato etag:

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

Risposte

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

O

HTTP/1.1 412 PreconditionFailed

Elencare i valori chiave-chiave snapshot

Obbligatorio: {name}, {api-version}

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

Richiedi campi specifici

Usare il parametro facoltativo $select della stringa di query e specificare un elenco delimitato da virgole di campi richiesti. Se il $select parametro viene omesso, la risposta contiene il set predefinito.

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