Rapportere API-endepunkter

Advarsel

Endepunkter som er inkludert i API-en for rapportering, er private endepunkter og leveres for øyeblikket ikke med en avskrivningsretningslinje. Anthology Ally kan endre eller oppdatere disse endepunktene avhengig av veikartet vårt eller fremtidige utgivelser.

Gå gjennom følgende tekniske dokumentasjon for å finne ut hvordan du konfigurerer og tilpasser endepunktene på riktig måte. Sjekk gjerne hvordan du integrerer Allys API med et eksternt rapporteringsverktøy for ytterligere veiledning.

Tilgjengelige metoder

Ally API for rapportering har to metoder. Følgende avsnitt beskriver dem:

Metode	URL	HTTP-forespørselstype	Beskrivelse
Generell	https://[region]/api/v2/clients/[Ally Client ID]/reports/overall	Få	Som standard returnerer denne metoden et datasett med informasjon om emnet, WYSIWYG og filers poengsummer og filtyper som er inkludert i hvert emne fra LMS-forekomsten, uavhengig av om Ally er aktivert eller ikke.
Problemer	https://[region]/api/v2/clients/[Ally Client ID]/reports/issues	Få	Som standard returnerer denne metoden et datasett med informasjonen relatert til alle tilgjengelighetsproblemene som skjer i hvert emne, inkludert i LMS-forekomsten, uavhengig av om Ally er aktivert.

Tips

Bytt ut [Ally Client ID] med din Ally ID. Hvis du ikke kjenner ID-en din, kan du opprette en støtteforespørsel for å be om den.

Tips

Erstatt [Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:

Amerikansk datasenter: prod.ally.ac
Kanadisk datasenter: prod-ca-central-1.ally.ac
Europeisk datasenter: prod-eu-central-1.ally.ac
Datasenter i Singapore: prod-ap-southeast-1.ally.ac
Australsk datasenter: prod-ap-southeast-2.ally.ac

HTTP-statusrespons

Ally API inkluderer et statusfelt i metadataene på følgende måte:

Status 200 - Vellykket: Forespørselen din ble mottatt og det forespurte datasettet er en del av svaret.
Status 202 - Behandling: Forespørselen din ble mottatt med suksess, men datasettet er under forberedelse og er ikke tilgjengelig ennå. Gjenta forespørselen etter en viss tid (minst ett minutt anbefales).
Status 401 - Uautorisert: Ally Client ID eller autorisasjonstoken er ikke korrekte.
Status 400 - Dårlig forespørsel: URL-en har et ugyldig parameternavn, for eksempel et ukjent filteralternativ, operator eller verdi. Se gjennom syntaksen for URL-en. Husk at enkelte av filter- og sorteringsalternativene skiller mellom store og små bokstaver.

Dokumentasjon av metoder

Metode: Totalt sett 

HTTP-forespørsel: GET

https://[region]/api/v2/clients/[Ally Client ID]/reports/overall

Bytt ut [Ally Client ID] med din Ally ID. Hvis du ikke kjenner ID-en din, kan du opprette en støtteforespørsel for å be om den.

Erstatt [Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:

Amerikansk datasenter: prod.ally.ac
Kanadisk datasenter: prod-ca-central-1.ally.ac
Europeisk datasenter: prod-eu-central-1.ally.ac
Datasenter i Singapore: prod-ap-southeast-1.ally.ac
Australsk datasenter: prod-ap-southeast-2.ally.ac

Authorisasjon: OAuth-bærertoken.

Parametere: Valgfrie filtre eller sorteringsalternativer.

Forespørsel om brødtekst: Ingen

Svar:

{ 
    "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 
    } 
}

Metode: Problemer

HTTP-forespørsel: GET 

https://[region]/api/v2/clients/[Ally Client ID]/reports/overall

Erstatt [Ally-klient-ID] ID med din Ally-ID. Hvis du ikke kjenner ID-en din, kan du opprette en støtteforespørsel for å be om den.

Erstatt [Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:

Amerikansk datasenter: prod.ally.ac
Kanadisk datasenter: prod-ca-central-1.ally.ac
Europeisk datasenter: prod-eu-central-1.ally.ac
Datasenter i Singapore: prod-ap-southeast-1.ally.ac
Australsk datasenter: prod-ap-southeast-2.ally.ac

Authorisasjon: OAuth-bærertoken 

Parametere: Valgfrie filtre eller sorteringsalternativer.

Forespørsel om brødtekst: Ingen

Svar:

{ 
    "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 
    } 
}

Der:

Data: inneholder datasettet med resultatene.
Metadata:
- Å: registrere hvilke data som skal hentes, det er «offset» + «limit» eller «total» hvis summen overstiger «total».
- Fra: registrering som dataene starter fra, er det «offset» + 1.
- Totalt: totalt antall kurs vurdert av Ally i LMS-instansen.

Forskyvning – hvor rekorden starter

Første rad er offset = 0,
Ved forskyvning < 0, får brukeren feil 400 - [Ugyldig verdi (parameter = forskyvning, melding = Ingen slike data),],
Når (forskyvning >= totalt) => så brukeren får feil 400 - [Ugyldig verdi (parameter = forskyvning, melding = Ingen slike data)]

Grense - hvor mange poster hentes fra og med forskyvning

Når (grense < 1), får brukeren feil 400 - [Ugyldig verdi (parameter = grense, melding = Grense utenfor grenser)]
Når (grense < 1), får brukeren feil 400 - [Ugyldig verdi (parameter = grense, melding = Grense utenfor grenser)]
Når (forskyvning < total && forskyvning + grense > totalt), endrer vi grensen i bakgrunnen for deg, og data hentes til sist (totalt)

Filtre og sorteringsalternativer

Endepunktssvar kan filtreres i URL-en. Dette avsnittet beskriver de tilgjengelige alternativene:

Sorteringsalternativer

Du kan definere om du vil vise resultatene sortert i stigende eller synkende rekkefølge med tanke på ett kriterium. Hvis du må legge til et sorteringsalternativ, må du legge til sorteringsparameteren som beskrevet nedenfor:

endpoint-url?sort=<Sort parameter value>

Der <Sorter parameterverdi> kan være en av følgende parameterverdier:

Parameterverdi	Beskrivelse	Støttes i	Eksempel
courseName	Sorter etter emnenavn. f.eks. kjemi 101 (courseCode er ikke gyldig)	Generelle og problemendepunkter	endpoint-url?sort=courseName
courseId	Sorter etter kurs-ID, for eksempel 123456 (dette er vanligvis et heltall)	Generelle og problemendepunkter	endpoint-url?sort=courseId
termId	Sorter etter semester-ID. F.eks. Sum	Generelle og problemendepunkter	endpoint-url?sort=termId
termName	Sorter etter semesternavn. f.eks. sommer	Generelle og problemendepunkter	endpoint-url?sort=termName
overallScore	Sorter etter det samlede tilgjengelighetsresultatet for hvert emne.	Bare totalt endepunkt.	endpoint-url?sort=overallScore
filesScore	Sorter resultatene etter filpoengsummen for hvert emne.	Bare totalt endepunkt.	endpoint-url?sort=filesScore
wysiwygScore	Sorter resultatene etter WYSIWYG-poengsummen for hvert emne.	Samlet endepunkt og bare tilgjengelig for Ally for LMS.	endpoint-url?sort= wysiwygScore
webPagesScore	Sorter resultatene etter nettsideresultatet for hvert domene.	Samlet endepunkt og kun tilgjengelig for Ally for Web og WCM.	endpoint-url?sort= webPagesScore

Notat

Parameterverdier skiller mellom store og små bokstaver, og bare ett sorteringsalternativ kan brukes om gangen.

Som standard sorteres resultatene i stigende rekkefølge. Hvis du vil angi en annen rekkefølge, kan du legge til rekkefølgeparameteren:

endpoint-url?sort=<Sort parameter value>&order=<Order value>

Der <Ordensverdi> kan være: asc eller desc

Eksempel:

https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc

Filtreringsalternativer

Du kan bruke filtreringsalternativer for å få mindre eller reduserte svar basert på de valgte kriteriene. Hvis du må legge til et filtreringsalternativ, må du legge til filtreringsparameteren som beskrevet nedenfor:

Filterparametre (uten operatør)

Navn på filterparameteren	Beskrivelse	Støttes i
allyEnabled	Du kan få kursene der Ally er aktiv Verdien er sann eller usann	Generelle og problemendepunkter
departmentId	Filtrer etter avdelings-ID	Generelle og problemendepunkter
departmentName	Filtrer etter avdelingsnavn. f.eks.Ingeniør	Generelle og problemendepunkter
termId	Filtrer etter semester-ID	Generelle og problemendepunkter
termName	Filtrer etter semesternavn. f.eks. sommer	Generelle og problemendepunkter
courseId	Filtrer etter ID eller kurs. f.eks. 123456 (dette er vanligvis et heltall)	Generelle og problemendepunkter
courseName	Filtrer etter navnet på et emne. For eksempel kjemi 101 (courseCode er ikke gyldig)	Generelle og problemendepunkter

endpoint-url?<Filter Parameter>=<value>

Filterparametere (med operator)

endpoint-url?<Filter Parameter>=<Operator>:<value>

Der:

<Filterparameter>: Filtreringsparameter for å få et mindre sett med resultater. Du kan se de støttede parametrene i tabellen nedenfor.
<Operator>: Du må bruke en operator for å filtrere, som lik, ikke lik.
<verdi>: Verdien som brukes i filteret.

Navn på filterparameteren	Felttype	Støttede operatører	Beskrivelse	Støttes i
allyEnabled	Boolsk	eq, ne	Du kan få kursene der Ally er aktiv. Verdien er sann eller usann.	Generelle og problemendepunkter
courseName	Streng	eq, ne, co, nc, sw	Filtrer etter navnet på et emne. For eksempel kjemi 101 (courseCode er ikke gyldig)	Generelle og problemendepunkter
courseId	Streng	eq, ne, co, nc, sw	Filtrer etter ID-en eller et emne. For eksempel 123456 (dette er vanligvis et heltall)	Generelle og problemendepunkter
termId	Streng	eq, ne, co, nc, sw	Term id – semester-ID.	Generelle og problemendepunkter
termName	Streng	eq, ne, co, nc, sw	Filtrer etter semesternavn. f.eks. sommer	Generelle og problemendepunkter
overallScore	Nummer	eq, ne, le, lt, ge, gt	Du kan filtrere etter en totalscore. f.eks. kurs med en poengsum lik 90 %	Overordnet endepunkt og i alle Ally-løsninger: LMS, nettsider og WCM.
filesScore	Nummer	eq, ne, le, lt, ge, gt	Du kan filtrere etter filens poengsum. f.eks. kurs med en arkivscore lik 90 %	Overordnet endepunkt og i alle Ally-løsninger: LMS, nettsider og WCM.
wysiwygScore	Nummer	eq, ne, le, lt, ge, gt	Du kan filtrere etter WYSIWYG-poengsummen. f.eks. kurs med en WYSIWYG-score lik 90 %	Samlet endepunkt og bare tilgjengelig for Ally for LMS.
webPagesScore	Nummer	eq, ne, le, lt, ge, gt	Du kan filtrere etter poengsummen til et domene. f.eks. nettsider med en poengsum lik 90 %.	Samlet endepunkt og bare tilgjengelig for Ally for Web eller WCM.

Notat

Parameterverdier skiller mellom store og små bokstaver.

Støttede operatører

Følgende tabell inneholder de støttede operatorene basert på felttypen:

Felttype	Operatør	Beskrivelse
Streng	eq	Er lik
Streng	ne	Er ikke lik
Streng	co	Inneholder nøkkelord
Streng	nc	Inneholder ikke nøkkelord
Streng	sw	Starter med nøkkelord
Nummer	eq	Er lik
Nummer	ne	Er ikke lik
Nummer	le	Mindre enn eller lik
Nummer	lt	Mindre enn
Nummer	ge	Større enn eller lik
Nummer	gt	Større enn

Eksempel:

I følgende eksempel finner du alle emnene som inneholder nøkkelordet «prøver» i emnenavnet:

https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests

Bruk av flere filtre

Du kan kombinere sorterings- og filtreringsalternativene i samme endepunkts-URL ved å legge til «&»-tegnet mellom de to betingelsene. La oss for eksempel si at du vil hente alle emnene som inneholder nøkkelordet «prøve» i emnenavnet der Ally er aktivert, og at den samlede poengsummen er mindre enn 90 %. URL vil se slik ut:

https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9

Du kan også bruke to filtreringsalternativer. La oss si at du må få alle emnene som har en samlet poengsum mellom 10 % og 70 %:

https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7