Endpoint API di Report
Note
La presente documentazione è stata tradotta tramite traduzione automatica assistita dall'intelligenza artificiale. Le traduzioni sono fornite "così come sono", senza alcuna garanzia circa la loro accuratezza. La versione inglese di questo contenuto costituisce la fonte ufficiale e facente fede.
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