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 | Nettadresse | Type HTTP-forespørsel | 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. |
Erstattet [Ally-klient-ID] med din Ally-ID. Hvis du ikke kjenner ID-en din, kan du opprette en støtteforespørsel for å be om den.
Erstatt%nbsp;[Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:
- Datasenter i USA: prod.ally.ac
- Datasenter i Canada: 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
Informasjonen ovenfor kan variere avhengig av LMS. Du kan gå gjennom kolonne definisjonen i emnerapportdokumentasjonen for hver LMS:
HTTP-statusrespons
Ally API inkluderer et statusfelt i metadataene på følgende måte:
- Status 200 - Vellykket: Forespørselen ble mottatt, og det etterspurte datasettet er en del av svaret.
- Status 202 - Behandler: Forespørselen ble mottatt, 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 klient-ID-en eller autorisasjonstokenet er ikke riktig.
- Status 400 – Dårlig forespørsel: URL-en har et ugyldig parameternavn, for eksempel et ukjent filteralternativ, operatør eller verdi. Se gjennom syntaksen for URL-en. Husk at enkelte av filter- og sorteringsalternativene skiller mellom store og små bokstaver.
Metodedokumentasjon
Metode: Totalt
HTTP-forespørsel: GET
https:// [Region]/api/v2/clients/[Ally-klient- ID]/reports/overall
Erstattet [Ally-klient-ID] med din Ally-ID. Hvis du ikke kjenner ID-en din, kan du opprette en støtteforespørsel for å be om den.
Erstatt%nbsp;[Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:
- Datasenter i USA: prod.ally.ac
- Datasenter i Canada: 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.
Parametre: Valgfrie filtre eller sorteringsalternativer.
Forespørselsbrødtekst: Ingen
Respons:
{
"data": [
{
"applikasjon/x-quiz": 2,
"observedDeletedOn": "",
"termName": "Fall 2016",
"courseId": "1",
"applikasjon/x-kunngjøring": 0,
"bilde": 4,
"termId": "2",
"dokument": 93,
"allyEnabled": true,
"pdf": 74,
"courseCode": "BIO101",
"applikasjon/x-oppgave": 0,
"departmentId": "1",
"totalFiles": 192,
"courseUrl": "https://ally.instructure.com/courses/1",
"departmentName": "Anthology Ally",
"applikasjon/x-side": 1,
"filesScore": 0.6022810739019293,
"applikasjon/x-emneoversikt": 1,
"numberOfStudents": 1,
"html-side": 5,
"lastCheckedOn": "2022-04-13 15:33:23",
"WYSIWYGScore": 1.0,
"totalWYSIWYG": 5,
"courseName": "Biology 101",
"applikasjon/x-diskusjon-emne": 1,
"annet": 11,
"overallScore": 0.6129724428830603,
"presentasjon": 5
}
],
"metadata": {
"filteredTotal":0, "totalt":
7186,
"til": 7186,
"status": "Processing",
"fra": 1
}
}
Metode: Problemer
HTTP-forespørsel: GET
https:// [Region]/api/v2/clients/[Ally-klient-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%nbsp;[Region] avhengig av regionen der det Ally miljøet for institusjonen din driftes:
- Datasenter i USA: prod.ally.ac
- Datasenter i Canada: 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
Respons:
{
"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, "totalt":
7186,
"til": 7186,
"status": "Processing",
"fra": 1
}
}
Hvor:
- Data: inneholder datasettet med resultatene.
- Metadata:
- Til: post som data hentes til, det er "forskyvning" + "grense" eller "total" hvis summen overstiger "totalt".
- Fra: Ta opp hvilke data som starter, det er "forskyvning" + 1.
- Totalt: totalt antall emner som Ally vurderte i LMS-tilfellet.
Forskyvning - fra poststart
- Første rad er forskyvning = 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 > 10 000), 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=<Sorter parameterverdi>
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) | Overordnede og problemrelaterte endepunkter | endpoint-url?sort=courseName |
courseId | Sorter etter emne-ID, f.eks. 123456 (dette er vanligvis et heltall) | Overordnede og problemrelaterte endepunkter | endpoint-url?sort=courseId |
termId | Sorter etter semester-ID. F.eks. Sum | Overordnede og problemrelaterte endepunkter | endpoint-url?sort=termId |
termName | Sorter etter semesternavn. f.eks. sommer | Overordnede og problemrelaterte endepunkter | 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 |
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=<Sorter parameterverdi>&order=<Ordreverdi>
Der <Rekkefølgeverdi> 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 til å få mindre eller reduserte svar basert på de valgte kriteriene. Hvis du må legge til et filtreringsalternativ, må du legge til filtreringsparameteret som beskrevet nedenfor:
Filterparametre (uten operatør)
Navn på filterparameteren | Beskrivelse | Støttes i |
allyEnabled | Du kan laste ned emnene der Ally er aktiv Verdien er sann eller usann | Generelle og problemendepunkter |
departmentId | Filtrer etter avdelings-ID | Overordnede og problemrelaterte endepunkter |
departmentName | Filtrer etter avdelingsnavn. f.eks.Ingeniør | Overordnede og problemrelaterte endepunkter |
termId | Filtrer etter semester-ID | Overordnede og problemrelaterte endepunkter |
termName | Filtrer etter semesternavn. f.eks. sommer | Overordnede og problemrelaterte endepunkter |
courseId | Filtrer etter ID-en eller et emne. f.eks. 123456 (dette er vanligvis et heltall) | Overordnede og problemrelaterte endepunkter |
courseName | Filtrer etter navnet på et emne. F.eks. Kjemi 101 (courseCode er ikke gyldig) | Overordnede og problemrelaterte endepunkter |
endpoint-url?<Filtrer parameter>=<value>
Filterparametere (med operatør)
endpoint-url?<Filtrer parameter>=<Operatør>:<value>
Hvor:
- <Filtrer parameter>: Filtreringsparameter for å få et mindre sett med resultater. Du kan se de støttede parametrene i tabellen nedenfor.
- <Operatør>: 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 laste ned emnene der Ally er aktiv Verdien er sann eller usann. | Overordnede og problemrelaterte endepunkter |
courseName | Streng | eq, ne, co, nc, sw | Filtrer etter navnet på et emne. F.eks. Kjemi 101 (courseCode er ikke gyldig) | Overordnede og problemrelaterte endepunkter |
courseId | Streng | eq, ne, co, nc, sw | Filtrer etter ID-en eller et emne. F.eks. 123456 (dette er vanligvis et heltall) | Overordnede og problemrelaterte endepunkter |
termId | Streng | eq, ne, co, nc, sw | Filtrer etter semester-ID. | Overordnede og problemrelaterte endepunkter |
termName | Streng | eq, ne, co, nc, sw | Filtrer etter semesternavn. f.eks. sommer | Overordnede og problemrelaterte endepunkter |
overallScore | Nummer | eq, ne, le, lt, ge, gt | Du kan filtrere etter en samlet poengsum. f.eks. emner med en poengsum lik 90 % | Overordnet endepunkt og i alle Ally-løsninger: LMS, nettsteder og WCM. |
filesScore | Nummer | eq, ne, le, lt, ge, gt | Du kan filtrere etter filenes poengsum. f.eks. emner med en filpoengsum på 90 % | Overordnet endepunkt og i alle Ally-løsninger: LMS, nettsteder og WCM. |
wysiwygScore | Nummer | eq, ne, le, lt, ge, gt | Du kan filtrere etter WYSIWYG-poengsummen. f.eks. emner med en WYSIWYG-poengsum 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. |
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
Bruke 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