Endpoint API di Report
Avvertimento
Gli endpoint inclusi nell'API per la creazione di report sono endpoint privati e al momento non sono dotati di criteri di deprecazione. Anthology Ally può modificare o aggiornare questi endpoint a seconda della nostra roadmap o delle versioni future.
Consulta la seguente documentazione tecnica per scoprire come configurare e personalizzare in modo appropriato i tuoi endpoint. Controlla pure come integrare l'API di Ally con uno strumento di reporting esterno per ulteriori indicazioni.
Metodi disponibili
L'API Ally per i report ha due metodi. La sezione seguente li descrive:
Metodo | URL | Tipo di richiesta HTTP | Descrizione |
Complessivo | https://[region]/api/v2/clients/[ID client Ally]/reports/overall | Ottieni | Per impostazione predefinita, questo metodo restituisce un set di dati con informazioni sul corso, sul WYSIWYG e sui punteggi dei file e sui tipi di file inclusi in ogni corso dall'istanza LMS, indipendentemente dal fatto che Ally sia abilitato o meno. |
Problemi | https://[region]/api/v2/clients/[ID client Ally]/reports/issues | Ottieni | Per impostazione predefinita, questo metodo restituisce un set di dati con le informazioni relative a tutti i problemi di accessibilità che si verificano in ogni corso, inclusi nell'istanza LMS, indipendentemente dal fatto che Ally sia abilitato o meno. |
Suggerimento
Sostituisci [Ally Client ID] con il tuo ID Ally. Se non conosci il tuo documento d'identità, puoi creare un ticket di supporto per richiederlo.
Suggerimento
Sostituisci [Region] a seconda della regione in cui è ospitato l'ambiente Ally del tuo istituto:
Centro dati Stati Uniti: prod.ally.ac
Centro dati canadese: prod-ca-central-1.ally.ac
Centro dati europeo: prod-eu-central-1.ally.ac
Centro dati di Singapore: prod-ap-southeast-1.ally.ac
Centro dati australiano: prod-ap-southeast-2.ally.ac
Le informazioni di cui sopra possono variare a seconda dell'LMS. È possibile rivedere la definizione della colonna nella Documentazione del Report del Corso per ogni LMS:
Risposta di stato HTTP
L'API Ally include un campo di stato nei metadati come segue:
Stato 200 - Riuscito: la richiesta è stata ricevuta correttamente e il dataset richiesto fa parte della risposta.
Stato 202 - Elaborazione: la richiesta è stata ricevuta correttamente, ma il dataset è in fase di preparazione e non è ancora disponibile. Ripeti la tua richiesta più tardi (si consiglia almeno un minuto).
Stato 401 - Non autorizzato: Ally ID client o il token di autorizzazione non sono corretti.
Stato 400 - Richiesta non valida: l'URL ha un nome di parametro non valido, ad esempio un'opzione di filtro, un operatore o un valore sconosciuto. Esamina la sintassi dell'URL. Tenere presente che alcune delle opzioni di filtro e ordinamento fanno distinzione tra maiuscole e minuscole.
Documentazione sui Metodi
Metodo: Complessivo
Richiesta HTTP: GET
https:// [Region]/api/v2/clients/[ID client Ally]/reports/overall
Sostituisci [Ally Client ID] con il tuo ID Ally. Se non conosci il tuo documento d'identità, puoi creare un ticket di supporto per richiederlo.
Sostituisci [Region] a seconda della regione in cui è ospitato l'ambiente Ally del tuo istituto:
Centro dati Stati Uniti: prod.ally.ac
Centro dati canadese: prod-ca-central-1.ally.ac
Centro dati europeo: prod-eu-central-1.ally.ac
Centro dati di Singapore: prod-ap-southeast-1.ally.ac
Centro dati australiano: prod-ap-southeast-2.ally.ac
Autorizzazione: Token di connessione OAuth.
Parametri: Filtri opzionali o opzioni di ordinamento.
Corpo della richiesta: Nessuno
Risposta:
{
"data": [
{
"application/x-quiz": 2,
"observedDeletedOn": "",
"termName": "Fall 2016",
"courseId": "1",
"application/x-announcement": 0,
"image": 4,
"termId": "2",
"document": 93,
"allyEnabled": true,
"pdf": 74,
"courseCode": "BIO101",
"application/x-assignment": 0,
"departmentId": "1",
"totalFiles": 192,
"courseUrl": "https://ally.instructure.com/courses/1",
"departmentName": "Anthology Ally",
"application/x-page": 1,
"filesScore": 0.6022810739019293,
"application/x-syllabus": 1,
"numberOfStudents": 1,
"html-page": 5,
"lastCheckedOn": "2022-04-13 15:33:23",
"WYSIWYGScore": 1.0,
"totalWYSIWYG": 5,
"courseName": "Biology 101",
"application/x-discussion-topic": 1,
"other": 11,
"overallScore": 0.6129724428830603,
"presentation": 5
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
} Metodo: Problemi
Richiesta HTTP: GET
https:// [Region]/api/v2/clients/[ID client Ally]/reports/overall
Sostituisci l'ID [ID client Ally] con il tuo ID Ally. Se non conosci il tuo documento d'identità, puoi creare un ticket di supporto per richiederlo.
Sostituisci [Region] a seconda della regione in cui è ospitato l'ambiente Ally del tuo istituto:
Centro dati Stati Uniti: prod.ally.ac
Centro dati canadese: prod-ca-central-1.ally.ac
Centro dati europeo: prod-eu-central-1.ally.ac
Centro dati di Singapore: prod-ap-southeast-1.ally.ac
Centro dati australiano: prod-ap-southeast-2.ally.ac
Autorizzazione: token di connessione OAuth
Parametri: Filtri opzionali o opzioni di ordinamento.
Corpo della richiesta: Nessuno
Risposta:
{
"data": [
{
"imageDecorative2": 4,
"htmlEmptyHeading2": 0,
"imageSeizure1": 2,
"observedDeletedOn": "",
"htmlObjectAlt2": 0,
"security1": 3,
"termName": "Fall 2016",
"courseId": "1",
"languageCorrect3": 14,
"htmlColorContrast2": 2,
"htmlLinkName3": 0,
"termId": "2",
"languagePresence3": 10,
"allyEnabled": true,
"htmlLabel2": 0,
"alternativeText2": 68,
"htmlImageAlt2": 0,
"htmlImageRedundantAlt3": 0,
"headingsPresence2": 20,
"courseCode": "BIO101",
"headingsSequential3": 4,
"departmentId": "1",
"htmlHeadingsPresence2": 0,
"courseUrl": "https://ally.instructure.com/courses/1",
"headingsStartAtOne3": 4,
"departmentName": "Anthology Ally",
"htmlHeadingsStart2": 0,
"htmlTdHasHeader2": 0,
"htmlList3": 0,
"htmlDefinitionList3": 0,
"htmlCaption2": 0,
"tableHeaders2": 23,
"htmlEmptyTableHeader2": 0,
"htmlHasLang3": 1,
"ocred2": 0,
"scanned1": 6,
"htmlBrokenLink2": 0,
"numberOfStudents": 1,
"htmlHeadingOrder3": 0,
"lastCheckedOn": "2022-04-13 15:33:23",
"headingsHigherLevel3": 0,
"contrast2": 28,
"title3": 46,
"imageOcr3": 0,
"tagged2": 4,
"libraryReference": 172,
"courseName": "Biology 101",
"imageContrast2": 0,
"imageDescription2": 4,
"htmlTitle3": 1,
"parsable1": 2
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
} Dove:
Dati: contiene il dataset dei risultati.
Metadati:
A: registra su quale dati verranno recuperati, è "offset" + "limite" o "totale" se la somma supera "totale".
Da: registrazione da cui partiranno i dati, è "offset" + 1.
Totale: numero totale di corsi considerati da Ally nell'istanza LMS.
Offset - da cui inizia la registrazione
La prima riga è sfalsata = 0,
Quando l'offset < 0, l'utente ottiene l'errore 400 -[Valore non valido (parameter=offset, message=No such data)],
Quando (offset >= totale) => allora l'utente riceve l'errore 400 - [Valore non valido (parameter=offset, message=No such data) ]
Limite: quante registrazioni vengono recuperati a partire dall'offset
Quando (limite < 1 ) l'utente riceve l'errore 400 - [Valore non valido (parameter=limit, message=Limit out of boundaries)]
Quando (limite > 10000) l'utente riceve l'errore 400 - [Valore non valido (parameter=limit, message=Limit out of boundaries)]
Quando (offset < totale && offset + limite > totale), allora cambiamo il limite in background per te, e i dati verranno recuperati fino all'ultimo (totale)
Filtri e opzioni di ordinamento
Le risposte dell'endpoint possono essere filtrate nell'URL. In questa sezione vengono descritte le opzioni disponibili:
Opzioni di ordinamento
È possibile definire se si desidera visualizzare i risultati ordinati in ordine crescente o decrescente considerando un criterio. Se è necessario aggiungere un'opzione di ordinamento, è necessario aggiungere il parametro di ordinamento come descritto di seguito:
endpoint-url?sort=<Sort parameter value>
Dove <Sort parameter value> può essere uno dei seguenti valori di parametro:
Valore del parametro | Descrizione | Supportato in | Esempio |
courseName | Ordina per nome del corso, ad es. Chimica 101 (courseCode non è valido) | Endpoint generali e problemi | endpoint-url?sort=courseName |
courseId | Ordina per ID corso, ad es. 123456 (di solito si tratta di un numero intero) | Endpoint generali e problemi | endpoint-url?sort=courseId |
termId | Ordina per ID termine. Ad esempio, Somma | Endpoint generali e problemi | endpoint-url?sort=termId |
termName | Ordina per termine Nome. ad es. Estate | Endpoint generali e problemi | endpoint-url?sort=termName |
overallScore | Ordina in base al punteggio di accessibilità complessivo di ciascun corso. | Solo endpoint generale. | endpoint-url?sort=overallScore |
filesScore | Ordina i risultati in base al punteggio del file di ogni corso. | Solo endpoint generale. | endpoint-url?sort=punteggiofile |
wysiwygScore | Ordina i risultati in base al punteggio WYSIWYG di ciascun corso. | Endpoint generale e disponibile solo per Ally per LMS. | endpoint-url?sort= wysiwygScore |
webPagesScore | Ordina i risultati in base al punteggio della pagina web di ciascun dominio. | Endpoint generale e disponibile solo per Ally per Web e WCM. | endpoint-url?sort= webPagesScore |
Nota
I valori dei parametri fanno distinzione tra maiuscole e minuscole ed è possibile utilizzare una sola opzione di ordinamento alla volta.
Per impostazione predefinita, i risultati sono ordinati in ordine crescente. Se si desidera impostare un ordine diverso, è possibile aggiungere il parametro order:
endpoint-url?sort=<Sort parameter="" value="">&order=<Order value></Sort>
Dove <Valore dell'ordine> può essere: asc o desc
Esempio:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Opzioni di filtro
È possibile utilizzare le opzioni di filtro per ottenere risposte più piccole o ridotte in base ai criteri selezionati. Se è necessario aggiungere un'opzione di filtro, è necessario aggiungere il parametro di filtro come descritto di seguito:
Parametri filtro (senza operatore)
Nome del parametro di filtro | Descrizione | Supportato in |
allyEnabled | Puoi ottenere i corsi in cui Ally è attivo Il valore è vero o falso | Endpoint generali e problemi |
departmentId | Filtra in base all'ID del reparto | Endpoint generali e problemi |
departmentName | Filtra in base al nome del reparto. ad es. Ingegneria | Endpoint generali e problemi |
termId | Filtra in base al termine ID | Endpoint generali e problemi |
termName | Filtra in base al Nome termine. ad esempio Estate | Endpoint generali e problemi |
courseId | Filtra in base all'ID o a un corso. ad es. 123456 (di solito si tratta di un numero intero) | Endpoint generali e problemi |
courseName | Filtra in base al nome di un corso. Ad esempio, Chimica 101 (courseCode non è valido) | Endpoint generali e problemi |
url-endpoint? <Filter parameter=""><value>=</Filter>
Parametri di filtro (con operatore)
url-endpoint? <Filter parameter="">=<Operator>:<value></Operator></Filter>
Dove:
<Filter Parameter>: parametro di filtro per ottenere un set di risultati più piccolo. È possibile consultare i parametri supportati nella tabella seguente.
<Operator>: è necessario utilizzare un operatore per filtrare, come uguale a, non uguale.
<value>: valore utilizzato nel filtro.
Nome del parametro di filtro | Tipo di campo | Operatori supportati | Descrizione | Supportato in |
allyEnabled | Booleano | eq, ne | Puoi ottenere i corsi in cui Ally è attivo. Il valore è vero o falso. | Endpoint generali e problemi |
courseName | Riga | eq, ne, co, nc, sw | Filtra in base al nome di un corso. Ad esempio, Chimica 101 (courseCode non è valido) | Endpoint generali e problemi |
courseId | Riga | eq, ne, co, nc, sw | Filtra in base all'ID o a un corso. Ad esempio, 123456 (di solito si tratta di un numero intero) | Endpoint generali e problemi |
termId | Riga | eq, ne, co, nc, sw | Filtra in base al termine ID. | Endpoint generali e problemi |
termName | Riga | eq, ne, co, nc, sw | Filtra in base al Nome termine. ad esempio Estate | Endpoint generali e problemi |
overallScore | Numero | eq, ne, le, lt, ge, gt | Puoi filtrare in base a un punteggio complessivo. es. Corsi con un punteggio pari al 90% | Endpoint generale e in tutte le soluzioni Ally: LMS, siti web e WCM. |
filesScore | Numero | eq, ne, le, lt, ge, gt | È possibile filtrare in base al punteggio dei file. es. Corsi con un punteggio file pari al 90% | Endpoint generale e in tutte le soluzioni Ally: LMS, siti web e WCM. |
wysiwygScore | Numero | eq, ne, le, lt, ge, gt | È possibile filtrare in base al punteggio WYSIWYG. es. Corsi con un punteggio WYSIWYG pari al 90% | Endpoint generale e disponibile solo per Ally per LMS. |
webPagesScore | Numero | eq, ne, le, lt, ge, gt | È possibile filtrare in base al punteggio di un dominio. ad esempio pagine Web con un punteggio pari al 90%. | Endpoint generale e disponibile solo per Ally per Web o WCM. |
Nota
I valori dei parametri fanno distinzione tra maiuscole e minuscole.
Operatori Supportati
La tabella seguente contiene gli operatori supportati in base al tipo di campo:
Tipo di campo | Operatore | Descrizione |
Riga | eq | È uguale |
Riga | ne | Non è uguale |
Riga | co | Contiene la parola chiave |
Riga | nc | Non contiene parole chiave |
Riga | sw | Inizia con la parola chiave |
Numero | eq | È uguale |
Numero | ne | Non è uguale |
Numero | le | Minore o uguale a |
Numero | lt | Meno di |
Numero | ge | Maggiore o uguale |
Numero | gt | Maggiore di |
Esempio:
Nell'esempio seguente vengono recuperati tutti i corsi che contengono la parola chiave "tests" nel nome del corso:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Utilizzo di più filtri
È possibile combinare le opzioni di ordinamento e filtro nello stesso URL dell'endpoint aggiungendo il carattere "&" tra le due condizioni. Ad esempio, supponiamo che tu voglia recuperare tutti i corsi che contengono la parola chiave "test" nel nome del corso in cui Ally è abilitato e che il punteggio complessivo sia inferiore al 90%. L'URL sarà simile al seguente:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
È inoltre possibile utilizzare due opzioni di filtro. Ad esempio, supponiamo che tu debba ottenere tutti i corsi che hanno un punteggio complessivo compreso tra il 10% e il 70%:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7