Pwyntiau Gorffen API Adroddiadau

Mae'r pwyntiau gorffen sydd wedi'u cynnwys yn yr API ar gyfer adroddiadau yn bwyntiau gorffen preifat ac nid oes ganddynt bolisi anghymeradwyo ar hyn o bryd. Gall Antholeg Ally newid neu ddiweddaru'r pwyntiau gorffen hyn yn dibynnu ar ein map ffordd neu fersiynau rydym yn eu rhyddhau yn y dyfodol.

Adolygwch y ddogfennaeth dechnegol ganlynol i ddysgu sut i osod ac addasu eich pwyntiau gorffen yn briodol. Mae croeso i chi fwrw golwg ar sut i integreiddio API Ally ag Offeryn Adroddiadau Allanol i gael arweiniad ychwanegol. 

Dulliau sydd ar gael

Mae gan API Ally ar gyfer adroddiadau ddau ddull. Mae'r adran ganlynol yn eu disgrifio: 

Rhowch eich ID Ally yn lle [ID Cleient Ally]. Os nad ydych yn gwybod eich ID, gallwch greu tocyn cymorth i ofyn amdano.

Newidiwch [Rhanbarth] yn seiliedig ar y rhanbarth mae amgylchedd Ally eich sefydliad wedi'i letya ynddi:

• Canolfan ddata UDA: prod.ally.ac
• Canolfan ddata Canada: prod-ca-central-1.ally.ac
• Canolfan ddata Ewrop: prod-eu-central-1.ally.ac
• Canolfan ddata Singapôr: prod-ap-southeast-1.ally.ac
• Canolfan ddata Awstralia: prod-ap-southeast-2.ally.ac

Gall y wybodaeth uchod amrywio yn dibynnu ar yr LMS. Gallwch adolygu diffiniad y golofn yn Nogfennaeth yr Adroddiad Cwrs ar gyfer pob LMS:

• Blackboard Learn
• Moodle
• D2L Brightspace
• Instructure Canvas

Ymateb Statws HTTP 

Mae API Ally yn cynnwys maes statws yn y metaddata fel a ganlyn:

• Statws 200 - Llwyddiannus: Derbyniwyd eich cais yn llwyddiannus ac mae'r set ddata y gofynnwyd amdani yn rhan o'r ymateb. 
• Statws 202 - Wrthi'n prosesu: Derbyniwyd eich cais yn llwyddiannus ond mae'r set ddata wrthi'n cael ei pharatoi, ac nid yw ar gael eto. Gwnewch eich cais eto ar ôl ychydig o amser (argymhellir aros un munud ar y lleiaf).
• Statws 401 - Heb awdurdodi: Nid yw'r ID Cleient Ally neu'r tocyn awdurdodi yn gywir.
• Statws 400 - Cais gwael: Mae gan yr URL enw paramedr annilys, er enghraifft, opsiwn hidlo, gweithredydd neu werth anhysbys. Adolygwch gystrawen yr URL. Cofiwch fod rhai o'r opsiynau hidlo a threfnu yn gwahaniaethu rhwng llythrennau bach a phriflythrennau. 

Dogfennaeth Dulliau 

Dull: Cyffredinol 

Cais HTTP: CAEL
https:// [Rhanbarth]/api/v2/clients/[ID Cleient Ally]/reports/overall 

Rhowch eich ID Ally yn lle [ID Cleient Ally]. Os nad ydych yn gwybod eich ID, gallwch greu tocyn cymorth i ofyn amdano.  

Newidiwch [Rhanbarth] yn seiliedig ar y rhanbarth mae amgylchedd Ally eich sefydliad wedi'i letya ynddi:

• Canolfan ddata UDA: prod.ally.ac
• Canolfan ddata Canada: prod-ca-central-1.ally.ac
• Canolfan ddata Ewrop: prod-eu-central-1.ally.ac
• Canolfan ddata Singapôr: prod-ap-southeast-1.ally.ac
• Canolfan ddata Awstralia: prod-ap-southeast-2.ally.ac

Awdurdodi: Tocyn cludwr OAuth. 

Paramedrau: Hidlyddion neu opsiynau trefnu dewisol. 

Corff y Cais: Dim 

Ymateb: 

{ 
    "data": [ 
        { 
            "application/x-quiz": 2, 
            "observedDeletedOn": "", 
            "termName": "Hydref 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": "Bioleg 101", 
            "application/x-discussion-topic": 1, 
            "other": 11, 
            "overallScore": 0.6129724428830603, 
            "presentation": 5 
        } 
], 
    "metadata": {
    "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "Wrthi'n prosesu", 
        "from": 1 
    } 
} 

Dull: Problemau 

Cais HTTP: CAEL 
https:// [Rhanbarth]/api/v2/clients/[ID Cleient Ally]/reports/overall 

Rhowch eich ID Ally yn lle [ID Cleient Ally]. Os nad ydych yn gwybod eich ID, gallwch greu tocyn cymorth i ofyn amdano. 

Newidiwch [Rhanbarth] yn seiliedig ar y rhanbarth mae amgylchedd Ally eich sefydliad wedi'i letya ynddi:

• Canolfan ddata UDA: prod.ally.ac
• Canolfan ddata Canada: prod-ca-central-1.ally.ac
• Canolfan ddata Ewrop: prod-eu-central-1.ally.ac
• Canolfan ddata Singapôr: prod-ap-southeast-1.ally.ac
• Canolfan ddata Awstralia: prod-ap-southeast-2.ally.ac

Awdurdodi: Tocyn cludwr OAuth  

Paramedrau: Hidlyddion neu opsiynau trefnu dewisol. 

Corff y Cais: Dim 

Ymateb: 

{ 
    "data": [ 
        { 
            "imageDecorative2": 4, 
            "htmlEmptyHeading2": 0, 
            "imageSeizure1": 2, 
            "observedDeletedOn": "", 
            "htmlObjectAlt2": 0, 
            "security1": 3, 
            "termName": "Hydref 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": "Bioleg 101", 
            "imageContrast2": 0, 
            "imageDescription2": 4, 
            "htmlTitle3": 1, 
            "parsable1": 2 
        } 
], 
    "metadata": { 
        "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "Wrthi'n prosesu", 
        "from": 1 
    } 
} 

Ble: 

• Data: yn cynnwys set ddata'r canlyniadau. 
• Metaddata: 
  • I: cofnod y caiff data ei nôl iddo, mae'n "gwrthbwys" + "terfyn" neu'n "cyfanswm" os yw'r swm yn fwy na'r "cyfanswm". 
  • O: cofnod y bydd y data yn dechrau ohono, mae'n “gwrthbwys” + 1. 
  • Cyfanswm: cyfanswm y cyrsiau a ystyrir gan Ally yn enghraifft yr LMS. 

Gwrthbwys - pa gofnod y bydd yn dechrau ohono 

• Mae'r rhes gyntaf yn wrthbwys = 0, 
• Pan fydd gwrthbwys < 0 bydd y defnyddiwr yn cael gwall 400 - [Gwerth annilys (paramedr=gwrthbwys, neges=Dim data o'r fath)], 
• Pan fydd (gwrthbwys >= cyfanswm) => bydd y defnyddiwr yn cael gwall 400 - [Gwerth annilys (paramedr=gwrthbwys, neges=Dim data o'r fath)] 

Terfyn - faint o gofnodion sy'n cael eu nôl gan ddechrau o'r gwrthbwys 

• Pan fydd (terfyn < 1) bydd y defnyddiwr yn cael gwall 400 - [Gwerth annilys (paramedr=terfyn, neges=Mae'r terfyn y tu allan i'r ffiniau)]
• Pan fydd (terfyn > 10000) bydd y defnyddiwr yn cael gwall 400 - [Gwerth annilys (paramedr=terfyn, neges=Mae'r terfyn y tu allan i'r ffiniau)] 
• Pan fydd (gwrthbwys < cyfanswm && gwrthbwys + terfyn > cyfanswm) byddwn yn newid y terfyn yn y cefndir i chi, a chaiff y data ei nôl tan y (cyfanswm) olaf 

Hidlyddion ac opsiynau trefnu 

Mae modd hidlo ymatebion Pwyntiau Gorffen yn yr URL. Mae'r adran hon yn disgrifio'r opsiynau sydd ar gael: 

Opsiynau trefnu 

Gallwch ddiffinio a ydych eisiau dangos y canlyniadau wedi'u trefnu yn esgynnol neu'n ddisgynnol gan ystyried un maen prawf. Os oes angen i chi ychwanegu opsiwn trefnu, bydd yn rhaid i chi ychwanegu'r paramedr trefnu fel y'i disgrifir isod:

endpoint-url?sort=<Gwerth paramedr trefnu> 

Lle gall <Gwerth paramedr trefnu> fod yn unrhyw un o'r gwerthoedd paramedr canlynol: 

Mae gwerthoedd paramedr yn gwahaniaethu rhwng priflythrennau a llythrennau bach, ac mae dim ond modd defnyddio un opsiwn trefnu ar y tro. 

Yn ddiofyn, mae'r canlyniadau'n cael eu trefnu'n esgynnol. Os ydych eisiau gosod trefn wahanol, gallwch ychwanegu'r paramedr trefnu: 

endpoint-url?sort=<Gwerth paramedr trefnu>&order=<Gwerth trefnu> 

Lle gall <Gwerth trefnu> fod yn: asc neu desc 

Enghraifft: 

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

Opsiynau hidlo 

Gallwch ddefnyddio opsiynau hidlo i gael ymatebion llai neu lai o ymatebion yn seiliedig ar y meini prawf a ddewiswyd.  Os oes angen i chi ychwanegu opsiwn hidlo, bydd yn rhaid i chi ychwanegu'r paramedr hidlo fel y'i disgrifir isod:

Paramedrau Hidlo (heb weithredydd) 

 endpoint-url?<Paramedr Hidlo>=<gwerth> 

Paramedrau Hidlo (gyda gweithredydd) 

endpoint-url?<Paramedr Hidlo>=<Gweithredydd>:<gwerth> 

Ble: 

• <Paramedr Hidlo>: Paramedr hidlo i gael set lai o ganlyniadau. Gallwch weld y paramedrau a gefnogir yn y tabl isod. 
• <Gweithredydd>: Mae'n rhaid i chi ddefnyddio gweithredydd i hidlo, fel yn hafal, neu ddim yn hafal. 
• <gwerth>: Gwerth a ddefnyddir yn yr hidlydd. 

Mae gwerthoedd paramedrau'n gwahaniaethu rhwng priflythrennau a llythrennau bach.

Gweithredyddion a Gefnogir

Mae'r tabl canlynol yn cynnwys y gweithredyddion a gefnogir yn seiliedig ar y math o faes: 

Enghraifft: 

Mae'r enghraifft ganlynol yn nôl yr holl gyrsiau sy'n cynnwys yr allweddair "profion" yn enw'r cwrs:

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

Defnyddio hidlyddion lluosog 

Gallwch gyfuno'r opsiynau trefnu a hidlo yn yr un URL pwynt gorffen drwy ychwanegu'r nod "&" rhwng y ddau amod. Er enghraifft, gadewch i ni ddweud eich bod am nôl yr holl gyrsiau sy'n cynnwys yr allweddair "prawf" yn enw'r cwrs lle mae Ally wedi'i alluogi, ac mae'r sgôr cyffredinol yn llai na 90%. Byddai'r URL yn edrych fel hyn:

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

Gallwch hefyd ddefnyddio dau opsiwn hidlo. Er enghraifft, gadewch i ni ddweud bod angen i chi gael yr holl gyrsiau sydd â sgôr cyffredinol rhwng 10% a 70%:

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