Como Converter o Arquivo de Exportação do Mastodon em um Índice JSON Pesquisável

Você baixou seu arquivo de exportação do Mastodon nas configurações da conta, mas os arquivos estão em formato CSV ou JSON difíceis de pesquisar rapidamente. O arquivo contém suas postagens, seguidores, lista de seguidos, favoritos e outros dados. Este artigo explica como converter esse arquivo de exportação em um único índice JSON pesquisável que você pode abrir em qualquer editor de texto ou importar para uma ferramenta de análise de dados.

O arquivo de exportação do Mastodon inclui vários arquivos, cada um contendo um tipo específico de dados. Um índice JSON combina todos esses arquivos em um documento estruturado com pares chave-valor para cada item. Você usará um script Python para ler o arquivo, analisar cada arquivo e escrever um índice JSON unificado.

Ao final deste guia, você terá um único arquivo JSON que contém todos os seus dados do Mastodon em uma estrutura plana e pesquisável. Você pode consultá-lo com ferramentas JSON padrão ou carregá-lo em uma planilha para análise posterior.

O que o Arquivo de Exportação do Mastodon Contém

Ao solicitar seu arquivo do Mastodon em Configurações > Importar e Exportar > Exportar, o servidor gera um arquivo ZIP com nome como mastodon-export-20250101.zip. Dentro do ZIP, você encontra uma estrutura de pastas com os seguintes arquivos principais:

• outbox.json — Todas as suas postagens públicas no formato ActivityStreams, incluindo boosts e respostas.
• following_accounts.json — Uma lista de contas que você segue, com nome de usuário e URL do servidor.
• followers.json — Uma lista de contas que seguem você.
• lists.json — Quaisquer listas que você criou em sua conta do Mastodon.
• blocks.json — Contas que você bloqueou.
• mutes.json — Contas que você silenciou.
• bookmarks.json — Postagens que você favoritou.
• media_attachments.json — Metadados sobre arquivos de mídia que você enviou.
• actor.json — Dados do perfil da sua conta.

Cada arquivo já está em formato JSON, mas são separados e usam esquemas diferentes. Para pesquisar em todos os seus dados de uma vez, você precisa de um único índice JSON que mescle esses arquivos em um documento com uma estrutura consistente.

Passos para Converter o Arquivo em um Índice JSON Pesquisável

Você usará um script Python para extrair o arquivo ZIP, ler cada arquivo JSON e escrever um novo arquivo de índice JSON. Este script funciona em sistemas Windows, macOS e Linux que tenham Python 3.6 ou posterior instalado.

1. Baixe e instale o Python
   Se o Python ainda não estiver no seu sistema, baixe a versão mais recente em python.org. Durante a instalação no Windows, marque a opção Adicionar Python ao PATH. Verifique a instalação abrindo um terminal ou Prompt de Comando e executando python --version. Você deve ver um número de versão como 3.12.0.
2. Crie um novo arquivo de script Python
   Abra um editor de texto como Notepad, VS Code ou Sublime Text. Cole o seguinte script em um novo arquivo e salve-o como convert_archive.py na mesma pasta do seu arquivo ZIP de exportação do Mastodon.

   import json
   import zipfile
   import os
   import sys
   
   def convert_archive(zip_path, output_path):
       index = {}
       
       with zipfile.ZipFile(zip_path, 'r') as z:
           for filename in z.namelist():
               if filename.endswith('.json'):
                   with z.open(filename) as f:
                       try:
                           data = json.load(f)
                           # Use o nome do arquivo (sem extensão) como chave
                           key = os.path.splitext(os.path.basename(filename))[0]
                           index[key] = data
                       except json.JSONDecodeError:
                           print(f"Aviso: Não foi possível analisar {filename}, pulando")
       
       with open(output_path, 'w', encoding='utf-8') as out:
           json.dump(index, out, indent=2, ensure_ascii=False)
       
       print(f"Índice escrito em {output_path}")
   
   if __name__ == '__main__':
       if len(sys.argv) != 3:
           print("Uso: python convert_archive.py <input.zip> <output.json>")
           sys.exit(1)
       convert_archive(sys.argv[1], sys.argv[2])

3. Execute o script no terminal
   Abra um terminal ou Prompt de Comando. Navegue até a pasta que contém o script e o arquivo ZIP usando o comando cd. Execute o seguinte comando, substituindo mastodon-export.zip pelo nome real do seu arquivo ZIP e mastodon-index.json pelo nome de saída desejado:

   python convert_archive.py mastodon-export.zip mastodon-index.json

   O script exibe uma mensagem de sucesso quando terminar. Se você vir erros, verifique se o arquivo ZIP não está corrompido e se todos os arquivos JSON dentro dele são válidos.

4. Verifique o índice JSON de saída
   Abra o arquivo mastodon-index.json gerado em um editor de texto ou visualizador JSON. O arquivo deve começar com um objeto de nível superior contendo chaves como outbox, following_accounts, followers e assim por diante. Cada chave mapeia para os dados do arquivo correspondente no arquivo ZIP.
5. Pesquise o índice usando jq
   Instale o processador JSON de linha de comando jq em jqlang.org. Para Windows, baixe o executável e adicione-o ao PATH. Para macOS, use Homebrew: brew install jq. Para Linux, use seu gerenciador de pacotes: sudo apt install jq (Debian/Ubuntu). Em seguida, execute uma consulta como esta para encontrar todas as postagens contendo uma palavra específica:

   jq '.outbox.orderedItems[] | select(.object.content | contains("Mastodon"))' mastodon-index.json

   Este comando extrai cada item do array outbox e filtra pelo conteúdo que inclui a palavra Mastodon.

Erros Comuns e Limitações ao Converter Arquivos de Exportação

O script Python falha com erro zipfile.BadZipFile

Este erro significa que o arquivo ZIP está corrompido ou incompleto. Baixe o arquivo novamente em Configurações > Importar e Exportar > Exportar. Certifique-se de que o download termine completamente antes de executar o script.

A saída JSON é muito grande para abrir em um editor de texto comum

Se você tiver milhares de postagens, o arquivo de índice resultante pode ter centenas de megabytes. Use um visualizador JSON projetado para arquivos grandes, como JSON Viewer ou um editor de código como VS Code com a extensão JSON. Alternativamente, use jq para consultar o arquivo sem carregá-lo inteiramente na memória.

Dados ausentes para postagens privadas ou diretas

O arquivo de exportação do Mastodon inclui apenas postagens públicas por padrão. Postagens privadas e mensagens diretas não são exportadas. Se você precisar delas, deve usar a API do Mastodon com tokens de autenticação apropriados. O arquivo não é um backup completo da sua conta.

O script pula alguns arquivos JSON sem aviso

O script exibe um aviso para arquivos que não consegue analisar. Se você não vir nenhuma saída sobre arquivos pulados, todos os arquivos foram processados. Se alguns arquivos estiverem faltando no índice, verifique se eles existem dentro do ZIP listando seu conteúdo com unzip -l mastodon-export.zip no Linux/macOS ou abrindo o ZIP no Explorador de Arquivos no Windows.

A consulta jq não retorna resultados para um termo de pesquisa conhecido

O caminho .orderedItems[] no outbox pode conter objetos com estruturas diferentes. Alguns itens são boosts ou respostas que não possuem um campo .object.content. Ajuste a consulta para lidar com campos ausentes usando select(.object.content // "" | contains("Mastodon")). Isso usa uma string vazia como fallback para itens sem conteúdo.

Arquivo de Exportação do Mastodon vs Índice JSON: Principais Diferenças

Item	Arquivo de Exportação	Índice JSON
Formato do arquivo	ZIP contendo vários arquivos JSON	Arquivo JSON único
Capacidade de pesquisa	Requer abrir cada arquivo separadamente	Pesquisável com jq ou qualquer ferramenta JSON
Estrutura dos dados	Cada arquivo usa seu próprio esquema	Esquema unificado com chaves baseadas no nome do arquivo
Portabilidade	Deve extrair para acessar os dados	Pronto para uso imediato
Tamanho	ZIP compactado, menor em disco	Descompactado, maior que o ZIP

Agora você tem um único índice JSON que contém todos os dados de exportação do Mastodon em um só lugar. Use jq para executar consultas complexas em suas postagens, seguidores e favoritos sem abrir vários arquivos. Para análise avançada, carregue o índice em um banco de dados como SQLite usando a extensão JSON1, ou em um DataFrame pandas do Python para exploração estatística. O script fornecido pode ser estendido para filtrar chaves desnecessárias ou achatar estruturas aninhadas para facilitar ainda mais a pesquisa.