Questo documento contiene alcune delle domande tecniche più frequenti su Canvas Data 2 (CD2).
Cosa significa il timestamp 'ts' nel campo 'meta' del set di risultati della query?
ts è il timestamp dell'ultima modifica (o ora di commit) per il record nella tabella. Quando un nuovo record viene inserito in una tabella ospitata da CD2, gli viene assegnata l'ora di inserimento. Quando il record viene successivamente aggiornato, il timestamp viene aggiornato in modo che corrisponda all'ora in cui è avvenuto l'aggiornamento. Infine, quando il record viene eliminato, il timestamp riflette l'ora di eliminazione.
In che modo "since" e "until" si relazionano a "ts" nel set di risultati?
since e until sono filtri basati sull'ora di commit (o timestamp dell'ultima modifica). Tutti i record nel set di risultati rientrano nell'intervallo since e until .
Posso ottenere record duplicati della stessa chiave nel set di risultati?
No; le chiavi nel set di risultati di una query snapshot o incrementale sono sempre univoche.
Come posso trasformare un set di risultati di query incrementali in un'istruzione SQL?
Probabilmente vorrai usare un'istruzione INSERT o UPDATE. In PostgreSQL, questo si presenta così:
INSERT INTO ... (...)
VALUES (...)
ON CONFLICT (...)
DO UPDATE SET ...
Cosa faccio con i record nel set di risultati che hanno una "chiave" ma nessun "valore"?
I record di output che contengono un campo key ma nessun campo value corrispondono ai record eliminati. I dati non sono più disponibili nei sistemi di Instructure e devono essere eliminati anche dalla copia locale. Questi record sono inoltre contrassegnati con un'azione D in meta.
Cosa significa '__cd2_oversized_truncated__'? (Alcuni campi/colonne possono avere questo valore.)
__cd2_oversized_truncated__ è un segnaposto speciale (costante stringa) che indica che i dati originali erano troppo grandi per essere inclusi nel risultato, solitamente di diversi MB. Purtroppo, non è possibile recuperare il valore di questi campi/colonne. Tuttavia, valori così elevati sono in genere il risultato di un errore (ad esempio, uno studente che copia un documento Word binario in un campo di testo normale) e raramente contengono informazioni preziose utili per l'analisi.
Come posso acquisire lo stato del database in un dato momento?
CD2 non supporta query point-in-time, non è possibile ricostruire uno stato storico precedente del database, è possibile solo sincronizzare la copia locale con lo stato più aggiornato mantenuto da Instructure.
Come posso ottenere tutti i dati dall'inizio dei tempi fino a una data specifica?
Purtroppo, questa funzionalità non è supportata da CD2. CD2 consente di sincronizzare il database locale con lo stato corrente del database in Instructure. Se un record è stato aggiornato o eliminato nel database di origine nel dominio di Instructure, non è possibile recuperarne le versioni precedenti. Tuttavia, i record sono disponibili a tempo indeterminato finché esistono nei sistemi di Instructure e non scompaiono nel tempo. Ad esempio, dovresti essere in grado di ottenere tutti i corsi a cui uno studente ha fatto domanda o tutti i compiti che ha consegnato, perché vengono visualizzati come record diversi, non come versioni dello stesso record.
Come posso ottenere un flusso di tutte le transizioni dei record?
CD2 consente di aggiornare il database allo stato più recente, ma non restituisce (in modo affidabile) stati intermedi. Anche se si tenta di interrogare l'endpoint del processo di query dell'API CD2 con un intervallo breve, più eventi di change data capture sullo stesso record verranno uniti in un'unica modifica e solo quella singola modifica verrà restituita nel set di risultati della query incrementale. L'output di CD2 non può fungere da registro delle modifiche di tutte le transizioni del database, ma solo da mezzo per aggiornare il database locale con lo stato più recente nei sistemi di Instructure.
Risoluzione dei problemi
Ho ricevuto come risposta un codice di stato HTTP 4xx.
Un errore di classe HTTP 4xx (ad esempio HTTP 400 Richiesta non valida) è un errore permanente. Per saperne di più sul motivo per cui la richiesta è stata rifiutata, controlla il payload della risposta HTTP. Il corpo HTTP deve essere di tipo application/json e contenere un oggetto con la proprietà error . Questo include informazioni sul motivo per cui la richiesta è stata rifiutata.
Le query incrementali hanno il campo action in meta , che specifica se un record è stato inserito o aggiornato (upsert) o eliminato . Se un record viene inserito, in genere si utilizza un'istruzione SQL INSERT o UPDATE nel database per aggiornarlo. Se un record viene eliminato, si utilizza l'istruzione SQL DELETE per rimuoverlo.
Le query snapshot non hanno action perché rappresenterebbero un campo ridondante. Le query snapshot presuppongono che il database sia vuoto e che tutti i record debbano essere inseriti. In genere, si utilizza un'istruzione COPY o INSERT per popolare il database.
L'output CSV in CD2 è conforme allo standard RFC 4180. La Sezione 2.6 di questa specifica, che tratta della rappresentazione dei caratteri di nuova riga nei valori, è spesso implementata in modo inadeguato negli strumenti. In particolare, se un valore contiene un carattere di nuova riga incorporato, l'output dovrebbe essere racchiuso tra virgolette doppie, ma il carattere di nuova riga dovrebbe essere rappresentato letterale (non come una sequenza di escape). Tuttavia, gli strumenti spesso presumono che un record occupi sempre una singola riga, il che non è il caso in queste circostanze.
Lo script di creazione di PostgreSQL di esempio ha 'CREATE TYPE ... AS (...)' ma il mio data warehouse o motore di database non supporta questa sintassi.
Lo script PostgreSQL di riferimento per creare il database contiene i cosiddetti tipi annidati. Non tutti i motori di database hanno tipi annidati. Se il tuo motore non li supporta, puoi utilizzare il tipo SQL più generico json. json consente di inserire strutture annidate arbitrarie come dati JSON. Tuttavia, potresti non essere in grado di filtrare le colonne json in modo efficace come con altri tipi di colonna.
Ricevo un errore che indica che non ci sono dati disponibili per l'intervallo oppure che l'intervallo è fuori dai limiti.
Assicuratevi di concatenare correttamente le vostre query incrementali. Dovreste sempre utilizzare il timestamp until della query incrementale precedente (o il timestamp at della query snapshot iniziale) come timestamp since della query incrementale successiva. Non dovreste specificare valori arbitrari per questi parametri, ma riutilizzare solo quelli restituiti da una risposta precedente.
Sembra che non posso fornire un timestamp "fino a" a meno che non fornisca anche un timestamp "dal".
I timestamp since e until sono strumenti per concatenare query incrementali. È sempre consigliabile utilizzare il timestamp until della query incrementale precedente come timestamp since della query incrementale successiva. CD2 memorizza solo lo stato più recente di qualsiasi record, until non può essere utilizzato per ricostruire lo stato di un record in un momento passato.
Mancano alcuni numeri di parte o di sequenza nel set di file restituiti dall'API CD2.
L'API CD2 potrebbe restituire oggetti S3 che non hanno numeri di sequenza contigui, ad esempio part1 , part2 , part5 potrebbero essere presenti mentre part3 e part4 potrebbero essere mancanti. Questo non è un errore.
In generale, i nomi dei file sono informativi. Non si dovrebbero fare supposizioni basandosi sul modello di nome del file.
I file restituiti dall'API CD2 vengono generati eseguendo in modo indipendente attività simultanee. A seconda del contesto di esecuzione, dei parametri di input, ecc., un'attività potrebbe trovare diversi record che corrispondono alla query, oppure potrebbe non riuscire a trovarne alcuno. Inoltre, un'attività potrebbe essere interrotta durante l'elaborazione dei record e il suo carico di lavoro potrebbe essere delegato a un'altra attività. Pertanto, i numeri potrebbero non essere contigui, il che spiega perché potresti avere part1 e part5 ma nessun part4 .
Ogni file di output prodotto dall'API CD2 può contenere zero o più record. Uno script di integrazione dovrebbe essere in grado di gestire il caso in cui il file non contenga alcun record.
I file restituiti dall'API CD2 vengono generati eseguendo in modo indipendente attività simultanee. A seconda del contesto di esecuzione, dei parametri di input, ecc., un'attività potrebbe trovare diversi record che corrispondono alla query, oppure potrebbe non trovarne nessuno. Se non viene trovata alcuna corrispondenza, viene restituito un file vuoto.
I file vuoti vengono gestiti automaticamente dalla libreria client ufficiale CD2 .