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. |
Ersätt [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.
Ersätt [Region] beroende på den region där Ally-miljön för ditt lärosäte finns:
- Datacenter i USA: prod.ally.ac
- Kanadensiskt datacenter: prod-ca-central-1.ally.ac
- Datacenter 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
Informationen ovan kan variera beroende på LMS. Du kan granska kolumndefinitionen i dokumentationen för kursrapporten för varje LMS:
HTTP-statussvar
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ärda datauppsättningen är en del av svaret.
- Status 202 – Bearbetar: Din begäran har tagits emot, men datauppsättningen är under förberedelse och är inte tillgänglig ännu. Upprepa din begäran efter en tid (minst en minut rekommenderas).
- Status 401 – Obehörig: Ally 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 filter- och sorteringsalternativen är skiftlägeskänsliga.
Metoddokumentation
Metod: Övergripande
HTTP request: GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Ersätt [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.
Ersätt [Region] beroende på den region där Ally-miljön för ditt lärosäte finns:
- Datacenter i USA: prod.ally.ac
- Kanadensiskt datacenter: prod-ca-central-1.ally.ac
- Datacenter 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.
Text för 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: Porblem
HTTP request: 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.
Ersätt [Region] beroende på den region där Ally-miljön för ditt lärosäte finns:
- Datacenter i USA: prod.ally.ac
- Kanadensiskt datacenter: prod-ca-central-1.ally.ac
- Datacenter 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.
Text för 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
}
}
Var:
- Data: innehåller datauppsättningen för resultaten.
- Metadata:
- Till: post till vilken data kommer att hämtas, det är ”förskjutning” + ”begränsning” eller ”totalt” om summan överstiger ”totalt”.
- Från: post från vilken data kommer att starta, dvs. ”förskjutning” + 1.
- Summa: totalt antal kurser som Ally tar i beaktande för LMS-instansen.
Förskjutning – från vilken posterna börjar
- Första raden är förskjuten = 0,
- Vid förskjutning < 0 visas felmeddelandet felkod 400 – [Ogiltigt värde (parameter=förskjutning, meddelande=Inga sådana data)],
- När (förskjutning >= totalt) => visas felmeddelandet felkod 400 – [Ogiltigt värde (parameter=förskjutning, meddelande=Inga sådana data)]
Begränsning – hur många poster som hämtas, med start vid förskjutningen
- När (begränsning < 1) visas felmeddelandet felkod 400 – [Ogiltigt värde (parameter=begränsning, meddelande=Begränsning utanför gränserna)]
- När (begränsning > 10000) visas felmeddelandet felkod 400 – [Ogiltigt värde (parameter=begränsning, meddelande=Begränsning utanför gränserna)]
- När (förskjutning < totalt && förskjutning + begränsning > totalt) ändrar vi gränsen åt dig i bakgrunden och data hämtas till slutet (totalt)
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 <Sort parameter value> kan vara en av följande parametervärden:
| Parametervärde | Beskrivning | Stöd i | Exempel |
| courseName | Sortera efter kursnamn, t.ex. Kemi 101 (courseCode är inte giltigt) | Övergripande slutpunkter och problem | endpoint-url?sort=courseName |
| courseId | Sortera efter kurs-ID, t.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problem | endpoint-url?sort=courseId |
| termId | Sortera efter termin-ID. T.ex. Summ | Övergripande slutpunkter och problem | endpoint-url?sort=termId |
| termName | Sortera efter terminens namn. t.ex. sommar | Övergripande slutpunkter och problem | 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 |
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 <Order value> 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 reducerade svar baserat på de valda kriterierna. Om du behöver lägga till ett filtreringsalternativ måste du lägga till filtreringsparametern enligt beskrivningen nedan:
Filterparametrar (utan operator)
| Namn på filterparameter | Beskrivning | Stöds i |
| allyEnabled | Du kan hämta de kurser där Ally är aktivt Värdet är sant eller falskt | Övergripande slutpunkter och problemslutpunkter |
| departmentId | Filtrera efter avdelnings-id | Övergripande slutpunkter och problem |
| departmentName | Filtrera efter avdelningsnamn, t.ex. Ingenjörsvetenskap | Övergripande slutpunkter och problem |
| termId | Filtrera efter termin-id | Övergripande slutpunkter och problem |
| termName | Filtrera efter terminnamn. t.ex. Sommar | Övergripande slutpunkter och problem |
| courseId | Filtrera efter kurs-ID, t.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problem |
| courseName | Filtrera efter namnet på en kurs. T.ex. Kemi 1 (courseCode är inte giltigt) | Övergripande slutpunkter och problem |
endpoint-url?<Filter Parameter>=<value>
Filterparametrar (med operator)
endpoint-url?<Filter Parameter>=<Operator>:<value>
Var:
- <Filter Parameter>: 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, som lika med eller inte lika med.
- <value>: Value used in the filter.
| Namn på filterparameter | Fälttyp | Operatorer som stöds | Beskrivning | Stöds i |
| allyEnabled | Boolesk | eq, ne | Du kan hämta de kurser där Ally är aktivt Värdet är sant eller falskt. | Övergripande slutpunkter och problem |
| courseName | Sträng | eq, ne, co, nc, sw | Filtrera efter namnet på en kurs. T.ex. Kemi 1 (courseCode är inte giltigt) | Övergripande slutpunkter och problem |
| courseId | Sträng | eq, ne, co, nc, sw | Filtrera efter kurs-id. T.ex. 123456 (detta är vanligtvis ett heltal) | Övergripande slutpunkter och problem |
| termId | Sträng | eq, ne, co, nc, sw | Filtrera efter termin-id. | Övergripande slutpunkter och problem |
| termName | Sträng | eq, ne, co, nc, sw | Filtrera efter terminnamn. t.ex. Sommar | Övergripande slutpunkter och problem |
| overallScore | Siffra | eq, ne, le, lt, ge, gt | Du kan filtrera efter en övergripande poäng. t.ex. kurser med en poäng på 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 filens poäng. t.ex. kurser med en filpoäng på 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äng, t.ex. kurser med en WYSIWYG-poäng på 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. |
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 med |
| 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 med |
| 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
