For the complete documentation index, see llms.txt. This page is also available as Markdown.

Snapshots

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

Os snapshots são criados diariamente, semanalmente, mensalmente e anualmente. Cada um contém o conjunto de active entities que mudou desde o snapshot anterior para esse intervalo.

Os snapshots conterão versões conflitantes das mesmas entities (ou seja, 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 eliminar inactive files, não é garantido que versões desatualizadas 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 snapshots diários), os seus metadados indicam quais os ficheiros 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 isto abaixo), mantendo a entity mais recente referenciada por cada pointer descoberto ao longo do caminho.

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

Descoberta de Snapshots

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

Campo
Valor

generationTimestamp

O timestamp UTC Unix quando este snapshot foi criado.

hash

O snapshot file.

numberOfEntities

O número de entradas no ficheiro do snapshot.

replacedSnapshotHashes

Um array com os hash de quaisquer snapshots substituídos por este.

timeRange.initTimestamp

O timestamp UTC Unix (em milissegundos) para o início do intervalo do snapshot.

timerange.endTimestamp

O timestamp UTC Unix (em milissegundos) para o fim do intervalo do snapshot.

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 os active entities associados criados ou atualizados nesse intervalo.

Os ficheiros do snapshot começam com esta linha exata:

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

Campo
Valor

entityId

O identificador imutável para este entity.

entityType

Um de scene, perfil, wearable, emote, store ou outfits.

pointers

Um array de pointers que resolvem (ou resolviam) para esta entity.

entityTimestamp

O timestamp UTC Unix (em milissegundos) quando esta entity foi carregada.

authChain

O cadeia de autenticação para esta entity.

Uma entrada típica parece assim:

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

Iniciar um índice de Entities

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

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

Em pseudo-código:

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

Os ficheiros de snapshot 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 índice de Entities

Os clients que mantêm um índice de entities atualizado podem fazer chamadas periódicas ao snapshots endpoint, e determinar se devem descarregar cada ficheiro tendo em conta:

  • 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 tiverem de ser processados novos snapshots, pode usar-se a mesma estratégia acima para atualizar um conjunto de dados existente.

Exemplos

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

Atualizado