Iniciando os trabalhos com o WS do Moodle 2.0

Caso ache que este tutorial é muito extenso e tenha ideia do que deve ser feito, você pode seguir o resumo sugerido no link: http://www.carlosdelfino.eti.br/ead/admin/settings.php?section=webservicesoverview, não se esqueça de substituir a parte do link "http://www.carlosdelfino.eti.br/ead/" para refletir sua instalação.

Para iniciar os trabalhos no WS é necessário ativa-lo acessando a seção "Administração do Site", e ir até "Opções Avançadas", como estou usando uma instalação já totalmente traduzida todas as minhas opções e menus estão em portugues, se tiver alguma dificuldade verifique se o idioma selecionado é o Português Brasil, qualquer dúvida pode entrar em contato pelo e-mail O endereço de e-mail address está sendo protegido de spambots. Você precisa ativar o JavaScript enabled para vê-lo. , veja as telas abaixo:

Após ter selecionado a tela "Opções Avançadas", role  a janela até encontrar a opção "Habilitar serviços web (web services) enablewebservices" como exibido na próxima tela:

Após marcar a caixa de seleção você deve rolar a tela até o fim e salvar a sua configuração para que entrem em vigor.

Lembre-se: Você so deve ativar o serviço de WS do Moodle 2.0 se realmente precisar, já que, está abrindo uma porta de acesso ao seu servidor, e mais um recurso para ser gerenciado.

Ativando os protocolos que irá trabalhar

Para evitar problemas de segurança, o Moodle 2.0 pede que sejam ativados os protocolos conforme sua demanda, na versão 2.1.2 há 4 protocolos WebService disponíveis:

1. AMF
2. REST
3. SOAP
4. XML-RPC

No "Sistema Aula" estaremos usando apenas os Protocolos Rest para a versão VB (VisualBasic) e SOAP para a versão WEB (PHP). Portanto ative apenas esta duas opções para isto vá na seção "Administração do Site", "Plugins", "Serviços WEB", "Gerenciar Protocolos", cada protocolo é listado apresentando seu nome, versão, se está ativo () ou não (), um link para desinstalação como exibido na imagem ao lado.

O processo de criação do Usuário

Para uso do WebService é importante ter-se um usuário especifico que atue como Administrador do Site, este usuário terá as abilidades de um administrador, porem não será usado diretamente, apenas pelo sistema de WebService.

Você deve criar um usuário para que seja o representante do WebServer no Moodle. Há pessoas que usam a própria conta do administrador para esta representação, porem eu prefiro a opção de termos um usuário especializado, assim sabemos pelos Logs e envio de mensagens exatamente a origem do problema, caso ocorra.

Criando um Novo Papel

Você pode criar um novo usuário como sendo gerente do site diretamente adotando o papel "Manager" ou então você pode criar um novo papel para ele, eu particularmente sugiro criar um novo papel  chamado "Web Service", herdando de "Manager" assim é fácil gerrir mais tarde, as atribuidos o que se deseja remover deste papel. 

Para isto vá na seção "Administração do Site", "Opções Avançadas", "Permissões" e em seguida clique em "Definir Funções".

Conforme a tela abaixo:

Digite o campo nome "Web Services", em nome breve "Web Services", na descrição sugiro: "Novo Papel WebSErvice para uso dos usuários que representam o serviços web do site." 

Na caixa de seleção "Role Archetype" selecione ARCHETYPE: Manager.

A não ser que tenha certeza do que está fazendo não altere nenhuma outra opção neste momento.

Salve o novo papel, e em seguida clique no botão "Reconfigurar com o padrão original" para ter certeza que o novo papel está idêntico ao papel "Manager". Observe que algumas Ações/Capabilities serão selecionadas caso estejam fora da configuração padrão, e se tiver a necessidade de personalizar o papel, veja o próximo passo.

Agora clique no botão "Editar" e faça as alterações que julgar necessário, porem certifique-se que as seguintes opções estão selecionadas conforme os protocolos que deseja usar: 

• AMF
  webservcie/amf:use
• REST
  webservcie/rest:use
• SOAP
  webservcie/soap:use
• XML-RPC
  webservcie/xmprpc:use

Certifique-se também que na opção "Context types where this role may be assigned" apenas a opção "Sistema" está selecionada, já que este usuário será usado apenas no contexto do sistema.

Criando um Usuário 

Vá na seção "Administração do Site", novamente, em seguida: "Usuários", "Contas", "Acrescentar novo usuário", preencha o formulário com os dados do novo usuário, lembre-se que este usuário será um administrador do site, então deve ter uma senha compatível com seu papel, e também deve ter uma conta de e-mail que deve ser verificada periodicamente, você pode usar um aliase para a conta de e-mail do administrador do site, veja isto com seu provedor de e-mail.

Já que este usuário será somente utilizado para WebService, selecione como processo de autenticação como sendo "Autenticação Autenticação do WebService".

Já os demais parâmetros podem e devem ser preenchidos como se fosse um usuário comum e conforme a política da instituição, procurando deixar o máximo de campos preenchido, lembre-se de preencher o campo Descrição explicando de forma bem declarativa o qual a função deste usuário no sistema, e não utilize este usuário para outras funções além do WebService.

Atribuindo o Papel correto ao Usuário

Nosso usuário ainda é um usuário comum, portanto é preciso dar-lhe um papel para que possa atuar adequadamente no moodle, agora vamos ver como faremos.

Para tanto basta irmos a seção "Administração do site", "Usuários", "Permissões" e finalmente "Designar funções globais do sistema", na lista de papeis que é exibida, similar a apresentada abaixo, selecione o papel criado para este fim, apenas clicando em seu nome.

Em seguida será exibida uma nova janela, com duas caixas de seleção a esquerda os nomes dos usuários que atuam com este papel e a direita os usuários disponíveis para atribuição, veja uma tela similar ao lado.

É importante observar que é possível termos mais de um usuário configurados para atuarem com este papel, apesar de ser desnecessário, porem pode ser útil se vier a ter diversos parceiros acessando seu site. Assim Cada um poderá ter seu próprio usuário com seus dados e e-mail de contato.

Também é possível ter papeis diferenciados para cada usuário ou grupo de usuário, a varias combinações possíveis, basta usar a criatividade.

Chegando as Habilidades do Usuário Criado

Bem fechando esta etapa, agora podemos usar o recurso de verificação de habilidades, para confirmar se o usuário criado está realmente apto a ser o usuário responsável pela gestão do WebService, para esta fase inicial, o WebService deve ter as seguintes habilidades confirmadas como já citado, porem no decorrer deste tutorial outras habilidades poderão ser necessárias então sempre recorra a esta ferramenta se achar necessário checa-las.

Para executar tal tarefa, vá em "Administração do site", "Usuários", "Permissões" e finalmente clique em "Verificar permissões do sistema". Será apresentado a lista dos usuários do site, caso haja muitos usuários use a caixa de busca para encontrar o usuário "Web Service", selecione-o e clique no botão "Mostrar permissões para este usuário"

na próxima tela as seguintes habilidades devem estar autorizadas conforme os protocolos que serão utilizados, como já citado:

• AMF
  webservcie/amf:use
• REST
  webservcie/rest:use
• SOAP
  webservcie/soap:use
• XML-RPC
  webservcie/xmprpc:use

Lembre-se outras habilidades poderão ser adicionadas. Mais adiante.

Bem agora vamos a criação do que é chamado EndPoint do WebService. Cada WebService pode ter um EndPoint, que representa um grupo de mensagens e operações que podem ser utilizadas pelo usuário autorizado no sistema, no Moodle cada EndPoint é nomeado e dado a ele um grupo de funções chamado de "Serviços Externos".

Criando um Novo Serviço Externo

Um serviço externo pode ser acessado por qualquer usuário ou por um grupo de usuários especifico, além de uma faixa de IPs pre-determinada, e será nesta página que iremos configurar e nomear este "Serviço Externo", neste tutorial iremos chamar de "SistemaAula".

Para acessar esta configuração vá em "Administração do Site", "Plugins", "Serviços da Web" e finalmente clique em "Serviços externos" uma página com o conteúdo ao lado será exibida.

Nesta página clique no link "Acrescentar" e lhe será apresentado uma nova página onde deverá informar o novo nome do "Serviço Externo", no nosso caso "SistemaAula", selecione a caixa Ativo, e também selecione a caixa "Apenas Usuários Autorizados", desta forma ao se criar o serviço ele já estará ativo e somente os usuários autorizados serão liberados para acesso.

Clique no botão "Adicionar Serviço" e será exibido uma nova página onde lhe será dada a opção para verificar quais as funções serão disponibilizadas, como ainda não adicionamos nenhuma, esta página está vazia.

Adicionando Funções ao Serviço Externo

Para cada serviço externo criado, você deve selecionar um grupo de funções que deseja disponibilizar, isto é bom porque facilita a gerência dos serviços conforme quem irá usa-lo, você pode por exemplo criar um serviço externo para a Secretaria da instituição administrar através de seu sistema de gestão acadêmico, e pode criar outro serviço externo para uso de um professor que deseja controlar a matricula, notas e frequência de seus alunos com seu pequeno sistema de gestão criado em Python, Perl ou PHP em sua residência.

No nosso WebService para o SistemaAula iremos selecionar algumas funções que já temos instaladas próprias do Sistema Aula.

Para as compatíveis se existir basta substituir o termo sistemaaula_ por moodle_ se não tiver a extensão do sistema aula, mas lembre-se que neste caso a compatibilidade de integração com o Sistema Aula será quebrada.

As funções são:

Para manipulação de Cursos:

• sistemaaula_course_create_cources
• sistemaaula_course_get_cources

Envio de mensagens

• sistemaaula_mensage_send_instantmensages

Manipulação de usuários

• sistemaaula_user_create_users
• sistemaaula_user_update_users
• sistemaaula_user_get_users_by_id
• sistemaaula_user_delete_users

Matrícula e informações relacionadas

• sistemaaula_enrol_get_enrolled_users
• sistemaaula_enrol_manual_enrol_users

Agora selecione as funções acima uma a uma mantendo a tecla [CTRL] precionada, assim poderá adicionar mais de uma função de uma única vez, mas nada impede que retorne mais de uma vez a esta tela para adicionar novas funções. Após selecionar todas as funções desejadas, clique no botão "Adicionar funções".

Observe atentamente a nova página exibida, você terá uma tabela com as seguintes colunas, "Função", "Descrição", "Capacidades Exigidas" e "Editar".

Na coluna Função, infelizmente somente as funções nativas do WebService do Moodle são apresentadas suas descrições, uma vez que esta descrição é inserida diretamente no código de configuração do WebService.

A coluna "Capacidades Exigidas" é a mais importante, já que lista as habilidades que são necessários aos usuários que serão autorizados a ter acesso ao WebService. Portanto observe atentamente se o papel possui as habilidades conforme listado abaixo, caso negativo é fundamental adicionar tais habilidades. Utilize do processo apresentado na seção "Checando as Habilidades do Usuário Criado" para verificar se o usuário que deseja usar é qualificado para esta função quando investido do papel criado. Para adicionar novas habilidades visite a seção "Criando um Novo Papel" e veja o procedimento.

Habilidades/Capacidades Exigidas por Função do Sistema Aula

Para manipulação de Cursos:

• sistemaaula_course_create_cources
  • moodle/course:create
  • moodle/course:visibility

• sistemaaula_course_get_cources
  • moodle/course:visibility

Envio de mensagens

• sistemaaula_mensage_send_instantmensages
  • moodle/site:sendmessage

Manipulação de usuários

• sistemaaula_user_create_users
  • moodle/user:create

• sistemaaula_user_update_users
  • moodle/user:update
• sistemaaula_user_get_users_by_id
• sistemaaula_user_delete_users
  • moodle/user:delete

Matrícula e informações relacionadas

• sistemaaula_enrol_get_enrolled_users
• sistemaaula_enrol_manual_enrol_users
  • enrol/manual:enrol

Autorizando o Acesso ao Serviço

Agora que o Serviço externo foi criado e as funções necessárias foram adicionadas a ele, é o momento de darmos os acesso adequado a ele. Para esta liberação você precisar já ter criado o usuário e atribuído o papel adequadamente com as devidas habilidades como descrito acima.

Você não é obrigado a especificar os usuários que são autorizados a acessar o serviço já que quando criar o Token de acesso este é criado indicando no mínimo o usuário e o "Serviço Externo" que ele representa. Mas se desejar ter uma maior segurança, você pode escolher os usuários autorizados.

Para selecionar o usuário que será autorizado a acessar este WebService vá em "Administração do Site", "Plugins", Serviços da Web" e Clique em "Serviços Externos"

O "Serviços Externo" criado acima deve ser listado, usamos o nome: "SistemaAula", na coluna "Usuários" clique em Usuários Autorizados na linha correspondente ao serviço. Uma nova página será exibida com duas caixas de seleção, uma listando os usuários autorizados e outros passivos de autorização. Entre elas há dois botões, "Acrescentar" e "Remover". Ao se selecionar um usuário passivo de autorização pode-se usar o botão "Acrescentar", já se selecionarmos na caixa a esquerda um usuário autorizado podemos usar o botão "Remover" para tirar seu acesso.

Uma vez adicionado ou removido, a alteração é imediatamente salva no servidor.

Na caixa após o texto "Alterar configurações para os usuários autorizados", é listado novamente os usuários que estão autorizados e a relação de habilidades/capacidades faltantes para estes atuarem neste WebServices.

Nesta mesma lista é possível clicar no nome do usuário e indicar também qual IP pode ser usado para acesso ao serviço por este usuário, e qual o prazo de validade do serviço, lembre-se de clicar na caixa de seleção "ativar" para que o prazo passe a ter valor. 

Criando o Token de Autorização e Autenticação de Acesso ao Serviço

O acesso ao "Serviço Externo" é identificado pelo token que gerência a autorização e autentica o usuário, este token também auxiliar o acesso as informações como IP e prazo de acesso ao "Serviço Externo" se estiverem definido.

Para criar o "Token de Acesso" vá em "Administração do site", "Plugins", "Serviços da Web" e Clique em "Manage Tokens"

Será apresentado uma lista de tokens caso exista, caso contrário será listado apenas o link "Acrescentar", ao clicar neste link será apresentado a página com uma lista de usuários, caso seja muito grande poderá usar a caixa de busca para filtrar, abaixo a lista de serviços disponíveis, o IP que poderá ter acesso, e os combos para selecionar a data de prazo para este token.

Após selecionar o usuário e serviço que são obrigatórios, e opcionalmente os demais dados, basta salvar clicando no botão "Salvar Mudanças". Será gerado o Token de acesso que irá representar estas informações, este Token deverá ser enviado ao cliente/parceiro para que este utilize na URL.

A utilização do WebService será tratado em um novo artigo evitando que este fique muito grande.

portanto fique atento, logo logo estarei postando aqui o link para o novo artigo como consumir um WebService no MOODLE, enquanto isto visite o link: https://github.com/FullService/Exemplos-Moodle---WebService, neste link existem alguns exemplos de consumo do WebService do Moodle usando PHP simples.

Qualquer duvida podem ser enviadas para O endereço de e-mail address está sendo protegido de spambots. Você precisa ativar o JavaScript enabled para vê-lo. .