Construir um Serviço RESTful no CICS com PHP

Página 4 de 10  Opções de documento Código de amostra Classificar este tutorial Ajude-nos a melhorar este conteúdo

Informações Básicas de REST no CA1S

Manipuladores de Eventos RESTful no SupportPac CA1S

Visão Geral

O WebSphere sMash introduz um conjunto de convenções que simplificam a criação de serviços da Web RESTful (para obter informações adicionais, consulte a documentação do WebSphere sMash em Recursos). O SupportPac CA1S adota um subconjunto destas convenções. Elas são descritas detalhadamente na documentação do CA1S (consulte Recursos) mas, para resumir:

• O CA1S pode ser configurado para tratar pedidos em alguns caminhos como RESTful. Em uma instalação padrão do CA1S, isto se aplica a caminhos em /ca1s/resources
• Quando um pedido nesse tipo de caminho é processado, as informações sobre o recurso direcionado são derivadas do URI da seguinte forma:

http://<host>/ca1s/resources/<resourceName>[/<resourceID>[/<…more/resource/info…>]]
             

• É consultado um script do manipulador de recursos que corresponde ao nome do recurso. O mecanismo PHP executará esse script, em seguida, tentará invocar um método específico no script, dependendo do método de HTTP do pedido e se o URI contém um identificador após o nome do recurso.

A Tabela 5 mostra o mapeamento do tipo de pedido de HTTP para o método que será invocado, assumindo que o recurso é denominado 'book':

Os scripts do manipulador de recursos não precisam implementar todos os métodos mostrados na Tabela 5. Se um método não for localizado para um determinado evento, ocorrerá um erro. Os manipuladores de eventos mais comumente implementados são para os eventos que correspondem às operações List, Create, Retrieve, Update e Delete ("LCRUD") no recurso, conforme realçado em negrito na Tabela 5.

Exemplo

O exemplo mostrado na Listagem 6 imprime uma cadeia diferente para cada evento:

<?php
class book {
	function onList() {
	  echo 'LIST all books!';
	}
	
	function onCreate() {
	  echo 'CREATE a book!';
	}
	
	function onRetrieve() {
	  echo 'RETRIEVE a book!';
	}
	
	function onUpdate() {
	  echo 'UPDATE a book!';
	}
	
	function onDelete() {
	  echo 'DELETE a book!';
	}	
}
?>
               

Para tentar, copie o script acima para seu sistema CICS em ca1s/work/resources/book.php (observe que o nome da classe declarada no script deve corresponder ao nome do arquivo de script). Em seguida, acesse-o com diferentes métodos de HTTP, com e sem um identificador no URI, usando um cliente REST, como o complemento Poster para Firefox. Você verá que os manipuladores de eventos serão acionados conforme apropriado. Por exemplo:

Os manipuladores de eventos não estão sendo invocados?

Confirme se os seguintes são todos idênticos (todos eles devem representar o nome do recurso):

• o primeiro componente de caminho do URI do pedido após o prefixo 'ca1s/resources/'
• o nome do arquivo do script do manipulador de recursos até a extensão .php
• o nome da classe definida no script

Voltar para parte superior

Acessando Dados do Pedido com zget()

Os scripts podem acessar vários atributos do pedido de entrada usando a função zget() , que é construída no CA1S. Os exemplos incluem:

• O corpo do pedido de entrada como uma cadeia, transcodificado da codificação do pedido para a codificação de tempo de execução de PHP:

$data = zget('/request/input/transcoded');

• Parâmetros de cadeia de consulta (bem como os parâmetros POST e PUT, se eles forem codificados para formulário):

		$value = zget('/request/params/<paramName>');
             

• O ID do recurso solicitado, conforme especificado no URI de entrada.

		$id = zget('/request/params/<resourceName>Id');

• A parte do URI após o ID do recurso, se disponível:

		$data = zget('/event/pathInfo');
            

Para experimentar zget(), modifique o método book::onUpdate() no book.php da seguinte forma:

function onUpdate() {
  $id = zget('/request/params/bookId');
  $data = zget('/request/input/transcoded');
  echo "You attempted to update book $id with data $data";
}

Em seguida, acesse um recurso do book específico com um pedido PUT para acionar o evento de atualização.

A função zget() é baseada no recurso de Contexto Global no WebSphere sMash (consulte Recursos). Uma descrição das funções completas fornecidas por zget() no CA1S e suas diferenças comparadas com a versão no WebSphere sMash está disponível na documentação do CA1S. Também é possível usar os mecanismos padrão do PHP para acessar dados do pedido, tais como, o $_GET superglobal, o fluxo de entrada php:// e outros.

Voltar para parte superior

Usando JSON como o Formato de Troca de Dados do Serviço

O REST ajuda a definir uma interface simples e consistente para expor um recurso como um serviço, mas não impõe um formato para os dados de entrada e saída do serviço —esta decisão é tomada pelo implementador. JSON é uma opção popular, porque é simples, legível por humanos e suportada por uma grande variedade de linguagens do lado do cliente e do servidor.

Codificando Variáveis de PHP em Dados de JSON

A listagem de código a seguir mostra como um manipulador onRetrieve() enviaria um recurso do book codificado como uma cadeia JSON. Observe que, neste exemplo, para simplificar, os detalhes do book são codificados permanentemente no manipulador. Na próxima seção, você verá como recuperar essas informações do programa de biblioteca COBOL.

function onRetrieve() {
  $id = zget('/request/params/bookId');
  // ... establish that book with ID $id is Heart of Darkness ...
  $book['title'] = 'Heart of Darkness';
  $book['author'] = 'Joseph Conrad';
  echo json_encode($book);
}

O corpo de resposta retornado de um pedido GET para um URI do membro como /ca1s/resources/book/10 conteria:

{"author":"Joseph Conrad","title":"Heart of Darkness"}

Decodificando Dados de JSON em

De forma semelhante, aqui é mostrado como um manipulador onCreate() processaria dados de entrada no pedido que são codificados como JSON. Mais uma vez, para simplificar, apenas foi efetuado dump dos dados decodificados; em um caso do mundo real, usaríamos os dados para criar um novo recurso.

function onCreate() {
  $inputData = zget('/request/input/transcoded');
  $book = json_decode($inputData, true);
  // ... Criar novo recurso de book com base nos dados em $book ...
  // Efetuar dump da variável para ilustrar:
  var_dump($book);
}
             

Enviar dados como

{"author":"Margaret Atwood","title":"Oryx and Crake"}

no corpo de um pedido POST para o URI de coleta ca1s/resources/book retornaria:

array(2) {
  ["author"]=>
  string(15) "Margaret Atwood"
  ["title"]=>
  string(14) "Oryx and Crake"
}

Voltar para parte superior

	Página 4 de 10