Rapportere API-endepunkter

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: 

MetodeNettadresseType HTTP-forespørselBeskrivelse
Generellhttps://[region]/api/v2/clients/[Ally Client ID]/reports/overallSom 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.
Problemerhttps://[region]/api/v2/clients/[Ally Client ID]/reports/issuesSom 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:

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:

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:

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: 

ParameterverdiBeskrivelseStøttes iEksempel
courseName&nbsp;Sorter etter emnenavn.  f.eks. kjemi 101
(courseCode er ikke gyldig)
Overordnede og problemrelaterte endepunkter endpoint-url?sort=courseName 
courseIdSorter 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 
termNameSorter etter semesternavn. f.eks. sommer Overordnede og problemrelaterte endepunkter endpoint-url?sort=termName 
overallScoreSorter etter det samlede tilgjengelighetsresultatet for hvert emne.   Bare totalt endepunkt.endpoint-url?sort=overallScore 
filesScoreSorter resultatene etter filpoengsummen for hvert emne. Bare totalt endepunkt.endpoint-url?sort=filesScore 
wysiwygScoreSorter resultatene etter WYSIWYG-poengsummen for hvert emne. Samlet endepunkt og bare tilgjengelig for Ally for LMS. endpoint-url?sort= wysiwygScore 
webPagesScoreSorter 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:&nbsp;

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-IDOverordnede og problemrelaterte endepunkter 
departmentName Filtrer etter avdelingsnavn. f.eks.Ingeniør Overordnede og problemrelaterte endepunkter 
termIdFiltrer etter semester-IDOverordnede og problemrelaterte endepunkter 
termName Filtrer etter semesternavn. f.eks. sommer Overordnede og problemrelaterte endepunkter 
courseIdFiltrer etter ID-en eller et emne. f.eks. 123456
(dette er vanligvis et heltall) 
Overordnede og problemrelaterte endepunkter 
courseName&nbsp;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:&nbsp;

  • <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 
allyEnabledBoolskeq, neDu kan laste ned emnene der Ally er aktiv 
Verdien er sann eller usann. 
Overordnede og problemrelaterte endepunkter 
courseNameStrengeq, ne, co, nc, sw Filtrer etter navnet på et emne. F.eks. Kjemi 101
(courseCode er ikke gyldig)
Overordnede og problemrelaterte endepunkter 
courseIdStrengeq, ne, co, nc, sw Filtrer etter ID-en eller et emne. F.eks. 123456
(dette er vanligvis et heltall) 
Overordnede og problemrelaterte endepunkter 
termIdStrengeq, ne, co, nc, sw Filtrer etter semester-ID. Overordnede og problemrelaterte endepunkter 
termNameStrengeq, ne, co, nc, sw Filtrer etter semesternavn. f.eks. sommer Overordnede og problemrelaterte endepunkter 
overallScoreNummereq, 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.
filesScoreNummereq, 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.
wysiwygScoreNummereq, 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. 
webPagesScoreNummereq, 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: 

FelttypeOperatørBeskrivelse
StrengeqEr lik 
StrengneEr ikke lik 
StrengcoInneholder nøkkelord 
StrengncInneholder ikke nøkkelord 
StrengswStarter med nøkkelord 
NummereqEr lik 
NummerneEr ikke lik 
NummerleMindre enn eller lik 
NummerltMindre enn 
NummergeStørre enn eller lik 
NummergtStørre enn 

Eksempel:&nbsp;

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