API de Fontes de dados

Lista as predefinições de fonte: configurações prontas e testadas da fonte de dados json (docs/sources.md, Presets). Cada uma diz quais cartões preenche, os campos que uma pessoa preenche (com ajuda, um padrão e um exemplo), os segredos de que precisa e como obter cada um, com que frequência atualiza e por quanto tempo um cartão mantém seus últimos dados, e os dados de quem ela lê e sob quais termos.

Crie uma fonte a partir de uma com POST /api/sources e preset, settings e secrets, e visualize-a com POST /api/sources/test.

Uma predefinição de fonte, como a lista a mostra.

Lista as fontes de dados do projeto, as mais recentes primeiro, no máximo 200 por página. Uma fonte de dados mantém atualizadas as propriedades dinâmicas de um cartão a partir de um endereço externo, em um agendamento (docs/sources.md). Cada fonte mostra o status: a última tentativa, o último sucesso, a última alteração gravada, a próxima execução, a contagem de falhas e o último erro.

Os segredos nunca são devolvidos; cada um aparece como definido com uma dica mascarada. next_cursor é passado como after para a próxima página, null quando não há mais.

Cria uma fonte de dados que grava as propriedades dinâmicas de um cartão a partir de um endereço externo. kind escolhe o adaptador (ics lê um endereço iCalendar ou webcal://); config guarda as configurações do tipo e secrets as credenciais dele, armazenadas criptografadas e mostradas apenas como uma dica mascarada.

Ou nomeie uma predefinição (GET /api/source-presets) e informe os settings e secrets dela em vez de kind e config: a fonte é uma fonte json cuja configuração a predefinição monta, devolvida com seu preset e settings, e o intervalo de atualização e o período de expiração assumem por padrão os da predefinição. Uma predefinição preenche apenas os cartões que lista (source_target_unsupported).

A fonte roda em segundos e depois a cada refresh_seconds. Uma execução com falha nunca grava: o cartão mantém o último documento válido e o status da fonte mostra o erro. Uma fonte preenche um cartão (source_target_taken), o cartão deve ser um que o tipo possa preencher (source_target_unsupported) e uma organização tem no máximo 200 fontes (source_limit_reached).

Use primeiro POST /api/sources/test para ver o documento que a fonte gravaria. Acrescenta source.created. Uma nova tentativa idêntica com a mesma Idempotency-Key retorna esta mesma resposta por vinte e quatro horas.

Faz uma prévia de uma fonte de dados sem salvar nem gravar nada: busca o endereço, formata a resposta para o cartão de destino e valida o documento com o cartão; depois retorna o documento, se o cartão o aceita (valid, com validation_error nomeando o caminho quando não aceita) e os avisos e contagens da execução.

Passe source_id para testar uma fonte salva com os demais membros como substituições (settings substituem os de uma fonte criada a partir de uma predefinição); caso contrário, target e ou kind e config, ou preset, settings e secrets são obrigatórios. Um segredo que uma fonte salva mantém é usado como armazenado, a menos que a substituição mude para onde ele aponta (source_secret_required).

Uma falha de busca ou de formatação é source_test_failed com o source_error fixo. No máximo 30 pré-visualizações por minuto por organização.

Uma fonte de dados com o status dela. ETag é a revisão, para If-Match na próxima alteração.

Altera uma fonte de dados. config substitui toda a configuração; secrets é mesclado (uma string define ou substitui um, null remove).

Uma fonte criada a partir de uma predefinição recebe settings em vez de config: cada configuração nomeada substitui seu valor, null remove uma opcional, as demais mantêm as suas, e a configuração é montada de novo a partir da predefinição (config em uma fonte assim é invalid_request em config, e settings em outra é invalid_request em settings). Os segredos dela são nomeados como a predefinição os nomeia.

Um segredo não enviado mantém o valor, a menos que a alteração aponte a fonte para algo que o escopo armazenado não cobre (source_secret_required em secrets.<name>: informe-o de novo).

Uma alteração no destino, em config, nos segredos, em refresh_seconds ou em enabled zera a contagem de falhas e executa a fonte em segundos; renomear não. enabled false para o agendamento e mantém o último documento do cartão. If-Match protege a revisão. Acrescenta source.updated.

Exclui a fonte de dados. O cartão mantém o último documento que a fonte gravou. If-Match protege a revisão. Acrescenta source.deleted.

O mapeamento de salas de uma fonte de dados que lê as salas de um sistema de reservas (tipo momentus): quais salas ela oferece que nenhuma tela mostra (summary.unmapped_rooms) e quais telas leem um documento de sala ou área sem um valor que nomeie uma (telas com status missing ou unknown, com uma sugestão quando o valor é uma sala escrita de outro jeito).

As salas são as da última atualização boa da fonte; nada é buscado. Um tipo sem salas responde source_has_no_rooms.

Sincroniza a fonte na hora, de forma direta (até 60 segundos), e a retorna com o novo status. Uma sincronização com falha responde 200 com status.state error e o erro; nunca grava. Uma atualização recomeça a fonte: a contagem de falhas é zerada e o endereço é lido por inteiro. source_busy (Retry-After) enquanto uma sincronização agendada está com a fonte.

No máximo 6 sincronizações por minuto por fonte.