Instantâneo
O recurso de instantâneo não está disponível na API versão 1.0.
Um instantâneo é um recurso identificado exclusivamente pelo seu nome. Veja os detalhes de cada operação.
Operações
- Obtenção
- Listar vários
- Criar
- Arquivar/Recuperar
- Listar valores-chave
Pré-requisitos
- Todas as solicitações HTTP devem ser autenticadas. Consulte a seção de autenticação .
- Todas as solicitações HTTP devem fornecer arquivos .
api-version
Consulte a seção de controle de versão.
Sintaxe
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>]
}
Obter instantâneo
Obrigatório: {name}
, {api-version}
GET /snapshots/{name}?api-version={api-version}
Respostas:
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 um instantâneo com o nome fornecido não existir, a seguinte resposta será retornada:
HTTP/1.1 404 Not Found
Obter (condicionalmente)
Para melhorar o cache do cliente, use If-Match
ou If-None-Match
solicite cabeçalhos. O etag
argumento faz parte da representação do instantâneo. Para mais informações, ver secções 14.24 e 14.26.
A solicitação a seguir recupera o instantâneo somente se a representação atual não corresponder à especificada etag
:
GET /snapshot/{name}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "{etag}"
Respostas:
HTTP/1.1 304 NotModified
Ou
HTTP/1.1 200 OK
Listar instantâneos
Opcional: name
(Se não for especificado, implica qualquer nome.) Opcional: status
(Se não for especificado, implica qualquer status.)
GET /snapshots?name=prod-*&api-version={api-version} HTTP/1.1
Resposta:
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshotset+json; charset=utf-8
Para obter mais opções, consulte a seção "Filtragem" mais adiante neste artigo.
Paginação
O resultado será paginado se o número de itens retornados exceder o limite de resposta. Siga os cabeçalhos de resposta opcionais Link
e use rel="next"
para navegação.
Como alternativa, o conteúdo fornece um próximo link na forma da @nextLink
propriedade. O URI vinculado inclui o api-version
argumento.
GET /snapshots?api-version={api-version} HTTP/1.1
Resposta:
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}"
}
Filtragem
Uma combinação de name
e status
filtragem é suportada.
Use os parâmetros opcionais name
e status
de seqüência de caracteres de consulta.
GET /snapshots?name={name}&status={status}&api-version={api-version}
Filtros suportados
Filtro de nome | Efeito |
---|---|
name for omitida ou name=* |
Corresponde instantâneos com qualquer nome |
name=abc |
Corresponde a um instantâneo chamado abc |
name=abc* |
Corresponde instantâneos com nomes que começam com abc |
name=abc,xyz |
Corresponde instantâneos com nomes abc ou xyz (limitado a 5 CSV) |
Filtro de status | Efeito |
---|---|
status for omitida ou status=* |
Corresponde instantâneos com qualquer status |
status=ready |
Corresponde instantâneos com um status pronto |
status=ready,archived |
Corresponde instantâneos com status pronto ou arquivado (limitado a 5 CSV) |
Caracteres reservados
*
, \
, ,
Se um caractere reservado fizer parte do valor, ele deverá ser escapado usando \{Reserved Character}
. Caracteres não reservados também podem ser escapados.
Validação do filtro
Se a validação do filtro falhar, a resposta será HTTP 400
com detalhes do erro:
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
}
Exemplos
Todos
GET /snapshots?api-version={api-version}
O nome do instantâneo começa com abc
GET /snapshot?name=abc*&api-version={api-version}
O nome do instantâneo começa com abc e o status é igual a pronto ou arquivado
GET /snapshot?name=abc*&status=ready,archived&api-version={api-version}
Solicitar campos específicos
Use o parâmetro opcional $select
de seqüência de caracteres de consulta e forneça uma lista separada por vírgulas de campos solicitados. Se o $select
parâmetro for omitido, a resposta conterá o conjunto padrão.
GET /snapshot?$select=name,status&api-version={api-version} HTTP/1.1
Criar instantâneo
parameters
Nome de Propriedade | Necessário | Default value | Validação |
---|---|---|---|
nome | sim | n/d | Comprimento Máximo: 256 |
filtros | sim | n/d | Contagem Mínimo: 1 Máximo: 3 |
filtros[<índice>].key | sim | n/d | |
filtros[<índice>].label | não | nulo | Os filtros de etiquetas multicorrespondência (por exemplo: "*", "vírgula, separado") não são suportados com o tipo de composição 'chave'. |
etiquetas | não | {} | |
composition_type | não | key | |
retention_period | não | Nível padrão 2592000 (30 dias) Nível gratuito 604800 (sete dias) |
Nível padrão Mínimo: 3600 (uma hora) Máximo: 7776000 (90 dias) Nível gratuito Mínimo: 3600 (uma hora) Máximo: 604800 (sete dias) |
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
}
Respostas:
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
}
Nome de Propriedade | Necessário | Default value | Validação |
---|---|---|---|
nome | sim | n/d | Comprimento Máximo: 256 |
filtros | sim | n/d | Contagem Mínimo: 1 Máximo: 3 |
filtros[<índice>].key | sim | n/d | |
filtros[<índice>].label | não | nulo | Os filtros de etiquetas multicorrespondência (por exemplo: "*", "vírgula, separado") não são suportados com o tipo de composição 'chave'. |
filtros[<índice>].tags | não | nulo | Contagem Mínimo: 0 Máximo: 5 |
etiquetas | não | {} | |
composition_type | não | key | |
retention_period | não | Nível padrão 2592000 (30 dias) Nível gratuito 604800 (7 dias) |
Nível padrão Mínimo: 3600 (1 hora) Máximo: 7776000 (90 dias) Nível gratuito Mínimo: 3600 (1 hora) Máximo: 604800 (7 dias) |
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
}
Respostas:
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
}
O status do instantâneo recém-criado é provisioning
.
Quando o snapshot é totalmente provisionado, o status é atualizado para ready
.
Os clientes podem sondar o snapshot para aguardar que ele esteja pronto antes de listar seus valores-chave associados.
Para consultar informações adicionais sobre a operação, consulte a seção de criação de instantâneo de sondagem.
Se o instantâneo já existir, a seguinte resposta será retornada:
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": ""
}
Criação de instantâneos de sondagem
A resposta de uma solicitação de criação de instantâneo retorna um Operation-Location
cabeçalho.
Respostas:
HTTP/1.1 201 Created
...
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
O status da operação de provisionamento de snapshot pode ser encontrado no URI contido em Operation-Location
.
Os clientes podem sondar esse objeto de status para garantir que um instantâneo seja provisionado antes de listar seus valores de chave associados.
GET {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
Resposta:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "{id}",
"status": "Succeeded",
"error": null
}
Se ocorrer algum erro durante o provisionamento do instantâneo, a error
propriedade conterá detalhes que descrevem o erro.
{
"id": "{name}",
"status": "Failed",
"error": {
"code": "QuotaExceeded",
"message": "The allotted quota for snapshot creation has been surpassed."
}
}
Arquivo (Patch)
Um instantâneo no ready
estado pode ser arquivado.
Um instantâneo arquivado recebe uma data de validade, com base no período de retenção estabelecido no momento de sua criação.
Depois que a data de expiração passar, o instantâneo será excluído permanentemente.
A qualquer momento antes da data de validade, os itens do instantâneo ainda podem ser listados.
Arquivar um snapshot que já archived
está não afeta o snapshot.
- Obrigatório:
{name}
,{status}
,{api-version}
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"status": "archived"
}
Resposta: Retornar o instantâneo arquivado
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"
}
Arquivar um instantâneo que está atualmente no provisioning
estado ou failed
é uma operação inválida.
Resposta:
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
}
Recuperar (Patch)
Um instantâneo no archived
estado pode ser recuperado.
Depois que o snapshot for recuperado, a data de expiração do snapshot será removida.
A recuperação de um snapshot que já ready
está não afeta o snapshot.
- Obrigatório:
{name}
,{status}
,{api-version}
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"status": "ready"
}
Resposta: Retornar o snapshot recuperado
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
{
"etag": "90dd86e2885440f3af9398ca392095b9",
"name": "{name}",
"status": "ready",
...
}
A recuperação de um instantâneo que está atualmente no provisioning
estado ou failed
é uma operação inválida.
Resposta:
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
}
Arquivar/recuperar snapshot (condicionalmente)
Para evitar condições de corrida, use If-Match
ou If-None-Match
solicite cabeçalhos. O etag
argumento faz parte da representação do instantâneo.
Se If-Match
ou If-None-Match
forem omitidos, a operação é incondicional.
A resposta a seguir atualiza o recurso somente se a representação atual corresponder à especificada etag
:
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"
A resposta a seguir atualiza o recurso somente se a representação atual não corresponder à especificada etag
:
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"
Respostas
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
Ou
HTTP/1.1 412 PreconditionFailed
Listar valores-chave de instantâneo
Obrigatório: {name}
, {api-version}
GET /kv?snapshot={name}&api-version={api-version}
Nota
A tentativa de listar os itens de um instantâneo que não está no ready
estado ou archived
resultará em uma resposta de lista vazia.
Solicitar campos específicos
Use o parâmetro opcional $select
de seqüência de caracteres de consulta e forneça uma lista separada por vírgulas de campos solicitados. Se o $select
parâmetro for omitido, a resposta conterá o conjunto padrão.
GET /kv?snapshot={name}&$select=key,value&api-version={api-version} HTTP/1.1