O Esqueleto para Consumir o WebService do Moodle 2.0

Para facilitar este tutorial vou criar um pequeno esqueleto com algumas funções básicas que irão reduzir o nosso trabalho.

É importante observar que o consumo do WebService é composto de dois conjuntos de informações, o primeiro grupo refere-se a informações de acesso ao servidor, onde será informados o endereço do servidor como a URL completa para acesso ao WebService, o Token que autentica e autoriza o acesso. Já o segundo grupo são as informações do serviço solicitado como o nome da função/mensagem solicitada ao WebService e os parâmetros necessário para seu funcionamento.

Para compor as informações do primeiro grupo identifique então:

• IP ou domínio onde está instalado seu servidor, em nosso caso estará instalado em "www.carlosdelfino.eti.br"
• Diretório de Instalação do Servidor, para nos estará em "ead"
• e obtenha o token a ser utilizado.

O nosso código inicial para o script ficará assim:

Bem vamos ver agora o código que irá ser usado em todas as chamadas ao WebService, este código será criado em uma arquivo que ficará no diretório "lib" com o nome "esqueletowebservice.php":

 A função acima está em sua primeira versão, e seu objetivo é bem simples apenas demonstrar como é chamado o WebService para o protocolo SOAP, em novos Tutoriais poderá ser melhorada para demonstrar outros protocolos.

Os parâmetros da função são todos obrigatórios com exceção do ultimo "$service" que por padrão é "soap", já que iremos focar neste protocolo. o primeiro é o nome do host, em seguida o diretório de instalação em nosso caso "ead", depois o token que dá acesso ao serviço externo, segue o nome da ação que será chamada e finalmente um array que contem os parâmetros do serviço que será chamado.

Usando o Esqueleto proposto

O código proposto neste tutorial é apenas um exemplo e deve ser melhorado conforme suas necessidades, este codigo conforme proposto não resolve todos os problemas que podem vir a ocorrer num ambiente de produção. 

Agora vamos ver o segundo grupo de informações necessário para que possamos consumir o WebService este grupo de informações está codificado para uso com SOAP porem seus requisitos são validos para qualquer protocolo, seja REST, XML-RPC ou mesmo AMF.

No caso do REST ou XML-RPC você poderá usar uma biblioteca como a CURL.php para auxiliar a conversão do código para o formato adequado, mantendo esta codificação, veja nos tutorias específicos como isto deve ser feito.

Na imagem acima, é apresentado o código que cria o objeto que representa o usuário que será adicionado com a a chamada da ação "sistemaaula_user_create_users", observe então que a variável "$action" terá este valor. nos comentários do código estão o tipo esperado seu tamanho e se são campos obrigatórios ou não. 

Há alguns campos como por exemplo: "lang" que possuem um tamanho bem além do necessário, e estão fora do padrão, esperava-se neste campo a observância do padrão ISO-639, porem ainda não encontramos uma boa justificativa para o MOODLE não segui-lo. Também temos o campo "country" que pode os códigos em maiúculo. 

Tratando as Exceções do WebServices do Moodle

As operações/mensagens do WebService do Moodle retornam erros pouco úteis na versão atual, isto também não tem uma justificativa muito clara, estamos pesquisando sobre o assunto em em breve estaremos publicando uma solução melhor, porem as funções que desenvolvemos para integração com o SistemaAula são mais amigáveis em seus erros, retornando mensagens mais claras e objetivas, como serão mostradas abaixo

Não trataremos aqui erros específicos do WebService, mas apenas das operações do moodle.

No WebService do SistemaAula as exceções são do tipo "moodle_exception", no lugar de "invalid_parameter_excpetion", retornando assim de forma mais declarativa e podendo sofrer intervenção da internacionalização.

Erro ao se tentar inserir um usuário duplicado.

No WebService do Moodle usando a operação padrão moodle_user_create_users, quando se tenta inteserir um usuário duplicado recebe a exceção "invalid_parameter_excepion" que na versão atual do MOODLE 2.0 não retorna uma mensagem muito útil e clara que a exceção é devido ao fato do usuário ser duplicado, mas usando nosso WebService com a operação sistemaaula_user_create_users a exceção retornada é moodle_exception, e a mensagem que acompanha atualmente é: "sistemaaula/username_already_exists", esta mensagem vem neste formato devido ao fato da internacionalização não ter encontrado o modulo sistemaaula, porem quando este vier a ser implementado e instalado a mensagem será alterada e será mais declarativa.

Veja uma parte do texto extraido da conversão do objeto SoapFalt impresso conforme a função print_r do PHP:

....

        )

    [previous:Exception:private] => 

    [faultstring] => sistemaaula/username_already_exists

    [faultcode] => Receiver

)