Slutpunkter i API för rapportering
Slutpunkter i API för rapportering
Varning
Slutpunkter som ingår i API för rapportering är privata slutpunkter och har för närvarande ingen inaktualitetspolicy. Anthology Ally kan ändra eller uppdatera dessa slutpunkter beroende på vår planering eller framtida versioner.
Läs följande tekniska dokumentation för att få reda på hur du konfigurerar och anpassar dina slutpunkter på rätt sätt. Läs gärna igenom Hur man integrerar Ally API med ett externt rapporteringsverktyg för ytterligare vägledning.
Tillgängliga metoder
Ally API för rapportering har två metoder. De beskrivs i följande avsnitt:
Metod | URL | Typ av HTTP-begäran | Beskrivning |
Övergripande | https://[region]/api/v2/clients/[Ally Client ID]/reports/overall | Hämta | Som standard returnerar den här metoden en datauppsättning med information om kursen, WYSIWYG samt filernas poäng och filtyper som ingår i varje kurs från LMS-instansen, oavsett om Ally är aktiverat eller inte. |
Problem | https://[Region]/api/v2/clients/[Ally Client ID]/reports/issues | Hämta | Som standard returnerar den här metoden en datauppsättning med informationen som hör samman med åtkomstproblem som finns i alla kurser som ingår i LMS-instansen, oavsett om Ally är aktiverat eller inte. |
Tips
Byt ut [Ally Client ID] med ditt Ally ID. Om du inte känner till ditt id kan du skapa ett supportärende för att begära det.
Tips
Byt ut [Region] beroende på vilken region där Ally-miljön i ditt lärosäte är värd:
Datacenter i USA: prod.ally.ac
Kanadensiskt datacenter: prod-ca-central-1.ally.ac
Datacentral i Europa: prod-eu-central-1.ally.ac
Datacenter i Singapore: prod-ap-southeast-1.ally.ac
Datacenter i Australien: prod-ap-southeast-2.ally.ac
Svar på HTTP-status
Ally API:n innehåller ett statusfält i metadatan enligt följande:
Status 200 – Lyckades: Din begäran har tagits emot och den begärdadatauppsättningen är en del av svaret.
Status 202 – Bearbetar: Din begäran har tagits emot men datauppsättningenhåller på att förberedas och är inte tillgänglig ännu. Upprepa din begäran efter en tid (minst en minut rekommenderas).
Status 401 - Obehörig: Allys klient-ID eller auktoriseringstoken är inte korrekta.
Status 400 – Felaktig begäran: URL:en har ett ogiltigt parameternamn, till exempel ett okänt filteralternativ, en operator eller ett okänt värde. Granska syntaxen för URL. Kom ihåg att vissa av filtrerings- och sorteringsalternativen är skiftlägeskänsliga.
Dokumentation av metoder
Metod: Övergripande
HTTP-begäran: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Byt ut [Ally Client ID] med ditt Ally ID. Om du inte känner till ditt id kan du skapa ett supportärende för att begära det.
Byt ut [Region] beroende på vilken region där Ally-miljön i ditt lärosäte är värd:
Datacenter i USA: prod.ally.ac
Kanadensiskt datacenter: prod-ca-central-1.ally.ac
Datacentral i Europa: prod-eu-central-1.ally.ac
Datacenter i Singapore: prod-ap-southeast-1.ally.ac
Datacenter i Australien: prod-ap-southeast-2.ally.ac
Auktorisering: OAuth-ägartoken.
Parametrar: Valfria filter eller sorteringsalternativ.
Begäran: 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
}
} Metod: Problem
HTTP-begäran: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Ersätt ID [Ally Client ID] med ditt Ally-ID. Om du inte känner till ditt id kan du skapa ett supportärende för att begära det.
Byt ut [Region] beroende på vilken region där Ally-miljön i ditt lärosäte är värd:
Datacenter i USA: prod.ally.ac
Kanadensiskt datacenter: prod-ca-central-1.ally.ac
Datacentral i Europa: prod-eu-central-1.ally.ac
Datacenter i Singapore: prod-ap-southeast-1.ally.ac
Datacenter i Australien: prod-ap-southeast-2.ally.ac
Auktorisering: OAuth-ägartoken
Parametrar: Valfria filter eller sorteringsalternativ.
Begäran: 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
}
} Där:
Data: innehåller datauppsättningen för resultaten.
Metadata:
Att: registrera till vilken data som hämtas, det är "offset" + "limit" eller "total" om summan överstiger "total".
Från: post från vilken data kommer att starta, det är "offset" + 1.
Totalt: det totala antalet kurser som övervägs av Ally i LMS-instansen.
Offset - från vilken posten startar
Första raden är offset = 0,
När offset < 0, då får användaren fel 400 400 - [Invalid value (parameter=offset, message=No such data)],
När (offset >= totalt) => får användaren fel 400 - [Invalid value (parameter=offset, message=No such data) ]
Gräns – hur många poster som hämtas från och med offset
När (gräns < 1), då får användaren fel 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)]
När (gräns > 10000) får användaren fel 400 - [Invalid value (parameter=limit, message=Limit out of boundaries)]
När (offset < total && offset + limit > total), ändrar vi gränsen i bakgrunden för dig, och data hämtas fram till sista (total)
Filter och sorteringsalternativ
Slutpunktssvar kan filtreras i URL:en. I det här avsnittet beskrivs de tillgängliga alternativen:
Sorteringsalternativ
Du kan definiera om du vill visa resultaten sorterade i stigande eller fallande ordning med ett villkor. Om du behöver lägga till ett sorteringsalternativ måste du lägga till sorteringsparametern enligt beskrivningen nedan:
endpoint-url?sort=<Sort parameter value>
Där <Sortera parametervärde> kan vara något av följande parametervärden:
Parametervärde | Beskrivning | Stöds i | Exempel |
courseName | Sortera efter kursnamn, t.ex. Kemi 101 (courseCode är inte giltig) | Övergripande slutpunkter och problemslutpunkter | endpoint-URL?sort=courseName |
courseId | Sortera efter kurs-ID, t.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problemslutpunkter | endpoint-URL?sort=courseId |
termId | Sortera efter termin-id. T.ex. summar | Övergripande slutpunkter och problemslutpunkter | endpoint-URL?Sort=termId |
termName | Sortera efter namnet på terminen. t.ex. Sommar | Övergripande slutpunkter och problemslutpunkter | endpoint-url?sort=termName |
overallScore | Sortera efter den övergripande tillgänglighetspoängen för varje kurs. | Endast övergripande slutpunkt. | endpoint-url?sort=overallScore |
filesScore | Sortera resultaten efter filpoäng för varje kurs. | Endast övergripande slutpunkt. | endpoint-URL?Sort=filesScore |
wysiwygScore | Sortera resultaten efter WYSIWYG-poängen för varje kurs. | Övergripande slutpunkt och endast tillgänglig för Ally för LMS. | endpoint-url?sort= wysiwygScore |
webPagesScore | Sortera resultaten efter webbsidans poäng för varje domän. | Övergripande slutpunkt och endast tillgänglig för Ally för webben och WCM. | endpoint-URL?sort= webPagesScore |
Notera
Parametervärden är skiftlägeskänsliga och endast ett sorteringsalternativ kan användas åt gången.
Som standard sorteras resultaten i stigande ordning. Om du vill ange en annan ordning kan du lägga till sorteringsparametern:
endpoint-url?sort=<Sort parameter value>&order=<Order value>
Där <Ordervärde> kan vara: asc eller desc
Exempel:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Filtreringsalternativ
Du kan använda filtreringsalternativ för att få mindre eller färre svar baserat på de valda villkoren. Om du behöver lägga till ett filtreringsalternativ måste du lägga till filtreringsparametern enligt beskrivningen nedan:
Filterparametrar (utan operator)
Filterparameternamn | Beskrivning | Stöds i |
allyEnabled | Du kan hämta kurserna där Ally är aktivt. Värdet är sant eller falskt | Övergripande slutpunkter och problemslutpunkter |
departmentId | Filtrera efter avdelnings-id | Övergripande slutpunkter och problemslutpunkter |
avdelningsNamn | Filtrera efter avdelningens namn, t.ex. Teknik | Övergripande slutpunkter och problemslutpunkter |
termId | Filtrera efter termin-id | Övergripande slutpunkter och problemslutpunkter |
termName | Filtrera efter namnet på terminen, t.ex. Sommar | Övergripande slutpunkter och problemslutpunkter |
courseId | Filtrera efter ID eller kurs. t.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problemslutpunkter |
courseName | Filtrera efter namnet på en kurs. T.ex. Kemi 101 (courseCode är inte giltig) | Övergripande slutpunkter och problemslutpunkter |
endpoint-url?<Filter Parameter>=<value>
Filterparametrar (med operator)
endpoint-url?<Filter Parameter>=<Operator>:<value>
Där:
<Filterparameter>: Filtreringsparameter för att få en mindre uppsättning resultat. Du kan se de parametrar som stöds i tabellen nedan.
<Operator>: Du måste använda en operator för att filtrera, till exempel lika med, inte lika med.
<värde>: Värde som används i filtret.
Filterparameternamn | Fälttyp | Operatorer som stöds | Beskrivning | Stöds i |
allyEnabled | Boolesk | eq, ne | Du kan hämta kurserna där Ally är aktivt. Värdet är sant eller falskt. | Övergripande slutpunkter och problemslutpunkter |
courseName | Sträng | eq, ne, co, nc, sw | Filtrera efter namnet på en kurs. T.ex. Kemi 101 (courseCode är inte giltig) | Övergripande slutpunkter och problemslutpunkter |
courseId | Sträng | eq, ne, co, nc, sw | Filtrera efter kurs-id. T.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problemslutpunkter |
termId | Sträng | eq, ne, co, nc, sw | Filtrera efter termin-id. | Övergripande slutpunkter och problemslutpunkter |
termName | Sträng | eq, ne, co, nc, sw | Filtrera efter namnet på termen. t.ex. Sommar | Övergripande slutpunkter och problemslutpunkter |
overallScore | Siffra | eq, ne, le, lt, ge, gt | Du kan filtrera efter totalpoäng, t.ex. kurser med en poäng motsvarande 90 % | Övergripande slutpunkt och i alla Ally-lösningar: LMS, webbplatser och WCM. |
filesScore | Siffra | eq, ne, le, lt, ge, gt | Du kan filtrera efter filpoäng, t.ex. kurser med filpoäng lika med 90 % | Övergripande slutpunkt och i alla Ally-lösningar: LMS, webbplatser och WCM. |
wysiwygScore | Siffra | eq, ne, le, lt, ge, gt | Du kan filtrera efter WYSIWYG-poängen. t.ex. kurser med en WYSIWYG-poäng lika med 90 % | Övergripande slutpunkt och endast tillgänglig för Ally för LMS. |
webPagesScore | Siffra | eq, ne, le, lt, ge, gt | Du kan filtrera efter poängen för en domän. t.ex. webbsidor med en poäng på 90 %. | Övergripande slutpunkt och endast tillgänglig för Ally för webben eller WCM. |
Notera
Parametervärden är skiftlägeskänsliga.
Operatorer som stöds
I följande tabell visas de operatorer som stöds baserat på fälttypen:
Fälttyp | Operator | Beskrivning |
Sträng | eq | Är lika med |
Sträng | ne | Är inte lika |
Sträng | co | Innehåller nyckelord |
Sträng | nc | Innehåller inte nyckelord |
Sträng | sw | Börjar med nyckelord |
Siffra | eq | Är lika med |
Siffra | ne | Är inte lika |
Siffra | le | Mindre än eller lika med |
Siffra | lt | Mindre än |
Siffra | ge | Större än eller lika med |
Siffra | gt | Större än |
Exempel:
I följande exempel hämtas alla kurser som innehåller nyckelordet "prov" i kursnamnet:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Använda flera filter
Du kan kombinera sorterings- och filtreringsalternativen i samma slutpunkts-URL genom att lägga till tecknet "&" mellan de två villkoren. Anta till exempel att du vill hämta alla kurser som innehåller nyckelordet "prov" i kursnamnet, där Ally är aktiverat och den övergripande poängen är lägre än 90 %. URL:en skulle se ut så här:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
Du kan också använda två filtreringsalternativ. Anta till exempel att du ska ta fram alla kurser som har en övergripande poäng mellan 10 % och 70 %:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7