Instantâneo

Artigo
11/19/2023

Um instantâneo é um recurso identificado exclusivamente pelo seu nome. Veja os detalhes de cada operação.

Este artigo aplica-se à API versão 2022-11-01-preview.

Operations

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

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

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 opções adicionais, 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

No caso de um erro de validação de filtro, a resposta é 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

Tudo

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 parâmetro for omitido, a resposta conterá o $select 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/a	Comprimento máximo: 256
filtros	sim	n/a	Contagem mínimo: 1 Máximo: 3
filtros[<index>].key	sim	n/a
etiquetas	não	{}
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'.
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": {                           // 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
}

O status do snapshot recém-criado será "provisionamento". Quando o snapshot estiver totalmente provisionado, o status será atualizado para "pronto". 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, você receberá a seguinte resposta:

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 descrevendo 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 receberá 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 é recuperado, a data de expiração do snapshot é 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
...

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

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

Partilhar via

Instantâneo

Operations

Pré-requisitos

Sintaxe

Obter instantâneo

Obter (condicionalmente)

Listar instantâneos

Filtragem

Filtros suportados

Solicitar campos específicos

Criar instantâneo

Criação de instantâneos de sondagem

Arquivo (Patch)

Recuperar (Patch)

Arquivar/recuperar snapshot (condicionalmente)

Listar valores-chave de instantâneo

Solicitar campos específicos

Recursos adicionais