> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Obter política de snapshot
> Leia a agenda, a janela de retenção e o estado de execução de uma política.
Uma execução falhada é apenas um aviso: `enabled` não se move e a política nunca relata `error`. Verifique `faults` quando uma programação parou de produzir snapshots — ele carrega a razão pela qual a execução mais recente não tomou nenhum (quota esgotada, volume mid-extend, …) e está vazio após uma execução que teve sucesso. `next_run_at` e `last_run_at` dizem onde no ciclo a política está.
Requer a ação do IAM **`storage:GetSnapshotPolicy`**. Consulte [permissões de armazenamento](/pt/storage/permissions) para obter a lista completa, o que cada uma abrange e um exemplo de política.
## OpenAPI
````yaml /pt/api-reference/specs/storage.yaml get /v1/snapshot-policies/{policy_id}
openapi: 3.0.3
info:
title: API de armazenamento Basaltic
version: 1.0.0
description: >
As referências de armazenamento aceitam UUIDs, CRNs ou nomes de escopo em um
campo. Os nomes de snapshot requerem um volume fixo; source_snapshot aceita
somente UUID ou CRN aninhado. Bloqueie volumes com seus snapshots e
políticas de snapshot, além de gerenciamento de bucket para armazenamento de
objetos. O próprio protocolo de fio S3 é servido separadamente em
`objects.{region}.basaltic.cloud`.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://storage.{region}.basaltic.sh
description: Endpoint de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de região
security:
- BearerAuth: []
paths:
/v1/snapshot-policies/{policy_id}:
get:
tags:
- Storage
summary: Obter política de snapshot
description: >
Leia a agenda, a janela de retenção e o estado de execução de uma
política.
Uma execução falhada é apenas um aviso: `enabled` não se move e a
política nunca relata `error`. Verifique `faults` quando uma programação
parou de produzir snapshots — ele carrega a razão pela qual a execução
mais recente não tomou nenhum (quota esgotada, volume mid-extend, …) e
está vazio após uma execução que teve sucesso. `next_run_at` e
`last_run_at` dizem onde no ciclo a política está.
operationId: getSnapshotPolicy
parameters:
- $ref: '#/components/parameters/SnapshotPolicyId'
responses:
'200':
description: Detalhes da política de snapshot
content:
application/json:
schema:
$ref: '#/components/schemas/SnapshotPolicyResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
components:
parameters:
SnapshotPolicyId:
name: policy_id
in: path
description: ID da política de snapshot
required: true
schema:
type: string
format: uuid
example: 3c9f1b2e-6d4a-4e8b-9f1c-2a3b4c5d6e7f
schemas:
SnapshotPolicyResponse:
type: object
properties:
snapshot_policy:
$ref: '#/components/schemas/SnapshotPolicy'
SnapshotPolicy:
type: object
required:
- faults
description: >
Um cronograma anexado a um volume: tirar um instantâneo a cada
`interval_minutes`, em seguida, manter no máximo `retention_count` dos
instantâneos criados por essa política.
A retenção só apaga instantâneos criados pela própria política (aqueles
que carregam seu `snapshot_policy_id`) — um instantâneo feito
manualmente nunca é removido. Ele também nunca exclui um instantâneo do
qual algo depende: um instantâneo do qual um volume foi criado,
incluindo uma restauração ainda em andamento, é ignorado e reexaminado
mais tarde.
properties:
id:
type: string
format: uuid
readOnly: true
example: 3c9f1b2e-6d4a-4e8b-9f1c-2a3b4c5d6e7f
crn:
type: string
readOnly: true
description: Nome do recurso da nuvem (baseado em nome, com escopo de região).
example: crn:storage:sa-saopaulo-1:my-account:snapshot-policy/nightly
volume_id:
type: string
format: uuid
description: >-
O volume ao qual esta agenda está anexada. Um volume suporta até 16
políticas independentes.
example: 5f8d2c1a-9b3e-4d7a-8c6f-1e2a3b4c5d6e
name:
description: >-
Os nomes de recursos não devem começar com o prefixo literal crn: ou
ser UUIDs (formas canônicas, compactas, entre colchetes ou
urn:uuid:, em qualquer caso).
type: string
maxLength: 128
example: nightly
description:
type: string
example: Nightly snapshots of the database volume
enabled:
type: boolean
description: >
A desativação pausa toda a política — sem snapshots agendados e sem
retenção. Uma programação pausada que continuava a colher apagaria o
histórico enquanto você estava olhando para ele.
example: true
interval_minutes:
$ref: '#/components/schemas/SnapshotIntervalMinutes'
retention_count:
$ref: '#/components/schemas/SnapshotRetentionCount'
retention_days:
$ref: '#/components/schemas/SnapshotRetentionDays'
next_run_at:
type: string
format: date-time
readOnly: true
description: >
Quando o próximo snapshot deve ser feito. Re-stamped para `now +
interval_minutes` cada vez que a política dispara - nunca para
`previous + interval` - então uma janela perdida enquanto a região
estava ocupada custa um instantâneo, não um por janela perdida.
example: '2026-01-16T00:00:00Z'
last_run_at:
type: string
format: date-time
readOnly: true
description: >-
Quando a política disparou pela última vez. Ausente até o primeiro
incêndio.
example: '2026-01-15T00:00:00Z'
faults:
type: array
readOnly: true
description: >-
Falhas de aviso ativas, mais recentes primeiro; vazio quando
saudável. As políticas não têm status de erro e as falhas nunca
mudam. A execução e a retenção se recuperam de forma independente; o
histórico resolvido é mantido internamente.
items:
$ref: '#/components/schemas/Fault'
tags:
$ref: '#/components/schemas/Tags'
created_at:
type: string
format: date-time
readOnly: true
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
readOnly: true
example: '2026-01-15T09:30:00Z'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de erro identificando o tipo de erro
example: INVALID_INPUT
message:
type: string
description: Mensagem de erro legível pelo ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores não sensíveis opcionais para interpolação de erros
localizados, codificados por código de erro. Nunca presente para
erros de servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuração
example: 550e8400-e29b-41d4-a716-446655440000
SnapshotIntervalMinutes:
type: integer
minimum: 1
maximum: 43200
description: >
Minutos entre instantâneos — um intervalo mínimo, não uma cadência
exata. Uma passagem periódica leva o que foi devido e re-baseia a
próxima execução de cada política no momento em que foi executada, então
um snapshot aterrissa em ou após `interval_minutes` e nunca antes, e
pode aterrissar um minuto ou dois depois quando a passagem está ocupada.
Uma janela que o passe perde custa um instantâneo em vez de produzir uma
explosão de recuperação depois.
O limite mínimo é de um minuto, porque é esse tempo que avalia o
calendário e nada mais fino pode ser honrado; o limite máximo é de 30
dias. Intervalos sub-horais multiplicam o churn de snapshots e contam
contra a cota de `snapshots`, então escolha o maior intervalo que atenda
ao seu objetivo de ponto de recuperação.
example: 1440
SnapshotRetentionCount:
type: integer
minimum: 1
maximum: 256
description: >
Quantos instantâneos dessa política devem ser mantidos. Quando um
incêndio leva a contagem além disso, o mais velho vai primeiro.
example: 7
SnapshotRetentionDays:
type: integer
minimum: 0
maximum: 3650
default: 0
description: >
Limite de idade opcional, aplicado em cima de `retention_count`: um
instantâneo fora da janela EITHER é colhido. 0 significa sem idade
limitada. O único snapshot mais recente está isento do limite de idade,
portanto, um volume que não pode ser capturado por mais tempo do que a
janela nunca perde todo o seu histórico.
example: 30
Fault:
type: object
required:
- code
- severity
- message
- details
- first_at
- last_at
- occurrences
properties:
code:
type: string
description: >-
Código estável legível por máquina pertencente à operação de
relatório.
example: BACKUP_FAILED
severity:
type: string
enum:
- error
- warning
message:
type: string
example: Backup upload failed.
details:
type: object
nullable: true
additionalProperties: true
description: >-
Contexto estruturado; cadeias de caracteres legadas são preservadas
em legacy_text.
first_at:
type: string
format: date-time
description: Primeira observação nesta série de ocorrências ativas.
last_at:
type: string
format: date-time
description: Última observação nesta série de ocorrências ativas.
occurrences:
type: integer
minimum: 1
example: 1
Tags:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
responses:
Unauthorized:
description: Autenticação necessária ou token inválido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permissões insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: Página não encontrada
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
request_id: 550e8400-e29b-41d4-a716-446655440000
InternalServerError:
description: Erro interno do servidor
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INTERNAL_ERROR
message: An internal error occurred
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Um token bearer OAuth 2.0, enviado como `Authorization: Bearer `.
Esta é a forma recomendada de autenticação.
Obtenha o token trocando o par de chaves de acesso de uma conta de
serviço em `POST /v1/oauth/token` com `grant_type=client_credentials`.
Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis
com OAuth podem obter e renovar o token para você.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso
também serve como credencial AWS SigV4 para o endpoint de objetos
compatível com S3, que aceita somente esse método de autenticação.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.