Os pontos de extremidade incluídos na API de relatórios são privados e não vêm com uma política de depreciação no momento. O Anthology Ally pode alterar ou atualizar esses pontos de extremidade dependendo das nossas estratégias ou de versões futuras.
Analise a documentação técnica a seguir para saber como configurar e personalizar adequadamente os pontos de extremidade. Verifique como integrar a API do Ally a uma ferramenta externa de relatórios para ter mais orientação.
Métodos disponíveis
A API do Ally para relatórios tem dois métodos. A seção a seguir os descreve:
| Método | URL | Tipo de solicitação HTTP | Descrição |
| Geral | https://[região]/api/v2/clients/[Código de cliente do Ally]/reports/overall | Obter | Por padrão, esse método retorna um conjunto de dados com informações sobre o curso, WYSIWYG, além das pontuações e dos tipos de arquivos incluídos em cada curso a partir da instância LMS, independentemente de o Ally estar habilitado ou não. |
| Problemas | https://[região]/api/v2/clients/[Código de cliente do Ally]/reports/issues | Obter | Por padrão, este método retorna um conjunto de dados com as informações relacionadas a todos os problemas de acessibilidade que ocorrem em cada curso, incluídos na instância do LMS, independentemente de o Ally estar habilitado ou não. |
Substitua o [Código de cliente do Ally] pelo seu código do Ally. Se você não souber seu código, crie um tíquete de suporte para solicitá-lo.
Substitua [Região] dependendo da região em que o ambiente do Ally da sua instituição estiver hospedado:
- Centro de dados dos EUA: prod.ally.ac
- Centro de dados do Canadá: prod-ca-central-1.ally.ac
- Centro de dados da Europa: prod-eu-central-1.ally.ac
- Centro de dados de Singapura: prod-ap-southeast-1.ally.ac
- Centro de dados da Austrália: prod-ap-southeast-2.ally.ac
As informações acima podem variar dependendo do LMS. Você pode consultar a definição da coluna na Documentação de relatório do curso para cada LMS:
Resposta do status HTTP
A API do Ally inclui um campo de status nos metadados da seguinte maneira:
- Status 200 — Êxito: sua solicitação foi recebida com êxito e o conjunto de dados solicitado faz parte da resposta.
- Status 202 — Em processamento: sua solicitação foi recebida com êxito, mas o conjunto de dados está em preparação e ainda não está disponível. Repita a solicitação após algum tempo (recomenda-se pelo menos um minuto).
- Status 401 — Não autorizado: o código de cliente do Ally ou o código de autorização não estão corretos.
- Status 400 — Solicitação incorreta: o URL tem um nome de parâmetro inválido, por exemplo, uma opção de filtro, um operador ou um valor desconhecido. Analise a sintaxe do URL. Lembre-se de que algumas das opções de filtragem e classificação diferenciam maiúsculas e minúsculas.
Documentação de métodos
Método: Geral
Solicitação HTTP: GET
https:// [Região]/api/v2/clients/[Código de cliente do Ally]/reports/overall
Substitua o [Código de cliente do Ally] pelo seu código do Ally. Se você não souber seu código, crie um tíquete de suporte para solicitá-lo.
Substitua [Região] dependendo da região em que o ambiente do Ally da sua instituição estiver hospedado:
- Centro de dados dos EUA: prod.ally.ac
- Centro de dados do Canadá: prod-ca-central-1.ally.ac
- Centro de dados da Europa: prod-eu-central-1.ally.ac
- Centro de dados de Singapura: prod-ap-southeast-1.ally.ac
- Centro de dados da Austrália: prod-ap-southeast-2.ally.ac
Autorização: código do portador do OAuth.
Parâmetros: Filtros opcionais ou opções de classificação.
Corpo da solicitação: Nenhum
Resposta:
{
"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
}
}
Método: Problemas
Solicitação HTTP: GET
https:// [Região]/api/v2/clients/[Código de cliente do Ally]/reports/overall
Substitua o código [Código de cliente do Ally] pelo seu código do Ally. Se você não souber seu código, crie um tíquete de suporte para solicitá-lo.
Substitua [Região] dependendo da região em que o ambiente do Ally da sua instituição estiver hospedado:
- Centro de dados dos EUA: prod.ally.ac
- Centro de dados do Canadá: prod-ca-central-1.ally.ac
- Centro de dados da Europa: prod-eu-central-1.ally.ac
- Centro de dados de Singapura: prod-ap-southeast-1.ally.ac
- Centro de dados da Austrália: prod-ap-southeast-2.ally.ac
Autorização: código do portador do OAuth
Parâmetros: filtros opcionais ou opções de classificação.
Corpo da solicitação: nenhum
Resposta:
{
"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
}
}
Em que:
- Dados: contém o conjunto de dados dos resultados.
- Metadados:
- Para: registro para o qual os dados serão obtidos, é "deslocamento" + "limite" ou "total" se a soma exceder "total".
- De: registro a partir do qual os dados começarão, é "deslocamento" + 1.
- Total: número total de cursos considerados pelo Ally na instância do LMS.
Deslocamento — a partir do qual o registro começa
- A primeira linha é deslocada = 0,
- Quando deslocamento < 0, o usuário recebe o erro 400 — [Valor inválido (parâmetro=deslocamento, mensagem=Os dados não existem)],
- Quando (deslocamento >= total) =>, o usuário recebe o erro 400 — [Valor inválido (parâmetro=deslocamento, mensagem=Os dados não existem)]
Limite — quantos registros são recuperados a partir do deslocamento
- Quando (limite < 1), o usuário recebe o erro 400 — [Valor inválido (parâmetro=limite, mensagem=Limite fora das fronteiras)]
- Quando (limite > 10.000), o usuário recebe o erro 400 — [Valor inválido (parâmetro=limite, mensagem=Limite fora dos limites)]
- Quando (deslocamento < total && deslocamento + limite > total), alteramos o limite em segundo plano para você e os dados serão recuperados até o último (total)
Filtros e opções de classificação
As respostas do ponto de extremidade podem ser filtradas no URL. Esta seção descreve as opções disponíveis:
Opções de classificação
Você pode definir se deseja exibir os resultados classificados em ordem crescente ou decrescente conforme um critério. Se você precisar adicionar uma opção de classificação, adicione o parâmetro de classificação conforme descrito abaixo:
endpoint-url?sort=<Valor do parâmetro de classificação>
Em que <Valor do parâmetro de classificação> pode ser qualquer um dos valores de parâmetro a seguir:
| Valor do parâmetro | Descrição | Compatível com | Exemplo |
| courseName | Classifica pelo nome do curso, por exemplo, Introdução à Química (courseCode não é válido) | Pontos de extremidade gerais e de problemas | endpoint-url?sort=courseName |
| código do curso | Classifica por código do curso, por exemplo, 123456 (geralmente é um número inteiro) | Pontos de extremidade gerais e de problemas | endpoint-url?sort=courseId |
| termId | Classifique pelo código do período. Por exemplo, Soma | Pontos de extremidade gerais e de problemas | endpoint-url?sort=termId |
| termName | Classifica pelo nome do período, por exemplo, Primeiro semestre | Pontos de extremidade gerais e de problemas | endpoint-url?sort=termName |
| overallScore | Classifica pela pontuação geral de acessibilidade de cada curso. | Somente ponto de extremidade geral. | endpoint-url?sort=overallScore |
| filesScore | Classifica os resultados pela pontuação do arquivo de cada curso. | Somente ponto de extremidade geral. | endpoint-url?sort=filesScore |
| wysiwygScore | Classifica os resultados pela pontuação WYSIWYG de cada curso. | Ponto de extremidade geral e disponível apenas no Ally para LMS. | endpoint-url?sort= wysiwygScore |
| webPagesScore | Classifica os resultados pela pontuação da página da web de cada domínio. | Ponto de extremidade geral e disponível apenas no Ally para sites e WCM. | endpoint-url?sort= webPagesScore |
Os valores de parâmetro diferenciam maiúsculas e minúsculas e somente uma opção de classificação pode ser usada por vez.
Por padrão, os resultados são classificados em ordem crescente. Se quiser definir uma ordem diferente, você pode adicionar o parâmetro de ordem:
endpoint-url?sort=<Valor do parâmetro de classificação>&order=<Valor da ordem>
Em que <Valor da ordem> pode ser: asc ou desc
Exemplo:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Opções de filtragem
Você pode usar opções de filtragem para obter respostas menores ou reduzidas com base nos critérios selecionados. Se precisar adicionar uma opção de filtragem, adicione o parâmetro de filtragem conforme descrito abaixo:
Parâmetros do filtro (sem operador)
| Nome do parâmetro do filtro | Descrição | Compatível com |
| allyEnabled | Você pode obter os cursos em que o Ally está ativo O valor é verdadeiro ou falso | Pontos de extremidade gerais e de problemas |
| departmentId | Filtrar pelo código do departamento | Pontos de extremidade gerais e de problemas |
| departmentName | Filtrar pelo nome do departamento, por exemplo, Engenharia | Pontos de extremidade gerais e de problemas |
| termId | Filtrar pelo código do período | Pontos de extremidade gerais e de problemas |
| termName | Filtrar pelo nome do período, por exemplo, Primeiro semestre | Pontos de extremidade gerais e de problemas |
| código do curso | Filtre pelo código ou curso, por exemplo, 123456 (geralmente é um número inteiro) | Pontos de extremidade gerais e de problemas |
| courseName | Filtrar pelo nome de um curso. Por exemplo, Introdução à Química (courseCode não é válido) | Pontos de extremidade gerais e de problemas |
endpoint-url?<Parâmetro do filtro>=<valor>
Parâmetros do filtro (com operador)
endpoint-url?<Parâmetro do filtro>=<Operador>:<valor>
Em que:
- <Parâmetro do filtro>: Parâmetro de filtragem para obter um conjunto menor de resultados. Você pode consultar os parâmetros compatíveis na tabela abaixo.
- <Operador>: Você deve usar um operador para filtrar, como igual, não igual.
- <valor>: Valor usado no filtro.
| Nome do parâmetro do filtro | Tipo de campo | Operadores compatíveis | Descrição | Compatível com |
| allyEnabled | Booliano | eq, ne | Você pode obter os cursos em que o Ally está ativo O valor é verdadeiro ou falso. | Pontos de extremidade gerais e de problemas |
| courseName | Sequência de caracteres | eq, ne, co, nc, sw | Filtrar pelo nome de um curso. Por exemplo, Introdução à Química (courseCode não é válido) | Pontos de extremidade gerais e de problemas |
| código do curso | Sequência de caracteres | eq, ne, co, nc, sw | Filtrar pelo código ou curso. Por exemplo, 123456 (geralmente é um número inteiro) | Pontos de extremidade gerais e de problemas |
| termId | Sequência de caracteres | eq, ne, co, nc, sw | Filtrar pelo código do período. | Pontos de extremidade gerais e de problemas |
| termName | Sequência de caracteres | eq, ne, co, nc, sw | Filtrar pelo nome do período, por exemplo, Primeiro semestre | Pontos de extremidade gerais e de problemas |
| overallScore | Número | eq, ne, le, lt, ge, gt | Você pode filtrar por uma pontuação geral, por exemplo, Cursos com uma pontuação igual a 90% | Ponto de extremidade geral e em todas as soluções Ally: LMS, sites e WCM. |
| filesScore | Número | eq, ne, le, lt, ge, gt | Você pode filtrar pela pontuação dos arquivos, por exemplo, Cursos com uma pontuação de arquivos igual a 90% | Ponto de extremidade geral e em todas as soluções Ally: LMS, sites e WCM. |
| wysiwygScore | Número | eq, ne, le, lt, ge, gt | Você pode filtrar pela pontuação WYSIWYG, por exemplo, Cursos com uma pontuação WYSIWYG igual a 90% | Ponto de extremidade geral e disponível apenas no Ally para LMS. |
| webPagesScore | Número | eq, ne, le, lt, ge, gt | Você pode filtrar pela pontuação de um domínio, por exemplo, Páginas da web com uma pontuação igual a 90%. | Ponto de extremidade geral e disponível apenas no Ally para sites ou WCM. |
Os valores de parâmetro diferenciam maiúsculas e minúsculas.
Operadores compatíveis
A tabela a seguir contém os operadores compatíveis com base no tipo de campo:
| Tipo de campo | Operador | Descrição |
| Sequência de caracteres | eq | É igual |
| Sequência de caracteres | ne | Não é igual |
| Sequência de caracteres | co | Contém palavra-chave |
| Sequência de caracteres | nc | Não contém a palavra-chave |
| Sequência de caracteres | sw | Começa com a palavra-chave |
| Número | eq | É igual |
| Número | ne | Não é igual |
| Número | le | Menor ou igual |
| Número | lt | Menor que |
| Número | ge | Maior ou igual |
| Número | gt | Maior que |
Exemplo:
O exemplo a seguir recupera todos os cursos que contenham a palavra-chave "tests" no nome do curso:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Como usar vários filtros
Você pode combinar as opções de classificação e filtragem no mesmo URL do ponto de extremidade adicionando o caractere "&" entre as duas condições. Por exemplo, digamos que você queira recuperar todos os cursos que contêm a palavra-chave "test" no nome do curso em que o Ally está habilitado e que tenha pontuação geral inferior a 90%. O URL seria assim:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
Você também pode usar duas opções de filtragem. Por exemplo, digamos que você precise obter todos os cursos que tenham uma pontuação geral entre 10% e 70%:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7
