Este documento inclui algumas das perguntas técnicas mais frequentes sobre o Canvas Data 2 (CD2).
O que significa o carimbo de data/hora 'ts' no campo 'meta' do conjunto de resultados da consulta?
ts é um carimbo de data/hora da última modificação (ou horário de confirmação) do registro na tabela. Quando um novo registro é inserido em uma tabela hospedada pelo CD2, é atribuído a ele o horário de inserção. Quando esse registro é atualizado posteriormente, o carimbo de data/hora é atualizado para corresponder ao horário em que a atualização ocorreu. Finalmente, quando o registro é excluído, o carimbo de data/hora reflete o horário da exclusão.
Qual a relação entre 'since' e 'until' e 'ts' no conjunto de resultados?
Os parâmetros since e until são filtros baseados no horário de confirmação (ou no carimbo de data/hora da última modificação). Todos os registros no conjunto de resultados estão dentro do intervalo definido por since e ` until .
Posso obter registros duplicados com a mesma chave no conjunto de resultados?
Não; as chaves no conjunto de resultados de uma consulta instantânea ou incremental são sempre únicas.
Como faço para transformar um conjunto de resultados de uma consulta incremental em uma instrução SQL?
Provavelmente você desejará usar uma instrução INSERT ou UPDATE. No PostgreSQL, isso se parece com o seguinte:
INSERT INTO ... (...)
VALUES (...)
ON CONFLICT (...)
DO UPDATE SET ...
O que devo fazer com os registros no conjunto de resultados que possuem uma 'chave', mas não um 'valor'?
Registros de saída que possuem um campo key , mas nenhum campo value correspondem a registros excluídos. Os dados não estão mais disponíveis nos sistemas da Instructure e também devem ser excluídos da sua cópia local. Esses registros também são marcados com a ação "D" nos metadados.
O que significa '__cd2_oversized_truncated__'? (Alguns campos/colunas podem ter esse valor.)
__cd2_oversized_truncated__ é um marcador especial (constante de string) que indica que os dados originais eram muito grandes para serem incluídos no resultado, geralmente com vários MBs. Infelizmente, não é possível recuperar o valor desses campos/colunas. No entanto, valores tão grandes normalmente são resultado de um erro (por exemplo, um aluno copiando um documento binário do Word para um campo de texto simples) e raramente contêm informações valiosas para análises.
Como posso capturar o estado do banco de dados em um determinado momento?
O CD2 não suporta consultas pontuais; não é possível reconstruir um estado histórico anterior do banco de dados, apenas sincronizar sua cópia local com o estado mais atualizado mantido pela Instructure.
Como faço para obter todos os dados desde o início dos tempos até uma data específica?
Infelizmente, isso não é suportado pelo CD2. O CD2 permite sincronizar seu banco de dados local com o estado atual do banco de dados na Instructure. Se um registro foi atualizado ou excluído no banco de dados de origem no domínio da Instructure, você não poderá recuperar as versões anteriores desse registro. No entanto, os registros ficam disponíveis indefinidamente enquanto existirem nos sistemas da Instructure; eles não desaparecem com o tempo. Por exemplo, você poderá obter todos os cursos nos quais um aluno se inscreveu ou todas as tarefas que ele enviou, pois todos aparecem como registros diferentes, e não como versões do mesmo registro.
Como faço para obter um registro de todas as transições de gravação?
O CD2 permite atualizar seu banco de dados para o estado mais recente, mas não retorna (de forma confiável) estados intermediários. Mesmo que você tente consultar o endpoint de consulta da API do CD2 em intervalos curtos, vários eventos de captura de dados de alteração (CDC) para o mesmo registro serão consolidados em uma única alteração, e somente essa alteração será retornada no conjunto de resultados da consulta incremental. A saída do CD2 não pode servir como um registro de todas as transições do banco de dados, apenas como um meio de atualizar seu banco de dados local com o estado mais recente nos sistemas da Instructure.
Solução de problemas
Recebi um código de status HTTP 4xx como resposta.
Um erro HTTP da classe 4xx (por exemplo, HTTP 400 Bad Request) é um erro permanente. Para saber mais sobre o motivo da rejeição da sua solicitação, verifique o conteúdo da resposta HTTP. O corpo da resposta HTTP deve ser do tipo application/json e conter um objeto com a propriedade error . Isso inclui informações sobre o motivo da rejeição da solicitação.
As consultas incrementais possuem o campo action nos meta , que especifica se um registro foi inserido ou atualizado (upsertado) ou excluído . Se um registro for inserido ou atualizado, você normalmente usaria uma instrução SQL `INSERT` ou `UPDATE` em seu banco de dados para atualizar o registro. Se um registro for excluído, você usaria a instrução SQL `DELETE` para removê-lo.
Consultas de instantâneo não possuem action porque seria um campo redundante. Consultas de instantâneo pressupõem que seu banco de dados esteja vazio e que todos os registros devam ser inseridos. Normalmente, você usaria uma instrução COPY ou INSERT para preencher o banco de dados.
A saída CSV no CD2 está em conformidade com a RFC 4180. A seção 2.6 desta especificação, que trata de como as quebras de linha nos valores são representadas, é frequentemente implementada de forma inadequada nas ferramentas. Especificamente, se um valor contém um caractere de quebra de linha, a saída deve ser delimitada por aspas duplas, mas o caractere de quebra de linha deve ser representado literalmente (e não como uma sequência de escape). No entanto, as ferramentas geralmente assumem que um registro sempre cabe em uma única linha, o que não é o caso nessas circunstâncias.
O script de exemplo de criação do PostgreSQL tem 'CREATE TYPE ... AS (...)', mas meu data warehouse ou mecanismo de banco de dados não suporta essa sintaxe.
O script de referência do PostgreSQL para criar o banco de dados possui os chamados tipos aninhados. Nem todos os mecanismos de banco de dados suportam tipos aninhados. Se o seu mecanismo não os suporta, você pode usar o tipo SQL mais genérico json. json permite inserir estruturas aninhadas arbitrárias como dados JSON. No entanto, você pode não conseguir filtrar colunas json com a mesma eficácia que outros tipos de coluna.
Estou recebendo um erro informando que não há dados disponíveis para o intervalo ou que o intervalo está fora dos limites.
Certifique-se de encadear corretamente suas consultas incrementais. Você deve sempre usar o timestamp " until" da consulta incremental anterior (ou o timestamp " at" da sua consulta de snapshot inicial) como o timestamp " since" da próxima consulta incremental. Não especifique valores arbitrários para esses parâmetros; reutilize apenas aqueles retornados por uma resposta anterior.
Parece que não consigo fornecer um registro de data e hora "até" a menos que também forneça um registro de data e hora "desde".
Os registros de data e hora " since" e "until" são meios de encadear consultas incrementais. Você deve sempre usar o registro de data e hora "until" da consulta incremental anterior como o registro de data e hora "since" da próxima consulta incremental. O CD2 armazena apenas o estado mais recente de qualquer registro; o registro "until" não pode ser usado para reconstruir o estado de um registro em um ponto anterior no tempo.
Algumas partes ou números de sequência estão faltando no conjunto de arquivos retornados pela API CD2.
A API CD2 pode retornar objetos S3 que não possuem números de sequência contíguos, por exemplo, part1 , part2 e part5 podem estar presentes, enquanto part3 e part4 podem estar ausentes. Isso não é um erro.
Os nomes dos arquivos, em geral, são informativos. Você não deve fazer suposições com base no padrão dos nomes dos arquivos.
Os arquivos retornados pela API CD2 são gerados pela execução independente de tarefas simultâneas. Dependendo do contexto de execução, dos parâmetros de entrada, etc., uma tarefa pode encontrar vários registros que correspondem à consulta ou pode não encontrar nenhum registro. Além disso, uma tarefa pode ser interrompida durante o processamento de registros e sua carga de trabalho pode ser delegada a outra tarefa. Portanto, os números podem não ser contíguos, o que explica por que você pode ter uma part1 e uma part5 , mas nenhuma part4 .
Cada arquivo de saída gerado pela API CD2 pode conter zero ou mais registros. Um script de integração deve ser capaz de lidar com o caso em que o arquivo não contém registros.
Os arquivos retornados pela API CD2 são gerados pela execução independente de tarefas simultâneas. Dependendo do contexto de execução, dos parâmetros de entrada, etc., uma tarefa pode encontrar vários registros que correspondem à consulta ou pode não encontrar nenhum registro. Se nenhum registro for encontrado, um arquivo vazio será retornado.
Arquivos vazios são tratados automaticamente pela biblioteca cliente oficial do CD2 .