Raporlama API'si Uç Noktaları

Raporlama API'sine dâhil edilen uç noktalar, özel uç noktalardır ve şu anda bunlarla ilgili bir kullanımdan kaldırma ilkesi bulunmamaktadır. Anthology Ally, yol haritamıza veya gelecekteki sürümlere bağlı olarak bu uç noktaları değiştirebilir veya güncelleştirebilir.

Uç noktalarınızı uygun şekilde nasıl ayarlayacağınızı ve özelleştireceğinizi öğrenmek için aşağıdaki teknik belgeleri gözden geçirin. Ek yönergeler için, Ally'ın API'si, Haricî Raporlama Aracı ile nasıl entegre edilir? konusuna bakabilirsiniz.

Mevcut yöntemler

Ally'ın raporlama API'sinde, iki yöntem mevcuttur. Aşağıdaki bölümde bunlar açıklanmaktadır:

[Ally İstemci Kimliği] yerine Ally kimliğinizi girin. Kimliğinizi bilmiyorsanız talep etmek için bir destek bileti oluşturabilirsiniz.

[Bölge] yerine ise kurumunuza ait Ally ortamının barındırıldığı bölgeye göre şunlardan birini girin:

• ABD veri merkezi: prod.ally.ac
• Kanada veri merkezi: prod-ca-central-1.ally.ac
• Avrupa veri merkezi: prod-eu-central-1.ally.ac
• Singapur veri merkezi: prod-ap-southeast-1.ally.ac
• Avustralya veri merkezi: prod-ap-southeast-2.ally.ac

Yukarıdaki bilgiler, LMS'ye bağlı olarak değişebilir. Her LMS için Kurs Raporu Belgelerindeki sütun tanımını inceleyebilirsiniz:

• Blackboard Learn
• Moodle
• D2L Brightspace
• Instructure Canvas

HTTP Durum Yanıtı

Ally API'si, meta verilerde aşağıdaki gibi bir durum alanı içerir:

• Durum 200 - Başarılı: İsteğiniz başarılı bir biçimde alındı ve istenen veri kümesi, yanıtın içinde yer alıyor.
• Durum 202 - İşleniyor: İsteğiniz başarılı bir biçimde alındı ancak veri kümesi, hazırlanma aşamasında ve henüz kullanılamıyor. İsteğinizi bir süre sonra tekrarlayın (en az bir dakika beklemeniz önerilir).
• Durum 401 - Yetkisiz: Ally İstemci Kimliği veya yetkilendirme belirteci doğru değil.
• Durum 400 - Geçersiz istek: URL'nin içinde, bilinmeyen bir filtre seçeneği, işleç veya değer gibi geçersiz bir parametre adı mevcut. URL'nin söz dizimini gözden geçirin. Bazı filtre ve sıralama seçeneklerinin büyük/küçük harfe duyarlı olduğunu unutmayın.

Yöntemlere İlişkin Belgeler

Yöntem: Genel

HTTP isteği: GET
https:// [Bölge]/api/v2/clients/[Ally İstemci Kimliği]/reports/overall 

[Ally İstemci Kimliği] yerine Ally kimliğinizi girin. Kimliğinizi bilmiyorsanız talep etmek için bir destek bileti oluşturabilirsiniz.

[Bölge] yerine ise kurumunuza ait Ally ortamının barındırıldığı bölgeye göre şunlardan birini girin:

• ABD veri merkezi: prod.ally.ac
• Kanada veri merkezi: prod-ca-central-1.ally.ac
• Avrupa veri merkezi: prod-eu-central-1.ally.ac
• Singapur veri merkezi: prod-ap-southeast-1.ally.ac
• Avustralya veri merkezi: prod-ap-southeast-2.ally.ac

Yetkilendirme: OAuth bearer belirteci.

Parametreler: İsteğe bağlı filtreler veya sıralama seçenekleri.

İstek Metni: Yok

Yanıt:

{ 
    "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": "İşleniyor", 
        "from": 1 
    } 
} 

Yöntem: Sorunlar

HTTP isteği: GET 
https:// [Bölge]/api/v2/clients/[Ally İstemci Kimliği]/reports/overall 

[Ally İstemci Kimliği] yerine Ally kimliğinizi girin. Kimliğinizi bilmiyorsanız talep etmek için bir destek bileti oluşturabilirsiniz.

[Bölge] yerine ise kurumunuza ait Ally ortamının barındırıldığı bölgeye göre şunlardan birini girin:

• ABD veri merkezi: prod.ally.ac
• Kanada veri merkezi: prod-ca-central-1.ally.ac
• Avrupa veri merkezi: prod-eu-central-1.ally.ac
• Singapur veri merkezi: prod-ap-southeast-1.ally.ac
• Avustralya veri merkezi: prod-ap-southeast-2.ally.ac

Yetkilendirme: OAuth bearer belirteci

Parametreler: İsteğe bağlı filtreler veya sıralama seçenekleri.

İstek Metni: Yok

Yanıt:

{ 
    "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": "İşleniyor", 
        "from": 1 
    } 
} 

Burada;

• Data: Sonuçların veri kümesini içerir.
• Meta veriler:
  • To: Verilerin getirileceğini kayıttır ve bunun değeri, "ofset" + "limit" toplamına veya toplama sonucu "toplam"ı aşıyorsa "toplam"a eşittir.
  • From: Verilerin başlatılacağı kayıttır ve bunun değeri, "ofset" + 1'dir.
  • Total: LMS örneğinde Ally tarafından değerlendirilen kursların toplam sayısıdır.

Ofset: Kaydın başladığı yer

• İlk satır, ofset = 0'a karşılık gelir,
• Ofset < 0 olduğunda, kullanıcı, 400 hatası alır - [Geçersiz değer (parametre=ofset, ileti=Böyle bir veri yok)],
• (ofset >= toplam) olduğunda, kullanıcı, 400 hatası alır - [Geçersiz değer (parametre=ofset, ileti=Böyle bir veri yok)]

Limit: Ofsetten başlanarak kaç kaydın alınacağıdır

• (limit < 1) olduğunda, kullanıcı, 400 hatası alır - [Geçersiz değer (parametre=limit, ileti=Limit, sınırların dışında)]
• (limit > 10.000) olduğunda kullanıcı, 400 hatası alır - [Geçersiz değer (parametre=limit, ileti=Limit, sınırların dışında)]
• (ofset < toplam ve ofset + limit > toplam) olduğunda, sizin için arka planda sınırı değiştiririz ve son değere (toplam) ulaşılana kadar veri alınmaya devam eder

Filtreler ve sıralama seçenekleri

Uç nokta yanıtları URL'de filtrelenebilir. Bu bölümde, kullanılabilecek seçenekler açıklanmaktadır:

Sıralama seçenekleri

Sonuçları bir ölçütü göz önünde bulundurarak artan veya azalan düzende sıralanmış olarak görüntülemek isteyip istemediğinizi tanımlayabilirsiniz. Sıralama seçeneği eklemenizi gerektiren durumlarda, sıralama parametresini aşağıda açıklandığı gibi eklemeniz gerekir:

endpoint-url?sort=<Sıralama parametresi değeri>

Burada; <Sıralama parametresi değeri> ifadesi, aşağıdaki parametre değerlerinden herhangi biri olabilir:

Parametre değerleri, büyük/küçük harfe duyarlıdır ve aynı anda yalnızca tek bir sıralama seçeneği kullanılabilir.

Varsayılan olarak, sonuçlar, artan düzende sıralanır. Farklı bir düzen belirlemek isterseniz şu sıralama düzeni parametresini ekleyebilirsiniz:

endpoint-url?sort=<Sıralama parametresi değeri>&order=<Sıralama düzeni değeri>

Burada, <Sıralama düzeni değeri> şunlardan biri olabilir: asc veya desc

Örnek:

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

Filtreleme seçenekleri

Seçilen ölçütlere göre daha az veya sınırlı sayıda yanıt almak için filtreleme seçeneklerini kullanabilirsiniz. Bir filtreleme seçeneği eklemenizi gerektiren durumlarda, filtreleme parametresini aşağıda açıklandığı şekilde eklemeniz gerekir:

Filtre Parametreleri (işleçsiz)

endpoint-url?<Filtre Parametresi>=<değer>

Filtre Parametreleri (işleçli)

endpoint-url?<Filtre Parametresi>=<İşleç>:<değer>

Burada;

• <Filtre Parametresi>: Daha küçük bir sonuç kümesi elde etmeyi sağlayan filtreleme parametresi. Aşağıdaki tablodaki desteklenen parametreler listesine başvurabilirsiniz.
• <İşleç>: Filtreleme amacıyla "eşittir", "eşit değildir" gibi bir işleç kullanmanız gerekir.
• <değer>: Filtrede kullanılan değer.

Parametre değerleri büyük/küçük harfe duyarlıdır.

Desteklenen İşleçler

Aşağıdaki tablo, alan türüne göre desteklenen işleçleri içerir:

Örnek:

Aşağıdaki örnek, adının içinde "testler" anahtar sözcüğü geçen tüm kursları alır:

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

Birden fazla filtre kullanma

İki koşul arasına "&" karakterini ekleyerek sıralama ve filtreleme seçeneklerini aynı uç nokta URL'sinde birlikte kullanabilirsiniz. Örneğin, Ally'ın etkinleştirildiği kurslardan kurs adında "test" anahtar sözcüğü geçen ve genel puanın %90'dan küçük olduğu tüm kursları almak istediğinizi varsayalım. URL şöyle görünür:

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

İki filtreleme seçeneğini de kullanabilirsiniz. Örneğin, genel puanı %10 ile %70 arasında olan tüm kursları elde etmeniz gerektiğini varsayalım:

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