Instantâneo

Artigo
07/13/2023

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

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

Operations

Obter
Listar várias
Criar
Arquivar/recuperar
Listar chave-valores

Pré-requisitos

Todas as solicitações HTTP deverão ser autenticadas. Confira a seção autenticação.
Todas as solicitações HTTP deverão fornecer uma api-version explícita. Confira a seção 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 os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de instantâneo. Para obter mais informações, confira as seções 14.24 e 14.26.

A solicitação a seguir recupera o instantâneo somente se a representação atual não corresponder ao etag especificado:

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 o próximo link da propriedade @nextLink. O URI vinculado inclui o argumento api-version.

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

Há suporte para uma combinação de filtragens name e status. Use os parâmetros de cadeia de caracteres de consulta opcionais name e status.

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

Filtros com suporte

Filtro de nome	Efeito
`name` é omitido ou `name=*`	Corresponde a instantâneos com qualquer nome
`name=abc`	Corresponde a um instantâneo chamado abc
`name=abc*`	Corresponde aos instantâneos com nomes que começam com abc
`name=abc,xyz`	Corresponde aos instantâneos com nomes abc ou xyz (limitado a 5 CSVs)

Filtro de status	Efeito
`status` é omitido ou `status=*`	Corresponde aos instantâneos com qualquer status
`status=ready`	Corresponde aos instantâneos com um status pronto
`status=ready,archived`	Corresponde a instantâneos com status prontos ou arquivados (limitado a 5 CSV)

Caracteres reservados

*, \, ,

Caso um caractere reservado faça parte do valor, ele deverá ser ignorado usando \{Reserved Character}. Os caracteres não reservados também podem ser ignorados.

Validação de filtro

Caso ocorra um erro de validação de filtro, a resposta será HTTP 400 com os 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 snapshot 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}
```

Campos específicos da solicitação

Use o parâmetro opcional de cadeia de caracteres de consulta $select e forneça uma lista separada por vírgulas dos campos solicitados. Caso o parâmetro $select seja omitido, a resposta conterá o conjunto padrão.

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

Create snapshot

parameters

Nome da propriedade	Obrigatório	Valor padrão	Validação
name	sim	N/D	Comprimento máximo: 256
filtros	sim	N/D	Contagem mínimo: 1 máximo: 3
filters[<index>].key	sim	n/a
marcas	não	{}
filters[<index>].label	não	nulo	Não há suporte para filtros de rótulo de várias correspondências (por exemplo: "*", "vírgula, separado") com o tipo de composição 'key'.
composition_type	não	chave
retention_period	não	Camada padrão 2592000 (30 dias) Camada gratuita 604800 (7 dias)	Camada padrão mínimo: 3600 (1 hora) máximo: 7776000 (90 dias) Camada gratuita 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 instantâneo recém-criado será "provisionamento". Depois que o instantâneo for totalmente provisionado, o status será atualizado para "pronto". Os clientes podem sondar o instantâneo para aguardar o instantâneo estar pronto antes de listar seus valores-chave associados. Para consultar informações adicionais sobre a operação, consulte a seção 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âneo de sondagem

A resposta de uma solicitação de criação instantâneo retorna um cabeçalho Operation-Location.

Respostas:

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

O status da operação de provisionamento de instantâneo 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-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 propriedade error conterá detalhes que descrevem o erro.

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

Arquivo morto (Patch)

Uma instantâneo no estado ready 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 validade for aprovada, 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 instantâneo que já está archived não afeta o instantâneo.

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 estado provisioning 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)

Uma instantâneo no estado archived pode ser recuperado. Depois que o instantâneo for recuperado, a data de validade do instantâneo será removida.

Arquivar um instantâneo que já está ready não afeta o instantâneo.

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 instantâneo recuperado

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

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

Recuperar um instantâneo que está atualmente no estado provisioning 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 instantâneo (condicionalmente)

Para evitar condições de corrida, use os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de 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 ao etag especificado:

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 ao etag especificado:

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 instantâneo valores-chave

Obrigatório: {name}, {api-version}

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

Observação

Tentar listar os itens de um instantâneo que não está no estado ready ou archived resultará em uma resposta de lista vazia.

Campos específicos da solicitação

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

Compartilhar via

Instantâneo

Operations

Pré-requisitos

Sintaxe

Obter instantâneo

Obter (condicionalmente)

Listar instantâneos

Filtragem

Filtros com suporte

Campos específicos da solicitação

Create snapshot

Criação de instantâneo de sondagem

Arquivo morto (Patch)

Recuperar (Patch)

Arquivar/recuperar instantâneo (condicionalmente)

Listar instantâneo valores-chave

Campos específicos da solicitação

Comentários

Comentários

Recursos adicionais