Snapshots

Os content servers irão compilar periodicamente resumos das active entities que estão a alojar, chamados snapshots. São regulares files e podem ser descarregados usando o seu identificador.

Os snapshots são criados numa base diária, semanal, mensal e anual. Cada um contém o conjunto de active entities que mudou desde o snapshot anterior para esse intervalo.

Os snapshots conterão versões conflituantes das mesmas entities (isto é, diferentes manifest files associados ao mesmo pointer), à medida que são atualizados. Ao analisá-los, os clients devem manter a versão no snapshot mais recente. Como os content servers podem apagar files inativos, não é garantido que versões obsoletas de entities estejam disponíveis para download.

Quando um novo snapshot substitui os mais antigos (por exemplo, um snapshot semanal que combina uma série de diários), os seus metadados indicam quais os files anteriores que são substituídos, para que os clients não precisem de os descarregar.

O conjunto completo de active entities pode ser descoberto combinando todos os snapshots disponíveis (mais sobre isso abaixo), mantendo a entity mais recente referenciada por cada pointer descoberto ao longo do caminho.

Pode experimentar snapshots com código funcional na prática secção.

Descobrir Snapshots

Para localizar o conjunto atual de snapshots, use o snapshots endpoint. A resposta contém um array de itens com estes campos:

Campo	Valor
generationTimestamp	O timestamp Unix UTC quando este snapshot foi criado.
hash	O snapshot file.
numberOfEntities	O número de entradas no snapshot file.
replacedSnapshotHashes	Um array com os hash de quaisquer snapshots substituídos por este.
timeRange.initTimestamp	O timestamp Unix UTC (em milissegundos) para o início do intervalo do snapshot.
timerange.endTimestamp	O timestamp Unix UTC (em milissegundos) para o fim do intervalo.

Por exemplo:

{
  "generationTimestamp": 1684979298844,
  "hash": "bafybeiflmm46nr4vv2h3wuzbx3pukcz7ju4fhbfzt6yxmoo533uktlgru4",
  "numberOfEntities": 12345,
  "replacedSnapshotHashes": [ "bafybeicw6x75ieaxfwynekbyhpcsgctpjkt6cb4j6oa7s57qjj6e4b5phd" ],
  "timeRange": {
     "initTimestamp": 1684281600000,
     "endTimestamp": 1684886400000
  }
}

Descarregar Snapshots

Usando o hash campo de um snapshot, os clients podem descarregar as entities associadas criadas ou atualizadas nesse intervalo de tempo.

Os snapshot files começam com esta linha exata:

### Decentraland json snapshot

Depois disso, cada linha é um documento JSON que descreve um entity com os seguintes campos:

Campo	Valor
entityId	O identificador imutável para esta entity.
entityType	Um de scene, perfil, wearable, emote, store ou outfits.
pointers	Um array de pointers que resolvem (ou eram usados para resolver) para esta entity.
entityTimestamp	O timestamp Unix UTC (em milissegundos) quando esta entity foi carregada.
authChain	O serializada em JSON para esta entity.

Uma entrada típica tem este aspeto:

{
  "entityId": "bafkreigrvaqynmiglpvewwhn2yd63q5dvagrrt5jbhimzvbrn5kimj5zne",
  "entityType": "wearable",
  "pointers": ["urn:decentraland:matic:collections-v2:0x11a6879861f36cbad632a4e7226816a16139fb33:0"],
  "entityTimestamp": 1671117456129,
  "authChain": [
    // ... payloads e assinaturas da cadeia de autenticação
  ]
}

Se pretender analisar um snapshot linha a linha, lembre-se de saltar (ou, melhor ainda, validar) a primeira linha com o cabeçalho e esteja preparado para lidar com uma linha vazia no fim do file.

Iniciar um Entity Index

Os clients que pretendem indexar todo o conjunto de active entities devem processar todos os snapshots atualmente disponíveis e manter a entity mais recente entity para cada pointer.

A estratégia mais simples é processar os snapshots por ordem cronológica inversa (isto é, do mais recente para o mais antigo), ignorando pointers que já tenham sido descobertos, de modo a manter a referência para a entity mais recente.

Em pseudo-código:

# Descarregue o conjunto atual de snapshots e ordene-os do mais recente para o mais antigo:
snapshots = get_snapshots()
snapshots.sort('timeRange.initTimestamp', DESCENDING)

seen_pointers = set()

# Processe os snapshots, mantendo a entity mais recente para cada pointer:
for snapshot in snapshots:
    items = get_snapshot_items(snapshot) 

    for item in items:
        if any(pointer in seen_pointers for pointer in item.pointers):
            discard(item)
        else:
            keep(item)
            seen_pointers.update(item.pointers)

Como as entities individuais podem ser referenciadas por múltiplos pointers (como é comum no caso de cenas), todos eles devem ser verificados antes de decidir manter ou descartar o item.

Os snapshot files para os intervalos de tempo mais longos podem ser muito grandes. Para fins de desenvolvimento e experimentação que não exijam indexar todo o conjunto de entities, recomenda-se usar os snapshots mais pequenos. O conjunto resultante de entities será incompleto, mas válido.

Atualizar um Entity Index

Os clients que mantêm um entity index atualizado podem fazer chamadas periódicas ao snapshots endpoint e determinar se devem descarregar cada file considerando:

• O snapshot identificado por hash já foi descarregado?

• Está hash na replacedSnapshotHashes lista de outro snapshot que já foi descarregado?

• É o timeRange relevante para os fins atuais?

Se houver novos snapshots a processar, pode usar-se a mesma estratégia acima para atualizar um dataset existente.

Exemplos

Na prática secção, encontrará exemplos de código que funcionam com o sistema de snapshots.